From 70910414e64cb0c497c941b0c98aef14fd88bfa0 Mon Sep 17 00:00:00 2001
From: Valery Kharseko <vharseko@3a-systems.ru>
Date: Tue, 02 Jul 2024 09:36:10 +0000
Subject: [PATCH] Restore missing docs (#350)
---
opendj-doc-generated-ref/src/main/docbkx/shared/man-dbtest.xml | 147
opendj-doc-generated-ref/src/main/docbkx/admin-guide/preface.xml | 66
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-virtual-attrs-collective-attrs.xml | 546
opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif-template.xml | 452
opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-account.xml | 372
opendj-doc-generated-ref/src/main/docbkx/shared/itemizedlist-download.xml | 53
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-tuning.xml | 515
opendj-doc-generated-ref/src/main/docbkx/shared/man-uninstall.xml | 303
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifmodify.xml | 148
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-data-repl.png | 0
opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-cli.xml | 826
opendj-doc-generated-ref/src/main/docbkx/release-notes/index.xml | 104
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-license.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-chaining.xml | 40
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-interface-stability.xml | 138
opendj-doc-generated-ref/src/main/docbkx/shared/man-stop-ds.xml | 255
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Entries.png | 0
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-gendata.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-list-backends.xml | 118
opendj-doc-generated-ref/src/main/docbkx/shared/man-base64.xml | 174
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/resources/maven-xml.txt | 26
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-issues.xml | 207
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pwd-policy.xml | 983 +
opendj-doc-generated-ref/src/main/docbkx/shared/man-dsjavaproperties.xml | 114
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldif-diff.xml | 207
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/keystores.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-backup.xml | 358
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-backup-restore.xml | 277
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-understanding-ldap.xml | 353
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/create-vlv-index.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-resource-limits.xml | 211
opendj-doc-generated-ref/src/main/docbkx/shared/man-verify-index.xml | 160
opendj-doc-generated-ref/src/main/docbkx/shared/screen-upgrade.xml | 99
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-ldap-operations.xml | 1906 ++
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-getting-directory-info.xml | 244
opendj-doc-generated-ref/src/main/docbkx/shared/glossary.xml | 883 +
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-load-balancing.xml | 46
opendj-doc-generated-ref/src/main/docbkx/shared/man-control-panel.xml | 159
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-admin-tools.xml | 449
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-get-sdk.xml | 51
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/OpenDJ-Control-Panel.png | 0
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-update-install.xml | 94
opendj-doc-generated-ref/src/main/docbkx/shared/sec-interface-stability.xml | 33
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-replication.xml | 1520 +
opendj-doc-generated-ref/src/main/docbkx/dev-guide/preface.xml | 57
opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-lifecycle.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldappasswordmodify.xml | 318
opendj-doc-generated-ref/src/main/docbkx/shared/man-upgrade.xml | 212
opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifsearch.xml | 245
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pta.xml | 587
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-writing.xml | 468
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-support.xml | 39
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/index.xml | 99
opendj-doc-generated-ref/src/main/docbkx/install-guide/preface.xml | 74
opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-jvm-opts.xml | 85
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapmodify.xml | 397
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-svrconf.png | 0
opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/data-organization.png | 0
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-whats-new.xml | 106
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-mv-servers.xml | 281
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-referrals.xml | 160
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/standalone-repl.png | 0
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-jvmopts.png | 0
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-compatibility.xml | 77
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifdiff.xml | 165
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-ldif.xml | 211
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-monitor-repl.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-troubleshooting.xml | 983 +
opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapsearch.xml | 534
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-before-you-install.xml | 68
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-extended-ops.xml | 122
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-attrtype.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif.xml | 126
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-import-export.xml | 412
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-ports-used.xml | 101
opendj-doc-generated-ref/src/main/docbkx/shared/man-rebuild-index.xml | 329
opendj-doc-generated-ref/src/main/docbkx/shared/man-dsreplication.xml | 403
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-welcome.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-setup.xml | 345
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-controls.xml | 449
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-controls.xml | 1438 +
opendj-doc-generated-ref/src/main/docbkx/shared/man-dsconfig.xml | 5560 ++++++
opendj-doc-generated-ref/src/main/docbkx/shared/sec-joining-the-community.xml | 59
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifsearch.xml | 226
opendj-doc-generated-ref/src/main/docbkx/admin-guide/index.xml | 165
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-groups.xml | 487
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-authenticating.xml | 278
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-get-sdk.xml | 342
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-connection-handlers.xml | 1325 +
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-replopts.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-modrate.xml | 368
opendj-doc-generated-ref/src/main/docbkx/shared/man-restore.xml | 322
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-reading.xml | 553
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-i18n.xml | 56
opendj-doc-generated-ref/src/main/docbkx/shared/sec-formatting-conventions.xml | 60
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-wrong.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-account-lockout.xml | 341
opendj-doc-generated-ref/src/main/docbkx/shared/man-status.xml | 255
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml | 237
opendj-doc-generated-ref/src/main/docbkx/shared/man-start-ds.xml | 135
opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapmodify.xml | 405
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-finished.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-samba.xml | 187
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/JXplorer-dsml.png | 0
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-finished.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-setup.png | 0
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-start.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-objclass.png | 0
opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-tree.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldappasswordmodify.xml | 335
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-right.png | 0
opendj-doc-generated-ref/src/main/docbkx/dev-guide/index.xml | 105
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-feedback.xml | 124
opendj-doc-generated-ref/src/main/docbkx/install-guide/index.xml | 67
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-support.xml | 48
opendj-doc-generated-ref/src/main/docbkx/shared/man-export-ldif.xml | 350
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-change-certs.xml | 499
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-rest-operations.xml | 1273 +
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-using-the-sdk.xml | 197
opendj-doc-generated-ref/src/main/docbkx/shared/affiliation-fr.xml | 17
opendj-doc-generated-ref/src/main/docbkx/shared/man-dsframework.xml | 295
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/OpenDJ-Control-Panel.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-global-admin.png | 0
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-failover.xml | 41
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-standards.xml | 1013 +
opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifmodify.xml | 152
opendj-doc-generated-ref/src/main/docbkx/shared/man-import-ldif.xml | 419
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-indexing.xml | 800
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-file-layout.xml | 252
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-best-practices.xml | 397
opendj-doc-generated-ref/src/main/docbkx/shared/images/forgerock-opendj-logo.png | 0
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-before-you-install.xml | 275
opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-tasks.xml | 253
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapcompare.xml | 327
opendj-doc-generated-ref/src/main/docbkx/shared/sec-release-levels.xml | 33
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-feedback.xml | 91
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-simple-proxy.xml | 253
opendj-doc-generated-ref/src/main/ant/zip.xml | 1
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-server-process.xml | 183
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-rest2ldap.xml | 1243 +
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-whats-new.xml | 291
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-monitoring.xml | 989 +
opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-upgrade.xml | 185
opendj-doc-generated-ref/src/main/docbkx/shared/man-encode-password.xml | 188
opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapcompare.xml | 346
opendj-doc-generated-ref/src/main/docbkx/shared/man-searchrate.xml | 377
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-setup.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-authrate.xml | 371
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/missing-java6.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/table-filter-operators.xml | 195
opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Schema.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/man-create-rc-script.xml | 129
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapdelete.xml | 330
opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-gui.xml | 181
opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-issues.xml | 92
opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-compatibility.xml | 165
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-privileges-acis.xml | 1438 +
opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-extended-ops.xml | 342
opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-review.png | 0
opendj-doc-generated-ref/src/main/docbkx/shared/sec-accessing-doc-online.xml | 52
opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapsearch.xml | 513
opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-l10n.xml | 843 +
opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-uninstall.xml | 175
opendj-doc-generated-ref/src/main/docbkx/shared/mediaobject-fr-logo.xml | 10
opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-schema.xml | 632
165 files changed, 49,776 insertions(+), 0 deletions(-)
diff --git a/opendj-doc-generated-ref/src/main/ant/zip.xml b/opendj-doc-generated-ref/src/main/ant/zip.xml
index e9b9af4..39ddb42 100644
--- a/opendj-doc-generated-ref/src/main/ant/zip.xml
+++ b/opendj-doc-generated-ref/src/main/ant/zip.xml
@@ -6,6 +6,7 @@
<dirset dir="${basedir}/src/main/docbkx/" casesensitive="yes">
<include name="*/"/>
<exclude name="*/*/**"/>
+ <exclude name="shared"/>
</dirset>
</path>
<mapper type="flatten"/>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-controls.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-controls.xml
new file mode 100644
index 0000000..1f16425
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-controls.xml
@@ -0,0 +1,449 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-controls'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>LDAP Controls</title>
+
+ <para>Controls provide a mechanism whereby the semantics and arguments of
+ existing LDAP operations may be extended. One or more controls may be
+ attached to a single LDAP message. A control only affects the semantics of
+ the message it is attached to. Controls sent by clients are termed
+ <emphasis>request controls</emphasis>, and those sent by servers are termed
+ <emphasis>response controls</emphasis>.</para>
+
+ <para>OpenDJ software supports the following LDAP controls.</para>
+ <variablelist>
+ <varlistentry xml:id="account-usability-control">
+ <term>Account Usability Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Account usability</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8</para>
+ <para>Control originally provided by Sun Microsystems, used to determine
+ whether a user account can be used to authenticate to the directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="assertion-request-control">
+ <term>Assertion Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Assertion</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.1.12</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4528'>RFC 4528
+ - Lightweight Directory Access Protocol (LDAP) Assertion Control</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="authorization-identity-request-control">
+ <term>Authorization Identity Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Authorization identity</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.16</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc3829'>RFC 3829
+ - Lightweight Directory Access Protocol (LDAP) Authorization Identity
+ Request and Response Controls</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="authorization-identity-response-control">
+ <term>Authorization Identity Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Authorization identity</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.15</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc3829'>RFC 3829
+ - Lightweight Directory Access Protocol (LDAP) Authorization Identity
+ Request and Response Controls</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="entry-change-notification-response-control">
+ <term>Entry Change Notification Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Entry change notification</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.7</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-ietf-ldapext-psearch'
+ >draft-ietf-ldapext-psearch - Persistent Search: A Simple LDAP Change
+ Notification Mechanism</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="get-effective-rights-request-control">
+ <term>Get Effective Rights Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Get effective rights</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-ietf-ldapext-acl-model'
+ >draft-ietf-ldapext-acl-model - Access Control Model for LDAPv3</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="manage-dsait-request-control">
+ <term>Manage DSAIT Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Manage DSAIT</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.2</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc3296'>RFC 3296
+ - Named Subordinate References in Lightweight Directory Access Protocol
+ (LDAP) Directories</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="matched-values-request-control">
+ <term>Matched Values Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Matched values</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.2.826.0.1.3344810.2.3</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc3876'>RFC 3876
+ - Returning Matched Values with the Lightweight Directory Access Protocol
+ version 3 (LDAPv3)</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="noop-control">
+ <term>No-Op Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>No-op</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.4203.1.10.2</para>
+ <para>Internet-Draft: <link
+ xlink:href="http://tools.ietf.org/html/draft-zeilenga-ldap-noop-01"
+ >draft-zeilenga-ldap-noop - LDAP No-Op Control</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="password-expired-response-control">
+ <term>Password Expired Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Password expired</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.4</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy'
+ >draft-vchu-ldap-pwd-policy - Password Policy for LDAP Directories</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="password-expiring-response-control">
+ <term>Password Expiring Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Password expiring</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.5</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy'
+ >draft-vchu-ldap-pwd-policy - Password Policy for LDAP Directories</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="password-policy-response-control">
+ <term>Password Policy Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-behera-ldap-password-policy'
+ >draft-behera-ldap-password-policy - Password Policy for LDAP
+ Directories</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="permissive-modify-request-control">
+ <term>Permissive Modify Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Permissive modify</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.2.840.113556.1.4.1413</para>
+ <para>Microsoft defined this control that, "Allows an LDAP modify to work
+ under less restrictive conditions. Without it, a delete will fail if an
+ attribute done not exist, and an add will fail if an attribute already
+ exists. No data is needed in this control." (<link
+ xlink:href='http://www.alvestrand.no/objectid/1.2.840.113556.1.4.1413.html'
+ >source of quote</link>)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="persistent-search-request-control">
+ <term>Persistent Search Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.3</para>
+ <para>Internet-Draft:
+ <link xlink:href='http://tools.ietf.org/html/draft-ietf-ldapext-psearch'
+ >draft-ietf-ldapext-psearch - Persistent Search: A Simple LDAP Change
+ Notification Mechanism</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="post-read-request-control">
+ <term>Post-Read Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Post-read</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.1.13.2</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4527'>RFC 4527
+ - Lightweight Directory Access Protocol (LDAP) Read Entry Controls</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="post-read-response-control">
+ <term>Post-Read Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Post-read</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.1.13.2</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4527'>RFC 4527
+ - Lightweight Directory Access Protocol (LDAP) Read Entry Controls</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="pre-read-request-control">
+ <term>Pre-Read Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Pre-read</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.1.13.1</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4527'>RFC 4527
+ - Lightweight Directory Access Protocol (LDAP) Read Entry Controls</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="pre-read-response-control">
+ <term>Pre-Read Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Pre-read</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.1.13.1</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4527'>RFC 4527
+ - Lightweight Directory Access Protocol (LDAP) Read Entry Controls</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="proxied-authorization-v1-request-control">
+ <term>Proxied Authorization v1 Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Proxied authorization</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.12</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-weltman-ldapv3-proxy-04'
+ >draft-weltman-ldapv3-proxy-04 - LDAP Proxied Authorization Control</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="proxied-autorization-v2-request-control">
+ <term>Proxied Authorization v2 Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Proxied authorization</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.18</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4370'>RFC 4370
+ - Lightweight Directory Access Protocol (LDAP) Proxied Authorization
+ Control</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="public-changelog-exchange-control">
+ <term>Public Changelog Exchange Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Public changelog exchange</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.26027.1.5.4</para>
+ <para>OpenDJ specific, for using the bookmark cookie when reading
+ the external change log.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="server-side-sort-request-control">
+ <term>Server Side Sort Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Server side sort</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.2.840.113556.1.4.473</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc2891'>RFC 2891
+ - LDAP Control Extension for Server Side Sorting of Search Results</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="server-side-sort-response-control">
+ <term>Server Side Sort Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Server side sort</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.2.840.113556.1.4.474</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc2891'>RFC 2891
+ - LDAP Control Extension for Server Side Sorting of Search Results</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="simple-paged-results-control">
+ <term>Simple Paged Results Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Simple paged results</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.2.840.113556.1.4.319</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc2696'>RFC 2696
+ - LDAP Control Extension for Simple Paged Results Manipulation</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="subentries-request-controls">
+ <term>Subentries Request Controls</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Subentries</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.4203.1.10.1</para>
+ <para>RFC: <link
+ xlink:href='http://tools.ietf.org/html/rfc3672'
+ >Subentries in the Lightweight Directory Access Protocol (LDAP)</link></para>
+ <para>Object Identifier: 1.3.6.1.4.1.7628.5.101.1</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-ietf-ldup-subentry'
+ >draft-ietf-ldup-subentry - LDAP Subentry Schema</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="subtree-delete-request-control">
+ <term>Subtree Delete Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Subtree delete</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.2.840.113556.1.4.805</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-armijo-ldap-treedelete'
+ >draft-armijo-ldap-treedelete - Tree Delete Control</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="virtual-list-view-request-control">
+ <term>Virtual List View Request Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Virtual list view (browsing)</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.9</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv'
+ >draft-ietf-ldapext-ldapv3-vlv - LDAP Extensions for Scrolling View
+ Browsing of Search Results</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="virtual-list-view-response-control">
+ <term>Virtual List View Response Control</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP controls</primary>
+ <secondary>Virtual list view (browsing)</secondary>
+ </indexterm>
+ <para>Object Identifier: 2.16.840.1.113730.3.4.10</para>
+ <para>Internet-Draft: <link
+ xlink:href='http://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv'
+ >draft-ietf-ldapext-ldapv3-vlv - LDAP Extensions for Scrolling View
+ Browsing of Search Results</link></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-extended-ops.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-extended-ops.xml
new file mode 100644
index 0000000..3be25a9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-extended-ops.xml
@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-extended-ops'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>LDAP Extended Operations</title>
+
+ <para>Extended operations allow additional operations to be defined for
+ services not already available in the protocol</para>
+
+ <para>OpenDJ software supports the following LDAP extended operations.</para>
+
+ <variablelist>
+ <varlistentry xml:id="cancel-extended-request">
+ <term>Cancel Extended Request</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP extended operations</primary>
+ <secondary>Cancel</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.1.8</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc3909'>RFC 3909
+ - Lightweight Directory Access Protocol (LDAP) Cancel Operation</link>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="get-connection-id-extended-request">
+ <term>Get Connection ID Extended Request</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP extended operations</primary>
+ <secondary>Get Connection ID</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.26027.1.6.2</para>
+ <para>OpenDJ extended operation to return the connection ID of the
+ associated client connection. This extended operation is intended for OpenDJ
+ internal use.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="password-modify-extended-request">
+ <term>Password Modify Extended Request</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP extended operations</primary>
+ <secondary>Password modify</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.4203.1.11.1</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc3909'>RFC 3062
+ - LDAP Password Modify Extended Operation</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="password-policy-state-extended-operation">
+ <term>Password Policy State Extended Operation</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP extended operations</primary>
+ <secondary>Password policy state</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.26027.1.6.1</para>
+ <para>OpenDJ extended operation to query and update password policy state
+ for a given user entry. This extended operation is intended for OpenDJ
+ internal use.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="start-transport-layer-security-extended-request">
+ <term>Start Transport Layer Security Extended Request</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP extended operations</primary>
+ <secondary>StartTLS</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.1466.20037</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4511'>RFC 4511
+ - Lightweight Directory Access Protocol (LDAP): The Protocol</link></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="who-am-i-extended-request">
+ <term>Who am I? Extended Request</term>
+ <listitem>
+ <indexterm>
+ <primary>LDAP extended operations</primary>
+ <secondary>What am I?</secondary>
+ </indexterm>
+ <para>Object Identifier: 1.3.6.1.4.1.4203.1.11.3</para>
+ <para>RFC: <link xlink:href='http://tools.ietf.org/html/rfc4532'>RFC 4532
+ - Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation</link>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-file-layout.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-file-layout.xml
new file mode 100644
index 0000000..6f9715d
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-file-layout.xml
@@ -0,0 +1,252 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-file-layout'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>File Layout</title>
+
+ <para>OpenDJ software installs and creates the following files and
+ directories. The following list is not necessarily exhaustive.</para>
+ <indexterm><primary>File layout</primary></indexterm>
+ <indexterm><primary>Installed files</primary></indexterm>
+ <variablelist>
+ <varlistentry>
+ <term><filename>QuickSetup.app</filename></term>
+ <listitem>
+ <para>Mac OS X GUI for installing OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>Uninstall.app</filename></term>
+ <listitem>
+ <para>Mac OS X GUI for removing OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>bak</filename></term>
+ <listitem>
+ <para>Directory for saving backup files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>bat</filename></term>
+ <listitem>
+ <para>Windows command-line tools and control panel</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>bin</filename></term>
+ <listitem>
+ <para>UNIX/Linux/Mac OS X command-line tools and control panel</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>changelogDb</filename></term>
+ <listitem>
+ <para>JE backend data for the external change log when using
+ replication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>classes</filename></term>
+ <listitem>
+ <para>Directory added to the <literal>CLASSPATH</literal> for OpenDJ,
+ permitting individual classes to be patched</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config</filename></term>
+ <listitem>
+ <para>OpenDJ server configuration and schema, PKI stores, LDIF generation
+ templates, resources for upgrade</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/MakeLDIF</filename></term>
+ <listitem>
+ <para>Templates for use with the <command>make-ldif</command> LDIF
+ generation tool</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/config.ldif</filename></term>
+ <listitem>
+ <para>LDIF representation of current OpenDJ server config</para>
+ <para>Use the <command>dsconfig</command> command to edit OpenDJ server
+ configuration.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/java.properties</filename></term>
+ <listitem>
+ <para>JVM settings for OpenDJ server and tools</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/schema</filename></term>
+ <listitem>
+ <para>OpenDJ directory server LDAP schema definition files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/tasks.ldif</filename></term>
+ <listitem>
+ <para>Data used by task scheduler backend so that scheduled tasks and
+ recurring tasks persist after server restart</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/tools.properties</filename></term>
+ <listitem>
+ <para>Default settings for command-line tools</para>
+ <para>Use as a template when creating an
+ <filename>~/.opendj/tools.properties</filename> file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/upgrade</filename></term>
+ <listitem>
+ <para>Resources used by the upgrade command to move to the next version
+ of OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>config/wordlist.txt</filename></term>
+ <listitem>
+ <para>List of words used to check password strength</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>db</filename></term>
+ <listitem>
+ <para>JE backend data for backends that you create</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>example-plugin.zip</filename></term>
+ <listitem>
+ <para>Sample OpenDJ plugin code. Custom plugins are meant to be installed
+ in <filename>lib/extensions</filename>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>import-tmp</filename></term>
+ <listitem>
+ <para>Used when importing data into OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>instance.loc</filename></term>
+ <listitem>
+ <para>Pointer to OpenDJ on the file system, useful in installations where
+ the program files are separate from the server instance files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>ldif</filename></term>
+ <listitem>
+ <para>Directory for saving LDIF export files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>legal-notices</filename></term>
+ <listitem>
+ <para>License information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>lib</filename></term>
+ <listitem>
+ <para>Scripts and libraries needed by OpenDJ and added to the
+ <literal>CLASSPATH</literal> for OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>lib/extensions</filename></term>
+ <listitem>
+ <para>File system directory to hold your custom plugins</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>locks</filename></term>
+ <listitem>
+ <para>Directory to hold lock files used when OpenDJ is running to prevent
+ backends from accidentally being used by more than one server process</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>logs</filename></term>
+ <listitem>
+ <para>Access, errors, audit, and replication logs</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>logs/server.pid</filename></term>
+ <listitem>
+ <para>Contains the process ID for the server when OpenDJ is running</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>setup</filename></term>
+ <listitem>
+ <para>UNIX setup utility</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>setup.bat</filename></term>
+ <listitem>
+ <para>Windows setup utility</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>uninstall</filename></term>
+ <listitem>
+ <para>UNIX utility for removing OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>uninstall.bat</filename></term>
+ <listitem>
+ <para>Windows utility for removing OpenDJ</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>upgrade</filename></term>
+ <listitem>
+ <para>UNIX utility for upgrading OpenDJ by pointing to the new .zip</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>upgrade.bat</filename></term>
+ <listitem>
+ <para>Windows utility for upgrading OpenDJ by pointing to the new .zip</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-interface-stability.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-interface-stability.xml
new file mode 100644
index 0000000..ce534dc
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-interface-stability.xml
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+ <appendix xml:id="appendix-interface-stability"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Release Levels & Interface Stability</title>
+
+ <para>This appendix includes ForgeRock definitions for product release levels
+ and interface stability.</para>
+
+ <itemizedlist>
+ <para>In addition to the indications concerning interface stability that
+ you find in the documentation, review the following information about OpenDJ
+ user and application programming interfaces.</para>
+
+ <listitem>
+ <para>Client tools — <command>ldap*</command>, <command>ldif*</command>,
+ and <command>*rate</command> commands — are Evolving.</para>
+ </listitem>
+
+ <listitem>
+ <para>The following classes, interfaces, and methods in the <link
+ xlink:show="new" xlink:href="${serverJavadocBase}">OpenDJ directory server
+ APIs</link> are Evolving.</para>
+
+ <itemizedlist>
+ <listitem><para><literal>org.forgerock.opendj.ldap.Connections#newInternalConnection</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.Connections#newInternalConnectionFactory</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.Connections#newServerConnectionFactory</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.FutureResult</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPClientContext</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPListener</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPListenerOptions</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.MemoryBackend</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.RequestContext</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.RequestHandler</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.RequestHandlerFactory</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.ServerConnection</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.ServerConnectionFactory</literal></para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>The following classes and interfaces in the <link xlink:show="new"
+ xlink:href="${sdkJavadocBase}">OpenDJ LDAP SDK APIs</link> are Evolving.</para>
+
+ <itemizedlist>
+ <listitem><para><literal>org.forgerock.opendj.ldap.ConnectionSecurityLayer</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPUrl</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.requests.BindRequest</literal>, including sub-types and especially SASL sub-types</para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.schema.MatchingRuleImpl</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.schema.SchemaValidationPolicy</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.schema.SyntaxImpl</literal></para></listitem>
+ </itemizedlist>
+
+ <para>The following methods are Deprecated.</para>
+
+ <itemizedlist>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPListenerOptions#getTCPNIOTransport</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPListenerOptions#setTCPNIOTransport</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPOptions#getTCPNIOTransport</literal></para></listitem>
+ <listitem><para><literal>org.forgerock.opendj.ldap.LDAPOptions#setTCPNIOTransport</literal></para></listitem>
+ </itemizedlist>
+
+ <para>The class <literal>org.forgerock.opendj.ldap.CoreMessages</literal> is
+ Internal.</para>
+ </listitem>
+
+ <listitem>
+ <para>For all Java APIs, <literal>com.*</literal> packages are Internal.</para>
+ </listitem>
+
+ <listitem>
+ <para>The configuration, user, and application programming interfaces for
+ RESTful access over HTTP to directory data are Evolving. This includes
+ interfaces exposed for the HTTP Connection Handler, its access log, and also
+ the REST LDAP gateway.</para>
+ </listitem>
+
+ <listitem>
+ <para>Text in log messages should be considered Internal. Log message IDs are
+ Evolving.</para>
+ </listitem>
+
+ <listitem>
+ <para>The default content of <literal>cn=schema</literal> (directory server
+ LDAP schema) is Evolving.</para>
+ </listitem>
+
+ <listitem>
+ <para>The monitoring interface <literal>cn=monitor</literal> for LDAP and
+ the monitoring interface exposed by the JMX Connection Handler are
+ Evolving.</para>
+ </listitem>
+
+ <listitem>
+ <para>Newly Deprecated and Removed interfaces are identified in the
+ <citetitle>Release Notes</citetitle> chapter, <link xlink:show="new"
+ xlink:href="release-notes#chap-compatibility"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>OpenDJ
+ Compatibility</citetitle></link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Interfaces that are not described in released product documentation
+ should be considered Internal/Undocumented. For example, the LDIF
+ representation of the server configuration, <filename>config.ldif</filename>,
+ should be considered Internal.</para>
+ </listitem>
+ </itemizedlist>
+
+ <xinclude:include href="../shared/sec-release-levels.xml" />
+ <xinclude:include href="../shared/sec-interface-stability.xml" />
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-l10n.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-l10n.xml
new file mode 100644
index 0000000..68350f5
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-l10n.xml
@@ -0,0 +1,843 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-l10n'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Localization</title>
+
+ <para>OpenDJ software stores data in UTF-8 format. It enables you to store
+ and to search for attribute values according to a variety of language
+ specific locales. OpenDJ software is also itself localized for a smaller
+ variety of languages.</para>
+
+ <section xml:id="supported-languages">
+ <title>OpenDJ Languages</title>
+ <indexterm><primary>Languages</primary></indexterm>
+ <para>OpenDJ <?eval ${docTargetVersion}?> software has been localized
+ in the following languages.</para>
+
+ <itemizedlist>
+ <listitem><para>French</para></listitem>
+ <listitem><para>German</para></listitem>
+ <listitem><para>Japanese</para></listitem>
+ <listitem><para>Simplified Chinese</para></listitem>
+ <listitem><para>Spanish</para></listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Certain messages have also been translated into Catalan, Korean,
+ Polish, and Traditional Chinese. Some error messages including messages
+ labeled SEVERE and FATAL are provided only in English.</para>
+ </note>
+ </section>
+
+ <section xml:id="supported-locales">
+ <title>Directory Support For Locales and Language Subtypes</title>
+ <indexterm><primary>Locales</primary></indexterm>
+ <para>OpenDJ software supports the following locales, with their
+ associated language and country codes, and their collation order
+ object identifiers. Locale support depends on the underlying Java
+ Virtual Machine.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Albanian</term>
+ <listitem>
+ <para>Code tag: sq</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.127.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic</term>
+ <listitem>
+ <para>Code tag: ar</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.3.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Algeria)</term>
+ <listitem>
+ <para>Code tag: ar-DZ</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.6.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Bahrain)</term>
+ <listitem>
+ <para>Code tag: ar-BH</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.5.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Egypt)</term>
+ <listitem>
+ <para>Code tag: ar-EG</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.7.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Iraq)</term>
+ <listitem>
+ <para>Code tag: ar-IQ</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.9.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Jordan)</term>
+ <listitem>
+ <para>Code tag: ar-JO</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.10.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Kuwait)</term>
+ <listitem>
+ <para>Code tag: ar-KW</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.11.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Lebanon)</term>
+ <listitem>
+ <para>Code tag: ar-LB</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.12.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Libya)</term>
+ <listitem>
+ <para>Code tag: ar-LY</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.13.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Morocco)</term>
+ <listitem>
+ <para>Code tag: ar-MA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.14.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Oman)</term>
+ <listitem>
+ <para>Code tag: ar-OM</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.15.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Qatar)</term>
+ <listitem>
+ <para>Code tag: ar-QA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.16.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Saudi Arabia)</term>
+ <listitem>
+ <para>Code tag: ar-SA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.17.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Sudan)</term>
+ <listitem>
+ <para>Code tag: ar-SD</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.18.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Syria)</term>
+ <listitem>
+ <para>Code tag: ar-SY</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.19.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Tunisia)</term>
+ <listitem>
+ <para>Code tag: ar-TN</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.20.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (United Arab Emirates)</term>
+ <listitem>
+ <para>Code tag: ar-AE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.4.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Arabic (Yemen)</term>
+ <listitem>
+ <para>Code tag: ar-YE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.21.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Belarusian</term>
+ <listitem>
+ <para>Code tag: be</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.22.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Bulgarian</term>
+ <listitem>
+ <para>Code tag: bg</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.23.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Catalan</term>
+ <listitem>
+ <para>Code tag: ca</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.25.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Chinese</term>
+ <listitem>
+ <para>Code tag: zh</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.143.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Chinese (Simplified) (China)</term>
+ <listitem>
+ <para>Code tag: zh-CN</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.144.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Chinese (Traditional) (Hong Kong)</term>
+ <listitem>
+ <para>Code tag: zh-HK</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.145.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Chinese (Traditional) (Taiwan)</term>
+ <listitem>
+ <para>Code tag: zh-TW</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.148.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Croatian</term>
+ <listitem>
+ <para>Code tag: hr</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.87.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Czech</term>
+ <listitem>
+ <para>Code tag: cs</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.26.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Danish</term>
+ <listitem>
+ <para>Code tag: da</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.27.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dutch</term>
+ <listitem>
+ <para>Code tag: nl</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.105.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dutch (Belgium)</term>
+ <listitem>
+ <para>Code tag: nl-BE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.106.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dutch (Netherlands)</term>
+ <listitem>
+ <para>Code tag: nl-NL</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.105.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English</term>
+ <listitem>
+ <para>Code tag: en</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.34.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (Australia)</term>
+ <listitem>
+ <para>Code tag: en-AU</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.35.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (Canada)</term>
+ <listitem>
+ <para>Code tag: en-CA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.36.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (Great Britain)</term>
+ <listitem>
+ <para>Code tag: en-GB</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.37.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (India)</term>
+ <listitem>
+ <para>Code tag: en-IN</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.40.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (Ireland)</term>
+ <listitem>
+ <para>Code tag: en-IE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.39.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (New Zealand)</term>
+ <listitem>
+ <para>Code tag: en-NZ</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.42.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (South Africa)</term>
+ <listitem>
+ <para>Code tag: en-ZA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.46.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>English (United States)</term>
+ <listitem>
+ <para>Code tag: en-US</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.34.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Estonian</term>
+ <listitem>
+ <para>Code tag: et</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.69.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Finnish</term>
+ <listitem>
+ <para>Code tag: fi</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.74.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>French</term>
+ <listitem>
+ <para>Code tag: fr</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.76.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>French (Belgium)</term>
+ <listitem>
+ <para>Code tag: fr-BE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.77.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>French (Canada)</term>
+ <listitem>
+ <para>Code tag: fr-CA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.78.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>French (France)</term>
+ <listitem>
+ <para>Code tag: fr-FR</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.76.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>French (Luxembourg)</term>
+ <listitem>
+ <para>Code tag: fr-LU</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.80.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>French (Switzerland)</term>
+ <listitem>
+ <para>Code tag: fr-CH</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.79.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>German</term>
+ <listitem>
+ <para>Code tag: de</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.28.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>German (Austria)</term>
+ <listitem>
+ <para>Code tag: de-AT</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.29.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>German (Germany)</term>
+ <listitem>
+ <para>Code tag: de-DE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.28.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>German (Luxembourg)</term>
+ <listitem>
+ <para>Code tag: de-LU</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.32.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>German (Switzerland)</term>
+ <listitem>
+ <para>Code tag: de-CH</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.31.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Greek</term>
+ <listitem>
+ <para>Code tag: el</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.33.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Hebrew</term>
+ <listitem>
+ <para>Code tag: he</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.85.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Hungarian</term>
+ <listitem>
+ <para>Code tag: hu</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.88.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Icelandic</term>
+ <listitem>
+ <para>Code tag: is</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.91.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Italian</term>
+ <listitem>
+ <para>Code tag: it</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.92.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Italian (Switzerland)</term>
+ <listitem>
+ <para>Code tag: it-CH</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.93.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Japanese</term>
+ <listitem>
+ <para>Code tag: ja</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.94.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Korean</term>
+ <listitem>
+ <para>Code tag: ko</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.97.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Latvian</term>
+ <listitem>
+ <para>Code tag: lv</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.101.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Lithuanian</term>
+ <listitem>
+ <para>Code tag: lt</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.100.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Macedonian</term>
+ <listitem>
+ <para>Code tag: mk</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.102.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Norwegian</term>
+ <listitem>
+ <para>Code tag: no</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.107.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Norwegian (Bokmål)</term>
+ <listitem>
+ <para>Code tag: no-NO</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.107.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Norwegian (Nynorsk)</term>
+ <listitem>
+ <para>Code tag: no-NO-NY</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.108.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Polish</term>
+ <listitem>
+ <para>Code tag: pl</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.114.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Portuguese</term>
+ <listitem>
+ <para>Code tag: pt</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.115.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Portuguese (Brazil)</term>
+ <listitem>
+ <para>Code tag: pt-BR</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.116.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Portuguese (Portugal)</term>
+ <listitem>
+ <para>Code tag: pt-PT</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.115.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Romanian</term>
+ <listitem>
+ <para>Code tag: ro</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.117.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Russian</term>
+ <listitem>
+ <para>Code tag: ru</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.118.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Russian (Russia)</term>
+ <listitem>
+ <para>Code tag: ru-RU</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.118.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Serbian</term>
+ <listitem>
+ <para>Code tag: sr</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.128.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Slovak</term>
+ <listitem>
+ <para>Code tag: sk</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.121.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Slovenian</term>
+ <listitem>
+ <para>Code tag: sl</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.122.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish</term>
+ <listitem>
+ <para>Code tag: es</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.49.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Argentina)</term>
+ <listitem>
+ <para>Code tag: es-AR</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.50.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Bolivia)</term>
+ <listitem>
+ <para>Code tag: es-BO</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.51.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Chile)</term>
+ <listitem>
+ <para>Code tag: es-CL</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.52.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Colombia)</term>
+ <listitem>
+ <para>Code tag: es-CO</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.53.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Costa Rica)</term>
+ <listitem>
+ <para>Code tag: es-CR</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.54.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Dominican Republic)</term>
+ <listitem>
+ <para>Code tag: es-DO</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.55.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Ecuador)</term>
+ <listitem>
+ <para>Code tag: es-EC</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.56.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (El Salvador)</term>
+ <listitem>
+ <para>Code tag: es-SV</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.65.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Guatemala)</term>
+ <listitem>
+ <para>Code tag: es-GT</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.57.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Honduras)</term>
+ <listitem>
+ <para>Code tag: es-HN</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.58.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Mexico)</term>
+ <listitem>
+ <para>Code tag: es-MX</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.59.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Nicaragua)</term>
+ <listitem>
+ <para>Code tag: es-NI</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.60.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Panama)</term>
+ <listitem>
+ <para>Code tag: es-PA</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.61.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Paraguay)</term>
+ <listitem>
+ <para>Code tag: es-PY</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.64.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Peru)</term>
+ <listitem>
+ <para>Code tag: es-PE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.62.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Puerto Rico)</term>
+ <listitem>
+ <para>Code tag: es-PR</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.63.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Spain)</term>
+ <listitem>
+ <para>Code tag: es-ES</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.49.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Uruguay)</term>
+ <listitem>
+ <para>Code tag: es-UY</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.67.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Spanish (Venezuela)</term>
+ <listitem>
+ <para>Code tag: es-VE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.68.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Swedish</term>
+ <listitem>
+ <para>Code tag: sv</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.129.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Swedish (Sweden)</term>
+ <listitem>
+ <para>Code tag: sv-SE</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.129.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Thai</term>
+ <listitem>
+ <para>Code tag: th</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.136.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Turkish</term>
+ <listitem>
+ <para>Code tag: tr</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.140.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Ukranian</term>
+ <listitem>
+ <para>Code tag: uk</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.141.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Vietnamese</term>
+ <listitem>
+ <para>Code tag: vi</para>
+ <para>Collation order object identifier: 1.3.6.1.4.1.42.2.27.9.4.142.1</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>OpenDJ software supports the following language subtypes.</para>
+ <indexterm><primary>Language subtypes</primary></indexterm>
+ <itemizedlist xml:id="supported-language-subtypes">
+ <listitem><para>Albanian, sq</para></listitem>
+ <listitem><para>Arabic, ar</para></listitem>
+ <listitem><para>Belarusian, be</para></listitem>
+ <listitem><para>Bulgarian, bg</para></listitem>
+ <listitem><para>Catalan, ca</para></listitem>
+ <listitem><para>Chinese, zh</para></listitem>
+ <listitem><para>Croatian, hr</para></listitem>
+ <listitem><para>Czech, cs</para></listitem>
+ <listitem><para>Danish, da</para></listitem>
+ <listitem><para>Dutch, nl</para></listitem>
+ <listitem><para>English, en</para></listitem>
+ <listitem><para>Estonian, et</para></listitem>
+ <listitem><para>Finnish, fi</para></listitem>
+ <listitem><para>French, fr</para></listitem>
+ <listitem><para>German, de</para></listitem>
+ <listitem><para>Greek, el</para></listitem>
+ <listitem><para>Hebrew, he</para></listitem>
+ <listitem><para>Hungarian, hu</para></listitem>
+ <listitem><para>Icelandic, is</para></listitem>
+ <listitem><para>Italian, it</para></listitem>
+ <listitem><para>Japanese, ja</para></listitem>
+ <listitem><para>Korean, ko</para></listitem>
+ <listitem><para>Latvian, lv</para></listitem>
+ <listitem><para>Lithuanian, lt</para></listitem>
+ <listitem><para>Macedonian, mk</para></listitem>
+ <listitem><para>Norwegian, no</para></listitem>
+ <listitem><para>Polish, pl</para></listitem>
+ <listitem><para>Portuguese, pt</para></listitem>
+ <listitem><para>Romanian, ro</para></listitem>
+ <listitem><para>Russian, ru</para></listitem>
+ <listitem><para>Serbian, sr</para></listitem>
+ <listitem><para>Slovak, sk</para></listitem>
+ <listitem><para>Slovenian, sl</para></listitem>
+ <listitem><para>Spanish, es</para></listitem>
+ <listitem><para>Swedish, sv</para></listitem>
+ <listitem><para>Thai, th</para></listitem>
+ <listitem><para>Turkish, tr</para></listitem>
+ <listitem><para>Ukranian, uk</para></listitem>
+ <listitem><para>Vietnamese, vi</para></listitem>
+ </itemizedlist>
+ </section>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-ports-used.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-ports-used.xml
new file mode 100644
index 0000000..bdf9c3c
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-ports-used.xml
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-ports-used'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Ports Used</title>
+
+ <para>OpenDJ server software uses the following TCP/IP ports by default.</para>
+
+ <!-- Protocol, port number, description (what for), on by default? -->
+ <variablelist>
+ <varlistentry xml:id="ldap-port">
+ <term>LDAP: 389 (1389)</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>389 (1389)</secondary></indexterm>
+ <para>OpenDJ directory server listens for LDAP requests from client
+ applications on port 389 by default. OpenDJ directory server uses port
+ 1389 by default for users who cannot use privileged ports. LDAP is enabled
+ by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="ldaps-port">
+ <term>LDAPS: 636 (1636)</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>636 (1636)</secondary></indexterm>
+ <para>OpenDJ directory server listens for LDAPS requests from client
+ applications on port 636 by default. OpenDJ directory server uses port
+ 1636 by default for users who cannot use privileged ports. LDAPS is not
+ enabled by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="admin-port">
+ <term>Administrative connections: 4444</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>4444</secondary></indexterm>
+ <para>OpenDJ directory server listens for administrative traffic on port
+ 4444 by default. The administration connector is enabled by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="snmp-port">
+ <term>SNMP: 161, 162</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>161</secondary></indexterm>
+ <indexterm><primary>Ports</primary><secondary>162</secondary></indexterm>
+ <para>OpenDJ directory server listens for SNMP traffic on port 161 by
+ default, and uses port 162 for traps. SNMP is not enabled by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="jmx-port">
+ <term>JMX: 1689</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>1689</secondary></indexterm>
+ <para>OpenDJ directory server listens for Java Management eXtension
+ traffic on port 1689 by default. JMX is not enabled by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="http-port">
+ <term>HTTP: 8080</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>8080</secondary></indexterm>
+ <para>OpenDJ directory server can listen for HTTP client requests to the
+ RESTful API. The default port is 8080, but HTTP access is not enabled by
+ default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="repl-port">
+ <term>Replication: 8989</term>
+ <listitem>
+ <indexterm><primary>Ports</primary><secondary>8989</secondary></indexterm>
+ <para>OpenDJ directory server listens for replication traffic
+ on port 8989 by default. Replication is not enabled by default.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-rest2ldap.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
new file mode 100644
index 0000000..bf1efc1
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-rest2ldap.xml
@@ -0,0 +1,1243 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-rest2ldap'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>REST LDAP Configuration</title>
+ <indexterm><primary>REST</primary></indexterm>
+ <indexterm><primary>HTTP</primary></indexterm>
+ <!-- This belongs in an OpenDJ reference. Ultimately this doc should
+ be generated, too, rather than written by hand. CREST-71? -->
+
+ <itemizedlist>
+ <para>OpenDJ offers two alternatives for RESTful access to directory
+ data.</para>
+
+ <listitem>
+ <para>OpenDJ directory server has an HTTP connection handler that exposes
+ the RESTful API over HTTP (or HTTPS). You configure the mapping between
+ JSON resources and LDAP entries by editing the configuration file for the
+ HTTP connection handler, by default
+ <filename>/path/to/opendj/config/http-config.json</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The OpenDJ REST LDAP gateway runs as a Servlet independent from your
+ directory service. You configure the gateway to access your directory service
+ by editing <filename>opendj-rest2ldap-servlet.json</filename> where you
+ deploy the gateway web application.</para>
+ </listitem>
+ </itemizedlist>
+
+ <variablelist>
+ <para>The JSON format configuration can hold the following configuration
+ objects. Some of the configuration settings are available only in the REST
+ LDAP gateway configuration. The order here is the order shown in the default
+ configuration file.</para>
+
+ <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ >Evolving</link></para>
+
+ <varlistentry>
+ <term>"ldapConnectionFactories" (required, gateway only)</term>
+ <listitem>
+ <para>Configures how the gateway connects to LDAP servers. This entire
+ configuration object applies only to the REST LDAP gateway.</para>
+
+ <variablelist>
+ <para>Configures at least a connection factory for unauthenticated
+ connections that are used for bind requests. By default, also configures a
+ factory for authenticated connections that are used for searches during
+ authentication and for proxied authorization operations.</para>
+
+ <para>The default configuration is set to connect to a local directory
+ server listening for LDAP connections on port 1389, authenticating as the
+ root DN user <literal>cn=Directory Manager</literal>, with the password
+ <literal>password</literal>.</para>
+
+ <varlistentry>
+ <term>"default"</term>
+ <listitem>
+ <para>Configures the unauthenticated connection factory for bind
+ operations.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>"connectionPoolSize" (optional)</term>
+ <listitem>
+ <para>The gateway creates connection pools to the primary and
+ secondary LDAP servers that maintain up to
+ <literal>connectionPoolSize</literal> connections to the
+ servers.</para>
+
+ <para>Default: 24</para>
+
+ <programlisting language="javascript">"connectionPoolSize": 24</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"connectionSecurity" (optional)</term>
+ <listitem>
+ <para>Whether connections to LDAP servers should be secured by using
+ SSL or StartTLS. The following values are supported.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"none" (default) means connections use plain LDAP and are
+ not secured.</para>
+ </listitem>
+
+ <listitem>
+ <para>"ssl" means connections are secured using LDAPS.</para>
+ </listitem>
+
+ <listitem>
+ <para>"startTLS" means connections are secured using LDAP and
+ StartTLS.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If you set "connectionSecurity", also review the
+ "trustManager" and "fileBasedTrustManager*" settings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"heartBeatIntervalSeconds" (optional)</term>
+ <listitem>
+ <para>The gateway tests its connections every
+ <literal>heartBeatIntervalSeconds</literal> seconds to detect whether
+ the connection is still alive.</para>
+
+ <para>Default: 30 (seconds)</para>
+
+ <programlisting language="javascript">"heartBeatIntervalSeconds": 30</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"fileBasedTrustManagerFile" (optional)</term>
+ <listitem>
+ <para>If "trustManager" is set to "file", then this setting
+ configures the location of the trust store file.</para>
+
+ <para>Default: "/path/to/truststore"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"fileBasedTrustManagerPassword" (optional)</term>
+ <listitem>
+ <para>If "trustManager" is set to "file", then this setting
+ specifies the trust store password.</para>
+
+ <para>Default: "password"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"fileBasedTrustManagerType" (optional)</term>
+ <listitem>
+ <para>If "trustManager" is set to "file", then this setting
+ configures the format for the data in the trust store file specified
+ by the "fileBasedTrustManagerFile" setting. Formats include the
+ following, though other implementations might be supported as well
+ depending on the Java environment.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"JKS" (default) specifies Java Key Store format.</para>
+ </listitem>
+
+ <listitem>
+ <para>"PKCS12" specifies Public-Key Cryptography Standards 12
+ format.</para>
+ </listitem>
+ </itemizedlist>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"primaryLDAPServers" (required)</term>
+ <listitem>
+ <para>The gateway accesses this array of LDAP servers before failing
+ over to the secondary LDAP servers. These might be LDAP servers in
+ the same data center for example.</para>
+
+ <programlisting language="javascript">{
+ "primaryLDAPServers": [
+ {
+ "hostname": "local1.example.com",
+ "port": 1389
+ },
+ {
+ "hostname": "local2.example.com",
+ "port": 1389
+ }
+ ]
+}</programlisting>
+
+ <para>By default, the gateway connects to the directory server
+ listening on port 1389 on the local host.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"secondaryLDAPServers" (optional)</term>
+ <listitem>
+ <para>The gateway accesses this array of LDAP servers if primary LDAP
+ servers cannot be contacted. These might be LDAP servers in the same
+ data center for example.</para>
+
+ <programlisting language="javascript">{
+ "secondaryLDAPServers": [
+ {
+ "hostname": "remote1.example.com",
+ "port": 1389
+ },
+ {
+ "hostname": "remote2.example.com",
+ "port": 1389
+ }
+ ]
+}</programlisting>
+
+ <para>No secondary LDAP servers are configured by default.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"trustManager" (optional)</term>
+ <listitem>
+ <para>If "connectionSecurity" is set to "ssl" or "startTLS", then
+ this setting configures how the LDAP servers are trusted. This
+ setting is ignored if "connectionSecurity" is set to "none".</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"file" means trust the LDAP server certificate if it is
+ signed by a Certificate Authority (CA) trusted according to the
+ file-based trust store configured with the "fileBasedTrustManager*"
+ settings.</para>
+ </listitem>
+
+ <listitem>
+ <para>"jvm" means trust the LDAP server certificate if it is signed
+ by a CA trusted by the Java environment.</para>
+ </listitem>
+
+ <listitem>
+ <para>"trustAll" (default) means blindly trust all LDAP server
+ certificates.</para>
+ </listitem>
+ </itemizedlist>
+
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"root"</term>
+ <listitem>
+ <para>Configures the authenticated connection factory.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>"inheritFrom" (optional)</term>
+ <listitem>
+ <para>Identifies the unauthenticated connection factory from which
+ to inherit settings. If this connection factory does not inherit from
+ another configuration object, then you must specify the configuration
+ here.</para>
+
+ <para>Default: "default"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"authentication" (required)</term>
+ <listitem>
+ <para>The gateway authenticates by simple bind using the credentials
+ specified.</para>
+
+ <programlisting language="javascript">{
+ "authentication": {
+ "bindDN": "cn=Directory Manager",
+ "password": "password"
+ }
+}</programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"authenticationFilter" (required)</term>
+ <listitem>
+ <para>Configures the REST LDAP authentication filter. If the configuration
+ is not present, the filter is disabled.</para>
+
+ <para>The default configuration allows HTTP Basic authentication where user
+ entries are <literal>inetOrgPerson</literal> entries expected to have
+ <literal>uid=<replaceable>username</replaceable></literal>, and to be found
+ under <literal>ou=people,dc=example,dc=com</literal>. The default
+ configuration also allows alternative, HTTP header based authentication in
+ the style of OpenIDM.</para>
+
+ <para>By default, authentication is required both for the gateway and for
+ the HTTP connection handler. When the HTTP connection handler property
+ <literal>authentication-required</literal> is set to
+ <literal>false</literal> (default: <literal>true</literal>), the HTTP
+ connection handler accepts both authenticated and unauthenticated requests.
+ All requests are subject to access control and resource limit settings in
+ the same way as LDAP client requests to the directory server. The
+ <literal>authentication-required</literal> setting can be overridden by the
+ global configuration property
+ <literal>reject-unauthenticated-requests</literal> (default:
+ <literal>false</literal>), described in the section on <link
+ xlink:show="new" xlink:href="admin-guide#restrict-clients"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Restricting
+ Client Access</citetitle></link>.</para>
+
+ <para>To protect passwords, configure HTTPS for the HTTP connection handler
+ or for the container where the REST LDAP gateway runs.</para>
+
+ <variablelist>
+ <para>The filter has the following configuration fields.</para>
+
+ <varlistentry>
+ <term>"supportHTTPBasicAuthentication"</term>
+ <listitem>
+ <para>Whether to support HTTP Basic authentication. If this is set to
+ <literal>true</literal>, then the entry corresponding to the user name
+ is found using the "searchBaseDN", "searchScope", and
+ "searchFilterTemplate" settings.</para>
+
+ <para>Default: <literal>true</literal></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"supportAltAuthentication"</term>
+ <listitem>
+ <para>Whether to allow alternative, HTTP header based authentication. If
+ this is set to <literal>true</literal>, then the headers to use are
+ specified in the "altAuthenticationUsernameHeader" and
+ "altAuthenticationPasswordHeader" values, and the bind DN is resolved
+ using the "searchFilterTemplate" value.</para>
+
+ <para>Default: <literal>true</literal></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"altAuthenticationUsernameHeader"</term>
+ <listitem>
+ <para>Specifies the HTTP header containing the username for
+ authentication when alternative, HTTP-header based authentication is
+ allowed.</para>
+
+ <para>Default: "X-OpenIDM-Username"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"altAuthenticationPasswordHeader"</term>
+ <listitem>
+ <para>Specifies the HTTP header containing the password for
+ authentication when alternative, HTTP-header based authentication is
+ allowed.</para>
+
+ <para>Default: "X-OpenIDM-Password"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"reuseAuthenticatedConnection" (gateway only)</term>
+ <listitem>
+ <para>Whether to use authenticated LDAP connections for subsequent LDAP
+ operations. If this is set to <literal>true</literal>, the gateway does
+ not need its own connection factory, nor does it need to use proxied
+ authorization for LDAP operations. Instead, it performs the operations
+ as the user on the authenticated connection.</para>
+
+ <para>Default: <literal>true</literal></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"method" (gateway only)</term>
+ <listitem>
+ <para>Specifies the authentication method used by the gateway. The
+ following values are supported.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"search-simple" (default) means the user name is resolved to
+ an LDAP bind DN by a search using the "searchFilterTemplate" value.</para>
+ </listitem>
+ <listitem>
+ <para>"sasl-plain" means the user name is resolved to an
+ authorization ID (authzid) using the "saslAuthzIdTemplate" value.</para>
+ </listitem>
+ <listitem>
+ <para>"simple" means the user name is the LDAP bind DN.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"bindLDAPConnectionFactory" (gateway only)</term>
+ <listitem>
+ <para>Identifies the factory providing connections used for bind
+ operations to authenticate users to LDAP servers.</para>
+
+ <para>Default: "default"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"saslAuthzIdTemplate" (gateway only)</term>
+ <listitem>
+ <para>Sets how to resolve the authorization ID when the authentication
+ "method" is set to "sasl-plain", substituting <literal>%s</literal>
+ in the template with the user name provided. The user name provided by
+ is DN escaped before the value is returned.</para>
+
+ <para>Default: "dn:uid=%s,ou=people,dc=example,dc=com"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"searchLDAPConnectionFactory" (gateway only)</term>
+ <listitem>
+ <para>Identifies the factory providing connections used to find
+ user entries in the directory server when the "method" is set to
+ "search-simple".</para>
+
+ <para>Default: "root"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"searchBaseDN"</term>
+ <listitem>
+ <para>Sets the base DN to search for user entries. For the gateway,
+ this applies when the "method" is set to "search-simple". This always
+ applies for the HTTP connection handler.</para>
+
+ <para>Default: "ou=people,dc=example,dc=com"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"searchScope"</term>
+ <listitem>
+ <para>Sets the search scope below the base DN such as "sub" (subtree
+ search) or "one" (one-level search) to search for user entries. For the
+ gateway, this applies when the "method" is set to "search-simple". This
+ always applies for the HTTP connection handler.</para>
+
+ <para>Default: "sub"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"searchFilterTemplate"</term>
+ <listitem>
+ <para>Sets the search filter used to find the user entry, substituting
+ <literal>%s</literal> in the template with the user name provided. The
+ user name provided by is DN escaped before the value is returned. For
+ the gateway, this applies when the "method" is set to "search-simple".
+ This always applies for the HTTP connection handler.</para>
+
+ <para>Default: "(&(objectClass=inetOrgPerson)(uid=%s))"</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"servlet" (required)</term>
+ <listitem>
+ <para>Configures how HTTP resources map to LDAP entries, and for the gateway
+ how to connect to LDAP servers and how to use proxied authorization.</para>
+
+ <para>The default gateway configuration tries to reuse authenticated
+ connections for LDAP operations, falling back to a connection authenticated
+ as root DN using proxied authorization for LDAP operations.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>"ldapConnectionFactory" (gateway only)</term>
+ <listitem>
+ <para>Specifies the connection factory used by the gateway to perform
+ LDAP operations if an authenticated connection is not passed from the
+ authentication filter according to the setting for
+ "reuseAuthenticatedConnection".</para>
+
+ <para>Default: "root"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"authorizationPolicy" (gateway only)</term>
+ <listitem>
+ <para>Specifies how to handle LDAP authorization. The following values
+ are supported.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"proxy" (default) means use proxied authorization when no
+ authenticated connection is provided for reuse, resolving the
+ authorization ID according to the setting for
+ "proxyAuthzIdTemplate".</para>
+ </listitem>
+
+ <listitem>
+ <para>"none" means do not use proxied authorization and do not reuse
+ authenticated connections, but instead use connections from the
+ factory specified in "ldapConnectionFactory".</para>
+ </listitem>
+
+ <listitem>
+ <para>"reuse" means reuse an authenticated connection passed by the
+ filter, and fail if no connection was passed by the filter.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"proxyAuthzIdTemplate" (gateway only)</term>
+ <listitem>
+ <para>Specifies the template to derive the authorization ID from the
+ security context created during authentication. Use
+ <literal>{dn}</literal> to indicate the user's bind DN or
+ <literal>{id}</literal> to indicate the user name provided for
+ authentication.</para>
+
+ <para>Default: "dn:{dn}"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"mappings"</term>
+ <listitem>
+ <para>For each collection URI such as <literal>/users</literal> and
+ <literal>/groups</literal>, you configure a mapping between the JSON
+ resource returned over HTTP, and the LDAP entry returned by the
+ directory service.</para>
+
+ <variablelist>
+ <para>Each mapping has a number of configuration elements.</para>
+
+ <varlistentry>
+ <term>"baseDN" (required)</term>
+ <listitem>
+ <para>The base DN where LDAP entries are found for this mapping.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"readOnUpdatePolicy" (optional)</term>
+ <listitem>
+ <para>The policy used to read an entry before it is deleted, or to
+ read an entry after it is added or modified. One of the following.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"controls": (default) use RFC 4527 read-entry controls to
+ reflect the state of the resource at the time the update was
+ performed.</para>
+ <para>The directory service must support RFC 4527.</para>
+ </listitem>
+
+ <listitem>
+ <para>"disabled": do not read the entry or return the resource on
+ update.</para>
+ </listitem>
+
+ <listitem>
+ <para>"search": perform an LDAP search to retrieve the entry before
+ deletion or after it is added or modified.</para>
+ <para>The JSON resource returned might differ from the LDAP entry
+ that was updated.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"useSubtreeDelete" (required)</term>
+ <listitem>
+ <para>Whether to use the LDAP Subtree Delete Request Control (OID:
+ <literal>1.2.840.113556.1.4.805</literal>) for LDAP delete operations
+ resulting from delete operations on resources.</para>
+
+ <para>Default: <literal>false</literal>. The default configuration
+ uses <literal>false</literal>.</para>
+
+ <para>Set this to <literal>true</literal> if you want this behavior,
+ if your directory server supports the control, and if clients that
+ request delete operations have access to use the control.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"usePermissiveModify" (required)</term>
+ <listitem>
+ <para>Whether to use the LDAP Permissive Modify Request Control (OID:
+ <literal>1.2.840.113556.1.4.1413</literal>) for LDAP modify operations
+ resulting from patch and update operations on resources.</para>
+
+ <para>Default: <literal>false</literal>. The default configuration
+ uses <literal>true</literal>.</para>
+
+ <para>Set this to <literal>false</literal> when using the gateway if
+ your directory server does not support the control.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"etagAttribute" (optional)</term>
+ <listitem>
+ <para>The LDAP attribute to use for multi-version concurrency control
+ (MVCC).</para>
+
+ <para>Default: "etag"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"namingStrategy" (required)</term>
+ <listitem>
+ <para>The approach used to map LDAP entry names to JSON resources. The
+ following naming strategies are supported.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>RDN and resource ID are both derived from a single user
+ attribute in the LDAP entry, as in the following example, where the
+ <literal>uid</literal> attribute is the RDN and its value is the
+ JSON resource ID.</para>
+
+ <programlisting language="javascript">{
+ "namingStrategy": {
+ "strategy": "clientDNNaming",
+ "dnAttribute": "uid"
+ }
+}</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>RDN and resource ID are derived from separate user attributes
+ in the LDAP entry, as in the following example where the RDN
+ attribute is <literal>uid</literal> but the JSON resource ID is the
+ value of the <literal>mail</literal> attribute.</para>
+
+ <programlisting language="javascript">{
+ "namingStrategy": {
+ "strategy": "clientNaming",
+ "dnAttribute": "uid",
+ "idAttribute": "mail"
+ }
+}</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>RDN is derived from a user attribute and the resource ID from
+ an operational attribute in the LDAP entry, as in the following
+ example, where the RDN attribute is <literal>uid</literal> but the
+ JSON resource ID is the value of the <literal>entryUUID</literal>
+ operational attribute.</para>
+
+ <programlisting language="javascript">{
+ "namingStrategy": {
+ "strategy": "serverNaming",
+ "dnAttribute": "uid",
+ "idAttribute": "entryUUID"
+ }
+}</programlisting>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"additionalLDAPAttributes" (optional, but necessary)</term>
+ <listitem>
+ <para>LDAP attributes to include during LDAP add operations as an
+ array of type-value lists, such as the following example.</para>
+
+ <programlisting language="javascript">{
+ "additionalLDAPAttributes": [
+ {
+ "type": "objectClass",
+ "values": [
+ "top",
+ "person",
+ "organizationalPerson",
+ "inetOrgPerson"
+ ]
+ }
+ ]
+}</programlisting>
+
+ <para>This configuration element is useful to set LDAP object classes
+ for example, which are not present in JSON resources.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"attributes" (required)</term>
+ <listitem>
+ <para>How the JSON resource fields map to attributes on LDAP
+ entries, each taking the form "<replaceable>field-name</replaceable>":
+ <replaceable>mapping-object</replaceable>. A number of
+ <replaceable>mapping-object</replaceable>s are supported.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>"constant"</term>
+ <listitem>
+ <para>Maps a single JSON attribute to a fixed value.</para>
+
+ <para>This can be useful as in the default case where each JSON
+ resource "schemas" takes the SCIM URN, and so the value is not
+ related to the underlying LDAP entries.</para>
+
+ <programlisting language="javascript">{
+ "schemas": {
+ "constant": [
+ "urn:scim:schemas:core:1.0"
+ ]
+ }
+}</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"simple"</term>
+ <listitem>
+ <para>Maps a JSON field to an LDAP attribute.</para>
+
+ <para>Simple mappings are used where the correspondence between
+ JSON fields and LDAP attributes is one-to-one.</para>
+
+ <programlisting language="javascript">{
+ "userName": {
+ "simple": {
+ "ldapAttribute": "mail",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ }
+}</programlisting>
+
+ <itemizedlist>
+ <para>Simple mappings can take a number of fields.</para>
+
+ <listitem>
+ <para>(Required) "ldapAttribute": the name of LDAP attribute.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "defaultJSONValue": the JSON value if no LDAP
+ attribute is available on the entry.</para>
+
+ <para>No default is set if this is omitted.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "isBinary": true means the LDAP attribute is
+ binary and the JSON field gets the base64-encoded value.</para>
+
+ <para>Default: <literal>false</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "isRequired": true means the LDAP attribute is
+ mandatory and must be provided to create the resource; false
+ means it is optional.</para>
+
+ <para>Default: <literal>false</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "isSingleValued": true means represent a
+ possibly multi-valued LDAP attribute as a single value; false
+ means represent it as an array of values.</para>
+
+ <para>Default: determine the representation based on the LDAP
+ schema, so SINGLE-VALUE attributes take single values, and
+ multi-valued attributes take arrays.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "writability": indicates whether the LDAP
+ attribute supports updates. This field can take the following
+ values.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"createOnly": This attribute can be set only when the
+ entry is created. Attempts to update this attribute thereafter
+ result in errors.</para>
+ </listitem>
+ <listitem>
+ <para>"createOnlyDiscardWrites": This attribute can be set only
+ when the entry is created. Attempts to update this attribute
+ thereafter do not result in errors. Instead the update value
+ is discarded.</para>
+ </listitem>
+ <listitem>
+ <para>"readOnly": This attribute cannot be written. Attempts to
+ write this attribute result in errors.</para>
+ </listitem>
+ <listitem>
+ <para>"readOnlyDiscardWrites": This attribute cannot be written.
+ Attempts to write this attribute do not result in errors.
+ Instead the value to write is discarded.</para>
+ </listitem>
+ <listitem>
+ <para>"readWrite": (default) This attribute can be set at
+ creation and updated thereafter.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"object"</term>
+ <listitem>
+ <para>Maps a JSON object to LDAP attributes.</para>
+
+ <para>This mapping lets you create JSON objects whose fields
+ themselves have mappings to LDAP attributes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"reference"</term>
+ <listitem>
+ <para>Maps a JSON field to an LDAP entry found by reference.</para>
+
+ <para>This mapping works for LDAP attributes whose values reference
+ other entries. This is shown in the following example from the
+ default configuration. The LDAP <literal>manager</literal>
+ attribute values are user entry DNs. Here, the JSON
+ <literal>manager</literal> field takes the user ID and name from
+ the entry referenced by the LDAP attribute. On updates, changes
+ to the JSON manager <literal>_id</literal> affect which manager
+ entry is referenced, yet any changes to the manager's name are
+ discarded, because changing managers only affects which user entry
+ to point to, not the referenced user's name.</para>
+
+ <programlisting language="javascript">{
+ "manager": {
+ "reference": {
+ "ldapAttribute": "manager",
+ "baseDN": "ou=people,dc=example,dc=com",
+ "primaryKey": "uid",
+ "mapper": {
+ "object": {
+ "_id": {
+ "simple": {
+ "ldapAttribute": "uid",
+ "isSingleValued": true,
+ "isRequired": true
+ }
+ },
+ "displayName": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true,
+ "writability": "readOnlyDiscardWrites"
+ }
+ }
+ }
+ }
+ }
+ }
+}</programlisting>
+
+ <para>Babs Jensen's manager in the sample LDAP data is Torrey
+ Rigden, who has user ID <literal>trigden</literal>. Babs's entry has
+ <literal>manager: uid=trigden,ou=People,dc=example,dc=com</literal>.
+ With this mapping, the resulting JSON field is the following.</para>
+
+ <programlisting language="javascript">{
+ "manager": [
+ {
+ "_id": "trigden",
+ "displayName": "Torrey Rigden"
+ }
+ ]
+}</programlisting>
+
+ <itemizedlist>
+ <para>Reference mapping objects have the following fields.</para>
+
+ <listitem>
+ <para>(Required) "baseDN": indicates the base LDAP DN under which
+ to find entries referenced by the JSON resource.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Required) "ldapAttribute": specifies the LDAP attribute in
+ the entry underlying the JSON resource whose value points to the
+ referenced entry.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Required) "mapper": describes how the referenced entry
+ content maps to the content of this JSON field.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Required) "primaryKey": indicates which LDAP attribute in
+ the mapper holds the primary key to the referenced entry.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "isRequired": true means the LDAP attribute is
+ mandatory and must be provided to create the resource; false
+ means it is optional.</para>
+
+ <para>Default: <literal>false</literal></para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "isSingleValued": true means represent a
+ possibly multi-valued LDAP attribute as a single value; false
+ means represent it as an array of values.</para>
+
+ <para>Default: <literal>false</literal></para>
+ </listitem>
+
+ <!-- Not used.
+ <listitem>
+ <para>(Optional) "scope": indicates the scope of the LDAP search
+ to find the referenced entry. The default is
+ <literal>"SearchScope.WHOLE_SUBTREE"</literal>.</para>
+ </listitem>
+ -->
+
+ <listitem>
+ <para>(Optional) "searchFilter": specifies the LDAP filter to
+ use to search for the referenced entry. The default is
+ <literal>"(objectClass=*)"</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Optional) "writability": indicates whether the mapping
+ supports updates, as described above for the simple mapping. The
+ default is "readWrite".</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The default mappings expose a SCIM view of user and group
+ data.</para>
+
+ <programlisting language="javascript">{
+ "/users": {
+ "baseDN": "ou=people,dc=example,dc=com",
+ "readOnUpdatePolicy": "controls",
+ "useSubtreeDelete": false,
+ "usePermissiveModify": true,
+ "etagAttribute": "etag",
+ "namingStrategy": {
+ "strategy": "clientDNNaming",
+ "dnAttribute": "uid"
+ },
+ "additionalLDAPAttributes": [
+ {
+ "type": "objectClass",
+ "values": [
+ "top",
+ "person",
+ "organizationalPerson",
+ "inetOrgPerson"
+ ]
+ }
+ ],
+ "attributes": {
+ "schemas": {
+ "constant": [
+ "urn:scim:schemas:core:1.0"
+ ]
+ },
+ "_id": {
+ "simple": {
+ "ldapAttribute": "uid",
+ "isSingleValued": true,
+ "isRequired": true,
+ "writability": "createOnly"
+ }
+ },
+ "_rev": {
+ "simple": {
+ "ldapAttribute": "etag",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ },
+ "userName": {
+ "simple": {
+ "ldapAttribute": "mail",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ },
+ "displayName": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true,
+ "isRequired": true
+ }
+ },
+ "name": {
+ "object": {
+ "givenName": {
+ "simple": {
+ "ldapAttribute": "givenName",
+ "isSingleValued": true
+ }
+ },
+ "familyName": {
+ "simple": {
+ "ldapAttribute": "sn",
+ "isSingleValued": true,
+ "isRequired": true
+ }
+ }
+ }
+ },
+ "manager": {
+ "reference": {
+ "ldapAttribute": "manager",
+ "baseDN": "ou=people,dc=example,dc=com",
+ "primaryKey": "uid",
+ "mapper": {
+ "object": {
+ "_id": {
+ "simple": {
+ "ldapAttribute": "uid",
+ "isSingleValued": true,
+ "isRequired": true
+ }
+ },
+ "displayName": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true,
+ "writability": "readOnlyDiscardWrites"
+ }
+ }
+ }
+ }
+ }
+ },
+ "groups": {
+ "reference": {
+ "ldapAttribute": "isMemberOf",
+ "baseDN": "ou=groups,dc=example,dc=com",
+ "writability": "readOnly",
+ "primaryKey": "cn",
+ "mapper": {
+ "object": {
+ "_id": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true
+ }
+ }
+ }
+ }
+ }
+ },
+ "contactInformation": {
+ "object": {
+ "telephoneNumber": {
+ "simple": {
+ "ldapAttribute": "telephoneNumber",
+ "isSingleValued": true
+ }
+ },
+ "emailAddress": {
+ "simple": {
+ "ldapAttribute": "mail",
+ "isSingleValued": true
+ }
+ }
+ }
+ },
+ "meta": {
+ "object": {
+ "created": {
+ "simple": {
+ "ldapAttribute": "createTimestamp",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ },
+ "lastModified": {
+ "simple": {
+ "ldapAttribute": "modifyTimestamp",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ }
+ }
+ }
+ }
+ },
+ "/groups": {
+ "baseDN": "ou=groups,dc=example,dc=com",
+ "readOnUpdatePolicy": "controls",
+ "useSubtreeDelete": false,
+ "usePermissiveModify": true,
+ "etagAttribute": "etag",
+ "namingStrategy": {
+ "strategy": "clientDNNaming",
+ "dnAttribute": "cn"
+ },
+ "additionalLDAPAttributes": [
+ {
+ "type": "objectClass",
+ "values": [
+ "top",
+ "groupOfUniqueNames"
+ ]
+ }
+ ],
+ "attributes": {
+ "schemas": {
+ "constant": [
+ "urn:scim:schemas:core:1.0"
+ ]
+ },
+ "_id": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true,
+ "isRequired": true,
+ "writability": "createOnly"
+ }
+ },
+ "_rev": {
+ "simple": {
+ "ldapAttribute": "etag",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ },
+ "displayName": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true,
+ "isRequired": true,
+ "writability": "readOnly"
+ }
+ },
+ "members": {
+ "reference": {
+ "ldapAttribute": "uniqueMember",
+ "baseDN": "dc=example,dc=com",
+ "primaryKey": "uid",
+ "mapper": {
+ "object": {
+ "_id": {
+ "simple": {
+ "ldapAttribute": "uid",
+ "isSingleValued": true,
+ "isRequired": true
+ }
+ },
+ "displayName": {
+ "simple": {
+ "ldapAttribute": "cn",
+ "isSingleValued": true,
+ "writability": "readOnlyDiscardWrites"
+ }
+ }
+ }
+ }
+ }
+ },
+ "meta": {
+ "object": {
+ "created": {
+ "simple": {
+ "ldapAttribute": "createTimestamp",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ },
+ "lastModified": {
+ "simple": {
+ "ldapAttribute": "modifyTimestamp",
+ "isSingleValued": true,
+ "writability": "readOnly"
+ }
+ }
+ }
+ }
+ }
+ }
+}</programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-standards.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-standards.xml
new file mode 100644
index 0000000..337fe4c
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/appendix-standards.xml
@@ -0,0 +1,1013 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<appendix xml:id='appendix-standards'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Standards, RFCs, & Internet-Drafts</title>
+
+ <para>OpenDJ <?eval ${docTargetVersion}?> software implements the following
+ RFCs, Internet-Drafts, and standards.</para>
+
+ <!-- Document [link], description -->
+ <variablelist>
+ <varlistentry xml:id="rfc1274">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc1274'>RFC 1274:
+ The COSINE and Internet X.500 Schema</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 1274</secondary>
+ </indexterm>
+ <para>X.500 Directory Schema, or Naming Architecture, for use in the
+ COSINE and Internet X.500 pilots.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc1321">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc1321'>RFC 1321:
+ The MD5 Message-Digest Algorithm</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 1321</secondary>
+ </indexterm>
+ <para>MD5 message-digest algorithm that takes as input a message of
+ arbitrary length and produces as output a 128-bit "fingerprint" or
+ "message digest" of the input.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc1777">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc1777'>RFC 1777:
+ Lightweight Directory Access Protocol (LDAPv2)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 1777</secondary>
+ </indexterm>
+ <para>Provide access to the X.500 Directory while not incurring the
+ resource requirements of the Directory Access Protocol.</para>
+ <para>Classified as an Historic document.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc1778">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc1778'>RFC 1778:
+ The String Representation of Standard Attribute Syntaxes</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 1778</secondary>
+ </indexterm>
+ <para>Defines the requirements that must be satisfied by encoding
+ rules used to render X.500 Directory attribute syntaxes into a form
+ suitable for use in the LDAP, then defines the encoding rules for the
+ standard set of attribute syntaxes.</para>
+ <para>Classified as an Historic document.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc1779">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc1779'>RFC 1779:
+ A String Representation of Distinguished Names</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 1779</secondary>
+ </indexterm>
+ <para>Defines a string format for representing names, which is designed
+ to give a clean representation of commonly used names, whilst being
+ able to represent any distinguished name.</para>
+ <para>Classified as an Historic document.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2079">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2079'>RFC 2079:
+ Definition of an X.500 Attribute Type and an Object Class to Hold
+ Uniform Resource Identifiers (URIs)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2079</secondary>
+ </indexterm>
+ <para>Defines a new attribute type and an auxiliary object class to
+ allow URIs, including URLs, to be stored in directory entries in a
+ standard way.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2222">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2222'>RFC 2222:
+ Simple Authentication and Security Layer (SASL)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2222</secondary>
+ </indexterm>
+ <para>Describes a method for adding authentication support to
+ connection-based protocols.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2246">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2246'>RFC 2246:
+ The TLS Protocol Version 1.0</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2246</secondary>
+ </indexterm>
+ <para>Specifies Version 1.0 of the Transport Layer Security
+ protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2247">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2247'>RFC 2247:
+ Using Domains in LDAP/X.500 Distinguished Names</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2247</secondary>
+ </indexterm>
+ <para>Defines an algorithm by which a name registered with the Internet
+ Domain Name Service can be represented as an LDAP distinguished name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2251">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2251'>RFC 2251:
+ Lightweight Directory Access Protocol (v3)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2251</secondary>
+ </indexterm>
+ <para>Describes a directory access protocol designed to provide access
+ to directories supporting the X.500 models, while not incurring the
+ resource requirements of the X.500 Directory Access Protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2252">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2252'>RFC 2252:
+ Lightweight Directory Access Protocol (v3): Attribute Syntax
+ Definitions</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2252</secondary>
+ </indexterm>
+ <para>Defines a set of syntaxes for LDAPv3, and the rules by which
+ attribute values of these syntaxes are represented as octet strings
+ for transmission in the LDAP protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2253">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2253'>RFC 2253:
+ Lightweight Directory Access Protocol (v3): UTF-8 String Representation
+ of Distinguished Names</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2253</secondary>
+ </indexterm>
+ <para>Defines a common UTF-8 format to represent distinguished names
+ unambiguously.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2254">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2254'>RFC 2254:
+ The String Representation of LDAP Search Filters</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2254</secondary>
+ </indexterm>
+ <para>Defines the string format for representing names, which is designed
+ to give a clean representation of commonly used distinguished names,
+ while being able to represent any distinguished name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2255">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2255'>RFC 2255:
+ The LDAP URL Format</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2255</secondary>
+ </indexterm>
+ <para>Describes a format for an LDAP Uniform Resource Locator.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2256">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2256'>RFC 2256:
+ A Summary of the X.500(96) User Schema for use with LDAPv3</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2256</secondary>
+ </indexterm>
+ <para>Provides an overview of the attribute types and object classes
+ defined by the ISO and ITU-T committees in the X.500 documents, in
+ particular those intended for use by directory clients.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2307">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2307'>RFC 2307:
+ An Approach for Using LDAP as a Network Information Service</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2307</secondary>
+ </indexterm>
+ <para>Describes an experimental mechanism for mapping entities related
+ to TCP/IP and the UNIX system into X.500 entries so that they may be
+ resolved with the Lightweight Directory Access Protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2377">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2377'>RFC 2377:
+ Naming Plan for Internet Directory-Enabled Applications</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2377</secondary>
+ </indexterm>
+ <para>Proposes a new directory naming plan that leverages the strengths
+ of the most popular and successful Internet naming schemes for naming
+ objects in a hierarchical directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2696">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2696'>RFC 2696:
+ LDAP Control Extension for Simple Paged Results Manipulation</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2696</secondary>
+ </indexterm>
+ <para>Allows a client to control the rate at which an LDAP server
+ returns the results of an LDAP search operation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2713">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2713'>RFC 2713:
+ Schema for Representing Java(tm) Objects in an LDAP Directory</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2713</secondary>
+ </indexterm>
+ <para>Defines a common way for applications to store and retrieve Java
+ objects from the directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2714">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2714'>RFC 2714:
+ Schema for Representing CORBA Object References in an LDAP
+ Directory</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2714</secondary>
+ </indexterm>
+ <para>Define a common way for applications to store and retrieve CORBA
+ object references from the directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2739">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2739'>RFC 2739:
+ Calendar Attributes for vCard and LDAP</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2739</secondary>
+ </indexterm>
+ <para>Defines a mechanism to locate a user calendar and free/busy time
+ using the LDAP protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2798">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2798'>RFC 2798:
+ Definition of the inetOrgPerson LDAP Object Class</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2798</secondary>
+ </indexterm>
+ <para>Define an object class called inetOrgPerson for use in LDAP and
+ X.500 directory services that extends the X.521 standard
+ organizationalPerson class.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2829">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2829'>RFC 2829:
+ Authentication Methods for LDAP</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2829</secondary>
+ </indexterm>
+ <para>Specifies particular combinations of security mechanisms which
+ are required and recommended in LDAP implementations.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2830">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2830'>RFC 2830:
+ Lightweight Directory Access Protocol (v3): Extension for Transport
+ Layer Security</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2830</secondary>
+ </indexterm>
+ <para>Defines the "Start Transport Layer Security (TLS) Operation"
+ for LDAP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2849">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2849'>RFC 2849:
+ The LDAP Data Interchange Format (LDIF) - Technical
+ Specification</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2849</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Specification</secondary>
+ </indexterm>
+ <para>Describes a file format suitable for describing directory
+ information or modifications made to directory information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2891">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2891'>RFC 2891:
+ LDAP Control Extension for Server Side Sorting of Search Results</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2891</secondary>
+ </indexterm>
+ <para>Describes two LDAPv3 control extensions for server side
+ sorting of search results.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc2926">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc2926'>RFC 2926:
+ Conversion of LDAP Schemas to and from SLP Templates</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 2926</secondary>
+ </indexterm>
+ <para>Describes a procedure for mapping between Service Location
+ Protocol service advertisements and lightweight directory access
+ protocol descriptions of services.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3045">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3045'>RFC 3045:
+ Storing Vendor Information in the LDAP root DSE</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3045</secondary>
+ </indexterm>
+ <para>Specifies two Lightweight Directory Access Protocol attributes,
+ vendorName and vendorVersion that MAY be included in the root
+ DSA-specific Entry (DSE) to advertise vendor-specific information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3062">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3062'>RFC 3062:
+ LDAP Password Modify Extended Operation</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3062</secondary>
+ </indexterm>
+ <para>Describes an LDAP extended operation to allow modification of
+ user passwords which is not dependent upon the form of the authentication
+ identity nor the password storage mechanism used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3112">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3112'>RFC 3112:
+ LDAP Authentication Password Schema</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3112</secondary>
+ </indexterm>
+ <para>Describes schema in support of user/password authentication in
+ a LDAP directory including the authPassword attribute type. This
+ attribute type holds values derived from the user's password(s)
+ (commonly using cryptographic strength one-way hash).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3377">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3377'>RFC 3377:
+ Lightweight Directory Access Protocol (v3): Technical
+ Specification</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3377</secondary>
+ </indexterm>
+ <para>Specifies the set of RFCs comprising the Lightweight Directory
+ Access Protocol Version 3 (LDAPv3), and addresses the "IESG Note"
+ attached to RFCs 2251 through 2256.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3383">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3383'>RFC 3383:
+ Internet Assigned Numbers Authority (IANA) Considerations for the
+ Lightweight Directory Access Protocol (LDAP)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3383</secondary>
+ </indexterm>
+ <para>Provides procedures for registering extensible elements
+ of the Lightweight Directory Access Protocol (LDAP).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3546">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3546'>RFC 3546:
+ Transport Layer Security (TLS) Extensions</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3546</secondary>
+ </indexterm>
+ <para>Describes extensions that may be used to add functionality to
+ Transport Layer Security.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3671">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3671'>RFC 3671:
+ Collective Attributes in the Lightweight Directory Access Protocol
+ (LDAP)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3671</secondary>
+ </indexterm>
+ <para>Summarizes the X.500 information model for collective attributes
+ and describes use of collective attributes in LDAP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3672">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3672'>RFC 3672:
+ Subentries in the Lightweight Directory Access Protocol
+ (LDAP)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3672</secondary>
+ </indexterm>
+ <para>Adapts X.500 subentries mechanisms for use with the Lightweight
+ Directory Access Protocol (LDAP).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3673">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3673'>RFC 3673:
+ Lightweight Directory Access Protocol version 3 (LDAPv3): All Operational
+ Attributes</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3673</secondary>
+ </indexterm>
+ <para>Describes an LDAP extension which clients may use to request the
+ return of all operational attributes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3674">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3674'>RFC 3674:
+ Feature Discovery in Lightweight Directory Access Protocol
+ (LDAP)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3674</secondary>
+ </indexterm>
+ <para>Introduces a general mechanism for discovery of elective features
+ and extensions which cannot be discovered using existing mechanisms.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3771">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3771'>RFC 3771:
+ Lightweight Directory Access Protocol (LDAP) Intermediate Response
+ Message</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3771</secondary>
+ </indexterm>
+ <para>Defines and describes the IntermediateResponse message, a general
+ mechanism for defining single-request/multiple-response operations in
+ Lightweight Directory Access Protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3829">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3829'>RFC 3829:
+ Lightweight Directory Access Protocol (LDAP) Authorization Identity
+ Request and Response Controls</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3829</secondary>
+ </indexterm>
+ <para>Extends the Lightweight Directory Access Protocol bind operation
+ with a mechanism for requesting and returning the authorization identity
+ it establishes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3876">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3876'>RFC 3876:
+ Returning Matched Values with the Lightweight Directory Access Protocol
+ version 3 (LDAPv3)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3876</secondary>
+ </indexterm>
+ <para>Describes a control for the Lightweight Directory Access Protocol
+ version 3 that is used to return a subset of attribute values from an
+ entry.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc3909">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc3909'>RFC 3909:
+ Lightweight Directory Access Protocol (LDAP) Cancel Operation</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 3909</secondary>
+ </indexterm>
+ <para>Describes a Lightweight Directory Access Protocol extended operation
+ to cancel (or abandon) an outstanding operation, with a response to
+ indicate the outcome of the operation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4346">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4346'>RFC 4346:
+ The Transport Layer Security (TLS) Protocol Version 1.1</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4346</secondary>
+ </indexterm>
+ <para>Specifies Version 1.1 of the Transport Layer Security
+ protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4370">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4370'>RFC 4370:
+ Lightweight Directory Access Protocol (LDAP) Proxied Authorization
+ Control</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4370</secondary>
+ </indexterm>
+ <para>Defines the Proxy Authorization Control, that allows a client
+ to request that an operation be processed under a provided authorization
+ identity instead of under the current authorization identity associated
+ with the connection.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4403">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4403'>RFC 4403:
+ Lightweight Directory Access Protocol (LDAP) Schema for Universal
+ Description, Discovery, and Integration version 3 (UDDIv3)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4403</secondary>
+ </indexterm>
+ <para>Defines the Lightweight Directory Access Protocol schema for
+ representing Universal Description, Discovery, and Integration
+ data types in an LDAP directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4422">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4422'>RFC 4422:
+ Simple Authentication and Security Layer (SASL)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4422</secondary>
+ </indexterm>
+ <para>Describes a framework for providing authentication and data
+ security services in connection-oriented protocols via replaceable
+ mechanisms.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4505">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4505'>RFC 4505:
+ Anonymous Simple Authentication and Security Layer (SASL)
+ Mechanism</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4505</secondary>
+ </indexterm>
+ <para>Describes a new way to provide anonymous login is needed
+ within the context of the Simple Authentication and Security
+ Layer framework.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4510">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4510'>RFC 4510:
+ Lightweight Directory Access Protocol (LDAP): Technical Specification
+ Road Map</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4510</secondary>
+ </indexterm>
+ <para>Provides a road map of the LDAP Technical Specification.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4511">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4511'>RFC 4511:
+ Lightweight Directory Access Protocol (LDAP): The Protocol</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4511</secondary>
+ </indexterm>
+ <para>Describes the protocol elements, along with their semantics and
+ encodings, of the Lightweight Directory Access Protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4512">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4512'>RFC 4512:
+ Lightweight Directory Access Protocol (LDAP): Directory Information
+ Models</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4512</secondary>
+ </indexterm>
+ <para>Describes the X.500 Directory Information Models as used in
+ LDAP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4513">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4513'>RFC 4513:
+ Lightweight Directory Access Protocol (LDAP): Authentication Methods
+ and Security Mechanisms</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4513</secondary>
+ </indexterm>
+ <para>Describes authentication methods and security mechanisms of the
+ Lightweight Directory Access Protocol.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4514">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4514'>RFC 4514:
+ Lightweight Directory Access Protocol (LDAP): String Representation of
+ Distinguished Names</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4514</secondary>
+ </indexterm>
+ <para>Defines the string representation used in the Lightweight Directory
+ Access Protocol to transfer distinguished names.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4515">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4515'>RFC 4515:
+ Lightweight Directory Access Protocol (LDAP): String Representation
+ of Search Filters</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4515</secondary>
+ </indexterm>
+ <para>Defines a human-readable string representation of LDAP search
+ filters that is appropriate for use in LDAP URLs and in other
+ applications.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4516">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4516'>RFC 4516:
+ Lightweight Directory Access Protocol (LDAP): Uniform Resource
+ Locator</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4516</secondary>
+ </indexterm>
+ <para>Describes a format for a Lightweight Directory Access Protocol
+ Uniform Resource Locator.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4517">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4517'>RFC 4517:
+ Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching
+ Rules</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4517</secondary>
+ </indexterm>
+ <para>Defines a base set of syntaxes and matching rules for use in
+ defining attributes for LDAP directories.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4518">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4518'>RFC 4518:
+ Lightweight Directory Access Protocol (LDAP): Internationalized
+ String Preparation</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4518</secondary>
+ </indexterm>
+ <para>Defines string preparation algorithms for character-based matching
+ rules defined for use in LDAP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4519">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4519'>RFC 4519:
+ Lightweight Directory Access Protocol (LDAP): Schema for User
+ Applications</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4519</secondary>
+ </indexterm>
+ <para>Provides a technical specification of attribute types and object
+ classes intended for use by LDAP directory clients for many directory
+ services, such as White Pages.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4524">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4524'>RFC 4524:
+ COSINE LDAP/X.500 Schema</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4524</secondary>
+ </indexterm>
+ <para>Provides a collection of schema elements for use with the
+ Lightweight Directory Access Protocol from the COSINE and Internet
+ X.500 pilot projects.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4525">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4525'>RFC 4525:
+ Lightweight Directory Access Protocol (LDAP) Modify-Increment
+ Extension</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4525</secondary>
+ </indexterm>
+ <para>Describes an extension to the Lightweight Directory Access
+ Protocol Modify operation to support an increment capability.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4526">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4526'>RFC 4526:
+ Lightweight Directory Access Protocol (LDAP) Absolute True and False
+ Filters</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4526</secondary>
+ </indexterm>
+ <para>Extends the Lightweight Directory Access Protocol to support
+ absolute True and False filters based upon similar capabilities found
+ in X.500 directory systems.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4527">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4527'>RFC 4527:
+ Lightweight Directory Access Protocol (LDAP) Read Entry
+ Controls</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4527</secondary>
+ </indexterm>
+ <para>Specifies an extension to the Lightweight Directory Access
+ Protocol to allow the client to read the target entry of an update
+ operation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4528">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4528'>RFC 4528:
+ Lightweight Directory Access Protocol (LDAP) Assertion
+ Control</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4528</secondary>
+ </indexterm>
+ <para>Defines the Lightweight Directory Access Protocol Assertion
+ Control, which allows a client to specify that a directory operation
+ should only be processed if an assertion applied to the target entry
+ of the operation is true.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4529">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4529'>RFC 4529:
+ Requesting Attributes by Object Class in the Lightweight Directory
+ Access Protocol (LDAP)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4529</secondary>
+ </indexterm>
+ <para>Extends LDAP to support a mechanism that LDAP clients may use to
+ request the return of all attributes of an object class.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4530">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4530'>RFC 4530:
+ Lightweight Directory Access Protocol (LDAP) entryUUID Operational
+ Attribute</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4530</secondary>
+ </indexterm>
+ <para>Describes the LDAP/X.500 'entryUUID' operational attribute and
+ associated matching rules and syntax.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4532">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4532'>RFC 4532:
+ Lightweight Directory Access Protocol (LDAP) "Who am I?"
+ Operation</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4532</secondary>
+ </indexterm>
+ <para>Provides a mechanism for Lightweight Directory Access Protocol
+ clients to obtain the authorization identity the server has associated
+ with the user or application entity.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4616">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4616'>RFC 4616:
+ The PLAIN Simple Authentication and Security Layer (SASL)
+ Mechanism</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4616</secondary>
+ </indexterm>
+ <para>Defines a simple clear-text user/password Simple Authentication
+ and Security Layer mechanism called the PLAIN mechanism.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4634">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4634'>RFC 4634:
+ US Secure Hash Algorithms (SHA and HMAC-SHA)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4634</secondary>
+ </indexterm>
+ <para>Specifies Secure Hash Algorithms, SHA-256, SHA-384, and SHA-512,
+ for computing a condensed representation of a message or a data file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4752">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4752'>RFC 4752:
+ The Kerberos V5 ("GSSAPI") Simple Authentication and Security Layer
+ (SASL) Mechanism</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4752</secondary>
+ </indexterm>
+ <para>Describes the method for using the Generic Security
+ Service Application Program Interface (GSS-API) Kerberos V5 in the
+ Simple Authentication and Security Layer, called the GSSAPI mechanism.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc4876">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc4876'>RFC 4876:
+ A Configuration Profile Schema for Lightweight Directory Access Protocol
+ (LDAP)-Based Agents</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 4876</secondary>
+ </indexterm>
+ <para>Defines a schema for storing a profile for agents that make use
+ of the Lightweight Directory Access protocol (LDAP).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="rfc5020">
+ <term><link xlink:href='http://tools.ietf.org/html/rfc5020'>RFC 5020:
+ The Lightweight Directory Access Protocol (LDAP) entryDN Operational
+ Attribute</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>RFC 5020</secondary>
+ </indexterm>
+ <para>Describes the Lightweight Directory Access Protocol
+ (LDAP) / X.500 'entryDN' operational attribute, that
+ provides a copy of the entry's distinguished name for use in
+ attribute value assertions.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="fips180-1">
+ <term><link xlink:href='http://www.itl.nist.gov/fipspubs/fip180-1.htm'
+ >FIPS 180-1: Secure Hash Standard (SHA-1)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>FIPS 180-1</secondary>
+ </indexterm>
+ <para>Specifies a Secure Hash Algorithm, SHA-1, for computing a condensed
+ representation of a message or a data file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="fips180-2">
+ <term><link
+ xlink:href='http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf'
+ >FIPS 180-2: Secure Hash Standard (SHA-1, SHA-256, SHA-384,
+ SHA-512)</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>FIPS 180-2</secondary>
+ </indexterm>
+ <para>Specifies four Secure Hash Algorithms for computing a condensed
+ representation of electronic data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="dsmlv2">
+ <term><link
+ xlink:href='http://www.oasis-open.org/committees/dsml/docs/DSMLv2.xsd'
+ >DSMLv2: Directory Service Markup Language</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>DSMLv2</secondary>
+ </indexterm>
+ <para>Provides a method for expressing directory queries and updates as
+ XML documents.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:show="new" xlink:href='http://www.json.org'
+ >JavaScript Object Notation</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>JSON</secondary>
+ </indexterm>
+ <para>A data-interchange format that aims to be both "easy for humans to
+ read and write," and also "easy for machines to parse and generate."</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:show="new"
+ xlink:href='http://www.simplecloud.info/specs/draft-scim-core-schema-00.html'
+ >Simple Cloud Identity Management: Core Schema 1.0</link></term>
+ <listitem>
+ <indexterm>
+ <primary>Supported standards</primary>
+ <secondary>SCIM Core Schema 1.0</secondary>
+ </indexterm>
+ <para>Platform neutral schema and extension model for representing users
+ and groups in JSON and XML formats. OpenDJ supports the JSON formats.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</appendix>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-account-lockout.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-account-lockout.xml
new file mode 100644
index 0000000..c135dff
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-account-lockout.xml
@@ -0,0 +1,341 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-account-lockout'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Implementing Account Lockout & Notification</title>
+
+ <para>OpenDJ directory server supports automatic account lockout.
+ The aim of account lockout is not to punish users who mistype their
+ passwords, but instead to protect the directory against attacks
+ in which the attacker attempts to guess a user password, repeatedly
+ attempting to bind until success is achieved.</para>
+
+ <para>Account lockout disables a user account after a specified
+ number of successive authentication failures. When you implement account
+ lockout, you can opt to have OpenDJ directory server unlock the account
+ again after a specified interval, or you can leave the account locked
+ until the password is reset.</para>
+
+ <note>
+ <para>When you configure account lockout as part of password policy, OpenDJ
+ locks an account after the specified number of consecutive authentication
+ failures. Account lockout is not transactional across a replication topology,
+ however. Under normal circumstances, replication nevertheless propagates
+ lockout quickly. If ever replication is delayed, an attacker with direct
+ access to multiple replicas could try to authenticate up to the specified
+ number of times on each replica before being locked out on all replicas.</para>
+ </note>
+
+ <para>This chapter shows you how to set up account lockout policies,
+ and how to intervene manually to lock and unlock accounts.</para>
+
+ <section xml:id="configure-account-lockout">
+ <title>Configuring Account Lockout</title>
+ <indexterm><primary>Accounts</primary><secondary>Lockout</secondary></indexterm>
+ <para>Account lockout is configured as part of password policy. This section
+ demonstrates configuring account lockout as part of the default password
+ policy. Users are allowed three consecutive failures before being locked out
+ for five minutes. Failures themselves also expire after five minutes.</para>
+
+ <para>Change the default password policy to activate lockout using the
+ <command>dsconfig</command> command. As the password policy is part of
+ the server configuration, you must manually apply the changes to each
+ replica in a replication topology.</para>
+
+ <screen>$ dsconfig
+ set-password-policy-prop
+ --port 4444
+ --hostname `hostname`
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set lockout-failure-count:3
+ --set lockout-duration:5m
+ --set lockout-failure-expiration-interval:5m
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Users having the default password policy are then locked out after
+ three failed attempts in succession.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword hifalutin
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ mail
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com
+
+$ ldapsearch
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword fatfngrs
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ mail
+The simple bind attempt failed
+Result Code: 49 (Invalid Credentials)
+$ ldapsearch
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword fatfngrs
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ mail
+The simple bind attempt failed
+Result Code: 49 (Invalid Credentials)
+$ ldapsearch
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword fatfngrs
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ mail
+The simple bind attempt failed
+Result Code: 49 (Invalid Credentials)
+$ ldapsearch
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword hifalutin
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ mail
+The simple bind attempt failed
+Result Code: 49 (Invalid Credentials)</screen>
+ </section>
+
+ <section xml:id="manage-accounts">
+ <title>Managing Accounts Manually</title>
+
+ <para>This section covers disabling and enabling accounts by using the
+ <command>manage-account</command> command. Password reset is covered in
+ the chapter on performing LDAP operations.</para>
+
+ <para>For the following examples, the directory admin user, Kirsten Vaughan,
+ has <literal>ds-privilege-name: password-reset</literal>, and the following
+ ACI on <literal>ou=People,dc=example,dc=com</literal>.</para>
+ <literallayout class="monospaced">(target="ldap:///ou=People,dc=example,dc=com") (targetattr ="*||+")(
+version 3.0;acl "Admins can run amok"; allow(all) groupdn =
+"ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)</literallayout>
+
+ <procedure xml:id="disable-account">
+ <title>To Disable an Account</title>
+ <indexterm><primary>Accounts</primary><secondary>Disabling</secondary></indexterm>
+ <step>
+ <para>Set the account status to disabled with the
+ <command>manage-account</command> command.</para>
+
+ <screen>$ manage-account
+ set-account-is-disabled
+ --port 4444
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --operationValue true
+ --targetDN uid=bjensen,ou=people,dc=example,dc=com
+ --trustAll
+Account Is Disabled: true</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="reactivate-account">
+ <title>To Activate a Disabled Account</title>
+ <indexterm><primary>Accounts</primary><secondary>Activating</secondary></indexterm>
+ <step>
+ <para>Clear the disabled status using the <command>manage-account</command>
+ command.</para>
+
+ <screen>$ manage-account
+ clear-account-is-disabled
+ --port 4444
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --targetDN uid=bjensen,ou=people,dc=example,dc=com
+ --trustAll
+Account Is Disabled: false</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="account-status-notification">
+ <title>Managing Account Status Notification</title>
+ <indexterm>
+ <primary>Accounts</primary>
+ <secondary>Status notifications</secondary>
+ </indexterm>
+ <para>OpenDJ can send mail about account status changes. OpenDJ needs an
+ SMTP server to send messages, and needs templates for the mail it sends.
+ By default, message templates are in English, under
+ <filename>/path/to/opendj/config/messages/</filename>.</para>
+
+ <para>OpenDJ generates notifications only when OpenDJ writes to an entry or
+ evaluates a user entry for authentication. OpenDJ generates account enabled
+ and account disabled notifications when the user account is enabled or
+ disabled with the <command>manage-account</command> command, which writes
+ to the entry. OpenDJ generates password expiration notifications when a
+ user tries to bind.</para>
+
+ <para>For example, if you set up OpenDJ to send a notification about password
+ expiration, that notification gets triggered when the user authenticates
+ during the password expiration warning interval. OpenDJ does not
+ automatically scan entries to send password expiry notifications. OpenDJ does
+ implement controls that you can pass in an LDAP search to determine whether a
+ user's password is about to expire. See the appendix on
+ <link xlink:href="admin-guide#appendix-controls"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>LDAP
+ Controls</citetitle></link> for a list. You can send notifications then
+ based on the results of your search.</para>
+
+ <procedure xml:id="mail-account-status-notifications">
+ <title>To Mail Users About Account Status</title>
+
+ <para>The following steps demonstrate how to set up notifications. Whether
+ OpenDJ sends notifications depends on the settings in the password policy,
+ and on account activity as described above.</para>
+
+ <step>
+ <para>Identify the SMTP server to which OpenDJ sends messages.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname `hostname`
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set smtp-server:smtp.example.com
+ --trustAll
+ --no-prompt</screen>
+ </step>
+
+ <step>
+ <para>Set up OpenDJ to be able to mail users about account status.</para>
+ <screen>$ dsconfig
+ set-account-status-notification-handler-prop
+ --port 4444
+ --hostname `hostname`
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "SMTP Handler"
+ --set enabled:true
+ --set email-address-attribute-type:mail
+ --trustAll
+ --no-prompt</screen>
+ <para>Notice that OpenDJ finds the user's mail address on the attribute
+ on the user's entry, specified by
+ <literal>email-address-attribute-type</literal>.</para>
+ <para>You can also configure the <literal>message-subject</literal> and
+ <literal>message-template-file</literal> properties. Try interactive
+ mode if you plan to do so.</para>
+ <para>You find templates for messages by default under the
+ <filename>config/messages</filename> directory. You can edit the templates
+ to suit your purposes.</para>
+ </step>
+
+ <step>
+ <para>Adjust applicable password policies to use the account status
+ notification handler you configured.</para>
+ <screen>$ dsconfig
+ set-password-policy-prop
+ --port 4444
+ --hostname `hostname`
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set account-status-notification-handler:"SMTP Handler"
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <variablelist xml:id="about-message-templates">
+ <title>About Notification Message Templates</title>
+ <indexterm>
+ <primary>Accounts</primary>
+ <secondary>Customizing notification messages</secondary>
+ </indexterm>
+ <para>When editing the <filename>config/messages</filename> templates
+ to suit your purposes, you can use the following tokens to have OpenDJ
+ update the message text dynamically.</para>
+ <varlistentry>
+ <term><literal>%%notification-type%%</literal></term>
+ <listitem>
+ <para>This token is replaced with the name of the account status
+ notification type for the notification.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>%%notification-message%%</literal></term>
+ <listitem>
+ <para>This token is replaced with the message for the account status
+ notification.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>%%notification-user-dn%%</literal></term>
+ <listitem>
+ <para>This token is replaced with the string representation of the DN for
+ the user that is the target of the account status notification.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>%%notification-user-attr:<replaceable>attrname</replaceable>%%</literal></term>
+ <listitem>
+ <para>This token is replaced with the value of the attribute specified by
+ <replaceable>attrname</replaceable> from the user's entry. If the
+ specified attribute has multiple values, then OpenDJ uses the first value
+ encountered. If the specified attribute does not have any values, then
+ OpenDJ replaces it with an emtpy string.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>%%notification-property:<replaceable>propname</replaceable>%%</literal></term>
+ <listitem>
+ <para>This token is replaced with the value of the specified notification
+ property from the account status notification. If the specified property
+ has multiple values, then OpenDJ uses the first value encountered. If the
+ specified property does not have any values, then OpenDJ replaces it with
+ an emtpy string. Valid <replaceable>propname</replaceable> values include
+ the following.</para>
+ <itemizedlist>
+ <listitem><para><literal>account-unlock-time</literal></para></listitem>
+ <listitem><para><literal>new-password</literal></para></listitem>
+ <listitem><para><literal>old-password</literal></para></listitem>
+ <listitem><para><literal>password-expiration-time</literal></para></listitem>
+ <listitem><para><literal>password-policy-dn</literal></para></listitem>
+ <listitem><para><literal>seconds-until-expiration</literal></para></listitem>
+ <listitem><para><literal>seconds-until-unlock</literal></para></listitem>
+ <listitem><para><literal>time-until-expiration</literal></para></listitem>
+ <listitem><para><literal>time-until-unlock</literal></para></listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-admin-tools.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-admin-tools.xml
new file mode 100644
index 0000000..76d9255
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-admin-tools.xml
@@ -0,0 +1,449 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-admin-tools'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Administration Interfaces & Tools</title>
+
+ <para>OpenDJ server software installs with a cross-platform, Java Swing-based
+ Control Panel for many day-to-day tasks. OpenDJ server software also installs
+ command-line tools for configuration and management tasks.</para>
+
+ <para>This chapter is one of the few to include screen shots of the control
+ panel. Most examples make use of the command-line tools. Once you understand
+ the concepts, and how to perform a task using the command-line tools, you
+ no doubt need no more than to know where to start in the Control Panel to
+ accomplish what you set out to do.</para>
+
+ <para>At a protocol level, administration tools and interfaces connect to
+ servers through a different network port than that used to listen for traffic
+ from other client applications.</para>
+
+ <para>This chapter takes a quick look at the tools for managing directory
+ services.</para>
+
+ <section xml:id="control-panel">
+ <title>Control Panel</title>
+ <indexterm><primary>Control panel</primary></indexterm>
+ <para>OpenDJ Control Panel offers a graphical user interface for
+ managing both local and remote servers. You choose the server to manage
+ when you start the Control Panel. The Control Panel connects to the
+ administration server port, making a secure LDAPS connection.</para>
+
+ <itemizedlist>
+ <para>Start OpenDJ Control Panel.</para>
+ <listitem>
+ <para>(UNIX) Run <command>opendj/bin/control-panel</command>.</para>
+ </listitem>
+ <listitem>
+ <para>(Windows) Double-click <filename>opendj\bat\control-panel.bat</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>(Mac OS X) Double-click <filename>opendj/bin/ControlPanel.app</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>When you login to OpenDJ Control Panel, you authenticate over LDAP.
+ This means that if users can run the Control Panel, they can use it to manage
+ a running server. Yet, to start and stop the server process through OpenDJ
+ Control Panel, you must start the Control Panel on the system where OpenDJ
+ runs, as the user who owns the OpenDJ server files (such as the user who
+ installed OpenDJ). In other words, the OpenDJ Control Panel does not do
+ remote process management.</para>
+
+ <mediaobject xml:id="figure-opendj-control-panel">
+ <imageobject>
+ <imagedata fileref="images/OpenDJ-Control-Panel.png" format="PNG" />
+ </imageobject>
+ <caption><para>OpenDJ Control Panel displays key information about the
+ server.</para></caption>
+ </mediaobject>
+
+ <variablelist>
+ <para>Down the left side of OpenDJ Control Panel, notice what you can
+ configure.</para>
+ <varlistentry>
+ <term>Directory Data</term>
+ <listitem>
+ <para>Directory data provisioning is typically not something you do
+ by hand in most deployments. Usually entries are created, modified, and
+ deleted through specific directory client applications. The Manage
+ Entries window can be useful, however, both in the lab as you design
+ and test directory data, and also if you modify individual ACIs or
+ debug issues with particular entries.</para>
+ <mediaobject xml:id="figure-manage-entries">
+ <imageobject>
+ <imagedata fileref="images/Manage-Entries.png" format="PNG" />
+ </imageobject>
+ <caption><para>The Manage Entries window can check that your changes are
+ valid before sending the request to the directory.</para></caption>
+ </mediaobject>
+ <para>Additionally, the Directory Data list makes it easy to create
+ a new base DN, and then import user data for the new base DN from LDIF.
+ You can also use the tools in the list to export user data to LDIF,
+ and to backup and restore user data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Schema</term>
+ <listitem>
+ <para>The Manage Schema window lets you browse and modify the rules
+ that define how data is stored in the directory. You can add new schema
+ definitions such as new attribute types and new object classes while the
+ server is running, and the changes you make take effect immediately.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Indexes</term>
+ <listitem>
+ <para>The Manage Indexes window gives you a quick overview of all
+ the indexes currently maintained for directory attributes. To protect
+ your directory resources from being absorbed by costly searches on
+ unindexed attributes, you may choose to keep the default behavior,
+ preventing unindexed searches, instead adding indexes required by specific
+ applications. (Notice that if the number of user data entries is smaller
+ than the default resource limits, you can still perform what appear
+ to be unindexed searches. That is because the <literal>dn2id</literal>
+ index returns all user data entries without hitting a resource limit that
+ would make the search unindexed.)</para>
+ <para>OpenDJ Control Panel also allows you to verify and rebuild
+ existing indexes, which you may have to do after an upgrade operation,
+ or if you have reason to suspect index corruption.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Monitoring</term>
+ <listitem>
+ <para>The Monitoring list gives you windows to observe information
+ about the system, the JVM used, and indications about how the cache is
+ used, whether the work queue has been filling up, as well as details
+ about the database. You can also view the numbers and types of requests
+ arriving over the connection handlers, and the current tasks in progress
+ as well.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Runtime Options</term>
+ <listitem>
+ <para>If you did not set appropriate JVM runtime options during the
+ installation process, this is the list that allows you to do so through
+ the Control Panel.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section xml:id="cli-overview">
+ <title>Command-Line Tools</title>
+ <indexterm><primary>Commands</primary></indexterm>
+
+ <para>All OpenDJ command-line tools take the <option>--help</option> option.</para>
+
+ <para>All commands call Java programs and therefore involve starting a
+ JVM.</para>
+
+ <itemizedlist>
+ <para>Setup, upgrade, and uninstall tools are located in the directory where
+ you unpacked OpenDJ, such as <filename>/path/to/opendj</filename>. Find the
+ additional command-line tools for your platform.</para>
+ <listitem>
+ <para>(UNIX) In <filename>opendj/bin</filename>.</para>
+ </listitem>
+ <listitem>
+ <para>(Windows) In <filename>opendj\bat</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following list uses the UNIX names for the tools. On Windows
+ all command-line tools have the extension .bat.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#backup-1"
+ xlink:role="http://docbook.org/xlink/role/olink">backup</link></term>
+ <listitem>
+ <para>Backup or schedule backup of directory data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#base64-1"
+ xlink:role="http://docbook.org/xlink/role/olink">base64</link></term>
+ <listitem>
+ <para>Encode and decode data in base64 format.</para>
+ <para>Base64 encoding represents binary data in ASCII, and can be used to
+ encode character strings in LDIF, for example.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#create-rc-script-1"
+ xlink:role="http://docbook.org/xlink/role/olink">create-rc-script</link>
+ (UNIX)</term>
+ <listitem>
+ <para>Generate a script you can use to start, stop, and restart the server
+ either directly or at system boot and shutdown. Use <command>create-rc-script -f
+ <replaceable>script-file</replaceable></command>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#dbtest-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dbtest</link></term>
+ <listitem>
+ <para>Debug JE databases.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#dsconfig-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dsconfig</link></term>
+ <listitem>
+ <para>The <command>dsconfig</command> command is the primary command-line
+ tool for viewing and editing OpenDJ configuration. When started without
+ arguments, <command>dsconfig</command> prompts you for administration
+ connection information. Once connected it presents you with a menu-driven
+ interface to the server configuration.</para>
+ <para>When you pass connection information, subcommands, and additional
+ options to <command>dsconfig</command>, the command runs in script mode
+ and so is not interactive.</para>
+ <para>You can prepare <command>dsconfig</command> batch scripts by running
+ the tool with the <option>--commandFilePath</option> option in interactive
+ mode, then reading from the batch file with the
+ <option>--batchFile</option> option in script mode. Batch files can be
+ useful when you have many <command>dsconfig</command> commands to run
+ and want to avoid starting the JVM and setting up a new connection for
+ each command.</para>
+ <para>In addition to the <link xlink:href="admin-guide#dsconfig-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dsconfig</link> reference
+ that covers subcommands, the <link xlink:show="new"
+ xlink:href="${configRefBase}"
+ ><citetitle>Configuration Reference</citetitle></link> covers the
+ properties you can set using the <command>dsconfig</command>
+ command.</para>
+ </listitem>
+ </varlistentry>
+<!--
+ <varlistentry>
+ <term><link xlink:href="admin-guide#dsframework-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dsframework</link></term>
+ <listitem>
+ <para>Manage server registration, server groups, and administrative
+ users.</para>
+ </listitem>
+ </varlistentry>
+-->
+ <varlistentry>
+ <term><link xlink:href="admin-guide#dsjavaproperties-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dsjavaproperties</link></term>
+ <listitem>
+ <para>Apply changes you make to
+ <filename>opendj/config/java.properties</filename>, which sets Java
+ runtime options.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#dsreplication-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dsreplication</link></term>
+ <listitem>
+ <para>Configure data replication between directory servers to keep their
+ contents in sync.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#encode-password-1"
+ xlink:role="http://docbook.org/xlink/role/olink">encode-password</link></term>
+ <listitem>
+ <para>Encode a clear text password according to one of the available
+ storage schemes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#export-ldif-1"
+ xlink:role="http://docbook.org/xlink/role/olink">export-ldif</link></term>
+ <listitem>
+ <para>Export directory data to LDAP Data Interchange Format, a standard,
+ portable, text-based representation of directory content.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#import-ldif-1"
+ xlink:role="http://docbook.org/xlink/role/olink">import-ldif</link></term>
+ <listitem>
+ <para>Load LDIF content into the directory, overwriting existing
+ data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldapcompare-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldapcompare</link></term>
+ <listitem>
+ <para>Compare the attribute values you specify with those stored on
+ entries in the directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldapdelete-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldapdelete</link></term>
+ <listitem>
+ <para>Delete one entry or an entire branch of subordinate entries in the
+ directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldapmodify-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldapmodify</link></term>
+ <listitem>
+ <para>Modify the specified attribute values for the specified
+ entries.</para>
+ <para>Use the <command>ldapmodify</command> command with the
+ <option>-a</option> option to add new entries.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldappasswordmodify-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldappasswordmodify</link></term>
+ <listitem>
+ <para>Modify user passwords.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldapsearch-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldapsearch</link></term>
+ <listitem>
+ <para>Search a branch of directory data for entries matching the LDAP
+ filter that you specify.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldif-diff-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldif-diff</link></term>
+ <listitem>
+ <para>Display differences between two LDIF files, with the resulting output
+ having LDIF format.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldifmodify-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldifmodify</link></term>
+ <listitem>
+ <para>Similar to the <command>ldapmodify</command> command, modify
+ specified attribute values for specified entries in an LDIF file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#ldifsearch-1"
+ xlink:role="http://docbook.org/xlink/role/olink">ldifsearch</link></term>
+ <listitem>
+ <para>Similar to the <command>ldapsearch</command> command, search a branch
+ of data in LDIF for entries matching the LDAP filter you specify.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#list-backends-1"
+ xlink:role="http://docbook.org/xlink/role/olink">list-backends</link></term>
+ <listitem>
+ <para>List backends and base DNs served by OpenDJ.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#make-ldif-1"
+ xlink:role="http://docbook.org/xlink/role/olink">make-ldif</link></term>
+ <listitem>
+ <para>Generate directory data in LDIF, based on templates that define how
+ the data should appear.</para>
+ <para>The <command>make-ldif</command> command is designed to help you
+ quickly generate test data that mimics data you expect to have in
+ production, but without compromising private information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#manage-account-1"
+ xlink:role="http://docbook.org/xlink/role/olink">manage-account</link></term>
+ <listitem>
+ <para>Lock and unlock user accounts, and view and manipulate password
+ policy state information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#manage-tasks-1"
+ xlink:role="http://docbook.org/xlink/role/olink">manage-tasks</link></term>
+ <listitem>
+ <para>View information about tasks scheduled to run in the server, and
+ cancel specified tasks.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#rebuild-index-1"
+ xlink:role="http://docbook.org/xlink/role/olink">rebuild-index</link></term>
+ <listitem>
+ <para>Rebuild an index stored in a JE backend.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#restore-1"
+ xlink:role="http://docbook.org/xlink/role/olink">restore</link></term>
+ <listitem>
+ <para>Restore user data from backup.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#start-ds-1"
+ xlink:role="http://docbook.org/xlink/role/olink">start-ds</link></term>
+ <listitem>
+ <para>Start OpenDJ directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#status-1"
+ xlink:role="http://docbook.org/xlink/role/olink">status</link></term>
+ <listitem>
+ <para>Display information about the server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#stop-ds-1"
+ xlink:role="http://docbook.org/xlink/role/olink">stop-ds</link></term>
+ <listitem>
+ <para>Stop OpenDJ directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><link xlink:href="admin-guide#verify-index-1"
+ xlink:role="http://docbook.org/xlink/role/olink">verify-index</link></term>
+ <listitem>
+ <para>Verify that an index stored in a JE backend is not corrupt.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>windows-service.bat (Windows)</term>
+ <listitem>
+ <para>Register OpenDJ as a Windows Service.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml
new file mode 100644
index 0000000..64d37ae
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml
@@ -0,0 +1,237 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-attribute-uniqueness'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Implementing Attribute Value Uniqueness</title>
+
+ <para>Some attribute values ought to remain unique. If you are using
+ <literal>uid</literal> values as RDNs to distinguish between millions of
+ user entries stored under <literal>ou=People</literal>, then you do not
+ want your directory to contain two or more identical
+ <literal>uid</literal> values. If your credit card or mobile number is
+ stored as an attribute value on your directory entry, you certainly do not
+ want to share that credit card or mobile number with another customer.
+ The same is true for your email address.</para>
+
+ <indexterm><primary>Unique attribute values</primary></indexterm>
+
+ <para>The difficulty for you as directory administrator lies in
+ implementing attribute value uniqueness without sacrificing the high
+ availability that comes from using OpenDJ's loosely consistent,
+ multi-master data replication. Indeed OpenDJ's replication model lets
+ you maintain write access during network outages for directory
+ applications. Yet, write access during a network outage can result in the
+ same, theoretically unique attribute value getting assigned to two different
+ entries at once. You do not notice the problem until the network outage
+ goes away and replication resumes.</para>
+
+ <para>This chapter shows you how to set up attribute value uniqueness
+ in your directory environment.</para>
+
+ <procedure xml:id="enable-unique-uids">
+ <title>To Enable Unique UIDs</title>
+
+ <para>OpenDJ provides a unique attribute plugin that you configure by using
+ the <command>dsconfig</command> command. By default, the plugin is prepared
+ to ensure attribute values are unique for <literal>uid</literal>
+ attributes.</para>
+
+ <step>
+ <para>Set the base DN where <literal>uid</literal> should have unique
+ values, and enable the plugin.</para>
+ <screen>$ dsconfig
+ set-plugin-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --plugin-name "UID Unique Attribute"
+ --set base-dn:ou=people,dc=example,dc=com
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Alternatively, you can specify multiple base DNs for unique values
+ across multiple suffixes.</para>
+ <screen>$ dsconfig
+ set-plugin-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDn "cn=Directory Manager"
+ --bindPassword password
+ --plugin-name "UID Unique Attribute"
+ --set enabled:true
+ --add base-dn:ou=people,dc=example,dc=com
+ --add base-dn:ou=people,dc=example,dc=org
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Check that the plugin is working correctly.</para>
+ <screen>$ cat bjensen.ldif
+dn: uid=ajensen,ou=People,dc=example,dc=com
+changetype: modify
+add: uid
+uid: bjensen
+
+$ ldapmodify
+ --defaultAdd
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename bjensen.ldif
+Processing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
+MODIFY operation failed
+Result Code: 19 (Constraint Violation)
+Additional Information: A unique attribute conflict was detected for \
+ attribute uid: value bjensen already exists in entry
+ uid=bjensen,ou=People,dc=example,dc=com</screen>
+
+ <para>If you have set up multiple suffixes, you might try something like
+ this.</para>
+ <screen>$ cat bjensen.ldif
+dn: uid=bjensen,ou=People,dc=example,dc=org
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+cn: Babs
+sn: Jensen
+uid: bjensen
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename bjensen.ldif
+Processing ADD request for uid=bjensen,ou=People,dc=example,dc=org
+ADD operation failed
+Result Code: 19 (Constraint Violation)
+Additional Information: A unique attribute conflict was detected for attribute
+ uid: value bjensen already exists in entry
+ uid=bjensen,ou=People,dc=example,dc=com</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="enable-unique-attributes">
+ <title>To Enable Unique Values For Other Attributes</title>
+
+ <para>You can also configure the unique attribute plugin for use with
+ other attributes, such as <literal>mail</literal>, <literal>mobile</literal>,
+ or attributes you define, for example <literal>cardNumber</literal>.</para>
+
+ <step>
+ <para>Before you set up the plugin, index the attribute for equality.</para>
+ </step>
+ <step>
+ <para>Set up the plugin configuration for your attribute.</para>
+ <screen>$ dsconfig
+ create-plugin
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --plugin-name "Unique mobile numbers"
+ --type unique-attribute
+ --set enabled:true
+ --set base-dn:ou=people,dc=example,dc=com
+ --set type:mobile
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Check that the plugin is working correctly.</para>
+ <screen>$ cat mobile.ldif
+dn: uid=ajensen,ou=People,dc=example,dc=com
+changetype: modify
+add: mobile
+mobile: +1 828 555 1212
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+changetype: modify
+add: mobile
+mobile: +1 828 555 1212
+
+$ ldapmodify
+ --defaultAdd
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename mobile.ldif
+Processing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=ajensen,ou=People,dc=example,dc=com
+Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
+MODIFY operation failed
+Result Code: 19 (Constraint Violation)
+Additional Information: A unique attribute conflict was detected for
+ attribute mobile: value +1 828 555 1212 already exists in entry
+ uid=ajensen,ou=People,dc=example,dc=com</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="unique-attributes-repl">
+ <title>To Ensure Unique Attribute Values With Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Unique attributes</secondary>
+ </indexterm>
+ <para>The unique attribute plugin ensures unique attribute values on the
+ directory server where the attribute value is updated. If client applications
+ separately write the same attribute value at the same time on different
+ directory replicas, it is possible that both servers consider the duplicate
+ value unique, especially if the network is down between the replicas.</para>
+
+ <step>
+ <para>Enable the plugin identically on all replicas.</para>
+ </step>
+ <step>
+ <para>To avoid duplicate values where possible, try one of the following
+ solutions.</para>
+ <stepalternatives>
+ <step>
+ <para>Use a load balancer or proxy technology to direct all updates
+ to the unique attribute to the same directory server.</para>
+ <para>The drawback here is the need for an additional component to
+ direct the updates to the same server, and to manage failover should that
+ server go down.</para>
+ </step>
+ <step>
+ <para>Configure safe read mode assured replication between replicas
+ storing the unique attribute.</para>
+ <para>The drawbacks here are the cost of safe read assured replication,
+ and the likelihood that assured replication can enter degraded mode during
+ a network outage, thus continuing to allow updates during the
+ outage.</para>
+ </step>
+ </stepalternatives>
+ </step>
+ </procedure>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-backup-restore.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-backup-restore.xml
new file mode 100644
index 0000000..15e68d6
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-backup-restore.xml
@@ -0,0 +1,277 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-backup-restore'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Backing Up & Restoring Data</title>
+
+ <para>OpenDJ lets you backup and restore your data either in compressed,
+ binary format, or in LDAP Data Interchange Format. This chapter shows you how
+ to backup and to restore OpenDJ data from archives, and explains portability
+ of backup archives, as well as backing up server configuration
+ information.</para>
+
+ <section xml:id="backup">
+ <title>Backing Up Directory Data</title>
+ <indexterm><primary>Backup</primary></indexterm>
+ <para>A <filename>bak/</filename> directory is provided when you install
+ OpenDJ, as a location to save binary backups. When you create a backup,
+ the <filename>bak/backup.info</filename> contains information about the
+ archive.</para>
+
+ <para>Archives produced by the <command>backup</command> command contain
+ backups only of the directory data. Backups of server configuration are
+ found in <filename>config/archived-configs/</filename>.</para>
+
+ <procedure xml:id="backup-immediately">
+ <title>To Back Up Data Immediately</title>
+
+ <para>To perform online backup, you start backup as a task by connecting to
+ the administrative port and authenticating as a user with the
+ <literal>backend-backup</literal> privilege, and also setting a start time
+ for the task by using the <option>--start</option> option.</para>
+
+ <para>To perform offline backup when OpenDJ is stopped, you run the
+ <command>backup</command> command without connecting to the server,
+ authenticating, or requesting a backup task.</para>
+
+ <step>
+ <para>Use one of the following alternatives.</para>
+ <stepalternatives>
+ <step>
+ <para>Back up only the database for Example.com, where the data
+ is stored in the backend named <literal>userRoot</literal>.</para>
+
+ <para>The following example requests an online backup task that
+ starts immediately, backing up only the <literal>userRoot</literal>
+ backend.</para>
+ <screen>$ backup
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backendID userRoot
+ --backupDirectory /path/to/opendj/bak
+ --start 0
+Backup task 20110613143715983 scheduled to start Jun 13, 2011 2:37:15 PM CEST</screen>
+ </step>
+ <step>
+ <para>Stop the server to back up Example.com data offline.</para>
+
+ <para>The following example stops OpenDJ, runs offline backup, and
+ starts the server after backup has completed.</para>
+ <screen>$ stop-ds
+Stopping Server...
+
+[13/Jun/2011:14:31:00 +0200] category=BACKEND severity=NOTICE msgID=9896306
+ msg=The backend userRoot is now taken offline
+[13/Jun/2011:14:31:00 +0200] category=CORE severity=NOTICE msgID=458955
+ msg=The Directory Server is now stopped
+$ backup --backendID userRoot -d /path/to/opendj/bak
+[13/Jun/2011:14:33:48 +0200] category=TOOLS severity=NOTICE msgID=10944792
+ msg=Starting backup for backend userRoot
+[13/Jun/2011:14:33:48 +0200] category=JEB severity=NOTICE msgID=8847446
+ msg=Archived: 00000000.jdb
+[13/Jun/2011:14:33:48 +0200] category=TOOLS severity=NOTICE msgID=10944795
+ msg=The backup process completed successfully
+$ start-ds
+... The Directory Server has started successfully</screen>
+ </step>
+ <step>
+ <para>Back up all user data on the server.</para>
+
+ <para>The following example requests an online backup task that
+ starts immediately, backing up all backends.</para>
+ <screen>$ backup
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backUpAll
+ --backupDirectory /path/to/opendj/bak
+ --start 0
+Backup task 20110613143801866 scheduled to start Jun 13, 2011 2:38:01 PM CEST</screen>
+ </step>
+ </stepalternatives>
+ </step>
+ </procedure>
+
+ <procedure xml:id="schedule-backup">
+ <title>To Schedule Data Backup</title>
+
+ <para>You can schedule online data backup using <command>crontab</command>
+ format.</para>
+
+ <step>
+ <para>Back up all user data every night at 2 AM, and notify
+ diradmin@example.com when finished, or on error.</para>
+ <screen>$ backup
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backUpAll
+ --backupDirectory /path/to/opendj/bak
+ --recurringTask "00 02 * * *"
+ --completionNotify diradmin@example.com
+ --errorNotify diradmin@example.com
+Recurring Backup task BackupTask-988d6adf-4d65-44bf-8546-6ea74a2480b0
+scheduled successfully</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="restore-data">
+ <title>Restoring Directory Data From Backup</title>
+ <indexterm><primary>Backup</primary></indexterm>
+ <indexterm>
+ <primary>Restoring</primary>
+ <secondary>From backup</secondary>
+ </indexterm>
+
+ <para>When you restore data, the procedure to follow depends on whether
+ the OpenDJ directory server is replicated.</para>
+
+ <procedure xml:id="restore-standalone-server">
+ <title>To Restore a Stand-alone Server</title>
+
+ <para>To restore OpenDJ when the server is online, you start a restore task
+ by connecting to the administrative port and authenticating as a user with
+ the <literal>backend-restore</literal> privilege, and also setting a start
+ time for the task by using the <option>--start</option> option.</para>
+
+ <para>To restore data when OpenDJ is stopped, you run the
+ <command>restore</command> command without connecting to the server,
+ authenticating, or requesting a restore task.</para>
+ <step>
+ <para>Use one of the following alternatives.</para>
+ <stepalternatives>
+ <step>
+ <para>Stop the server to restore data for Example.com.</para>
+
+ <para>The following example stops OpenDJ, restores data offline from
+ one of the available backups, and then starts the server after the
+ restore is complete.</para>
+ <screen>$ stop-ds
+Stopping Server...
+
+[13/Jun/2011:15:44:06 +0200] category=BACKEND severity=NOTICE msgID=9896306
+ msg=The backend userRoot is now taken offline
+[13/Jun/2011:15:44:06 +0200] category=CORE severity=NOTICE msgID=458955
+ msg=The Directory Server is now stopped
+$ restore --backupDirectory /path/to/opendj/bak --listBackups
+Backup ID: 20110613080032
+Backup Date: 13/Jun/2011:08:00:45 +0200
+Is Incremental: false
+Is Compressed: false
+Is Encrypted: false
+Has Unsigned Hash: false
+Has Signed Hash: false
+Dependent Upon: none
+$ restore --backupDirectory /path/to/opendj/bak --backupID 20110613080032
+[13/Jun/2011:15:47:41 +0200] category=JEB severity=NOTICE msgID=8847445
+ msg=Restored: 00000000.jdb (size 341835)
+$ start-ds
+... The Directory Server has started successfully</screen>
+ </step>
+ <step>
+ <para>Schedule the restore as a task to begin immediately.</para>
+
+ <para>The following example requests an online restore task, scheduled
+ to start immediately.</para>
+ <screen>$ restore
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backupDirectory /path/to/opendj/bak
+ --backupID 20110613080032
+ --start 0
+Restore task 20110613155052932 scheduled to start Jun 13, 2011 3:50:52 PM CEST</screen>
+ </step>
+ </stepalternatives>
+ </step>
+ </procedure>
+
+ <procedure xml:id="restore-replica">
+ <title>To Restore a Replica</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Restoring from backup</secondary>
+ </indexterm>
+
+ <para>After you restore a replica from backup, replication brings the replica
+ up to date with changes that happened after you created the backup. In order
+ to bring the replica up to date, replication must apply changes that
+ happened after the backup was made. Replication uses internal change log
+ records to determine what changes to apply.</para>
+
+ <para>Internal change log records are not kept forever, though. Replication
+ is configured to purge the change log of old changes, preventing the log
+ from growing indefinitely. Yet, for replication to determine what changes
+ to apply to a restored replica, it must find change log records dating back
+ at least to the last change in the backup. In other words, replication can
+ bring the restored replica up to date <emphasis>as long as the change log
+ records used to determine which changes to apply have not been
+ purged</emphasis>.</para>
+
+ <para>Therefore, when you restore a replicated server from backup, make sure
+ the backup you use is newer than the last purge of the replication change
+ log (default: 3 days). If all your backups are older than the replication
+ purge delay, do not restore from a backup, but instead initialize a new
+ replica as described in <link xlink:href="admin-guide#init-repl"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Initializing
+ Replicas</citetitle></link>.</para>
+
+ <step>
+ <para>Restore the server database from the backup archive that you are
+ sure is newer than the last purge of the replication change log.</para>
+
+ <screen>$ stop-ds
+Stopping Server...
+
+[13/Jun/2011:15:44:06 +0200] category=BACKEND severity=NOTICE msgID=9896306
+ msg=The backend userRoot is now taken offline
+[13/Jun/2011:15:44:06 +0200] category=CORE severity=NOTICE msgID=458955
+ msg=The Directory Server is now stopped
+$ restore --backupDirectory /path/to/opendj/bak --listBackups
+Backup ID: 20110613080032
+Backup Date: 13/Jun/2011:08:00:45 +0200
+Is Incremental: false
+Is Compressed: false
+Is Encrypted: false
+Has Unsigned Hash: false
+Has Signed Hash: false
+Dependent Upon: none
+$ restore --backupDirectory /path/to/opendj/bak --backupID 20110613080032
+[13/Jun/2011:15:47:41 +0200] category=JEB severity=NOTICE msgID=8847445
+ msg=Restored: 00000000.jdb (size 341835)
+$ start-ds
+... The Directory Server has started successfully</screen>
+ </step>
+
+ </procedure>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-chaining.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-chaining.xml
new file mode 100644
index 0000000..df46144
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-chaining.xml
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-chaining'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Implementing Directory Operation Chaining</title>
+
+ <para>Chaining involves one directory server communicating a directory
+ operation to another directory server in a distributed directory on behalf
+ of a client application. This chapter describes how to set up chaining
+ between directory servers in your deployment.</para>
+
+</chapter>
+
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-change-certs.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-change-certs.xml
new file mode 100644
index 0000000..0c228b2
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-change-certs.xml
@@ -0,0 +1,499 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-change-certs'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Changing Server Certificates</title>
+ <indexterm><primary>Certificates</primary></indexterm>
+
+ <para>OpenDJ uses key stores (for private keys) and trust stores (for
+ public, signed certificates). Up to three sets of key stores are used,
+ as shown in the following illustration.</para>
+
+ <mediaobject xml:id="figure-keystores">
+ <imageobject>
+ <imagedata fileref="images/keystores.png" format="PNG" />
+ </imageobject>
+ <caption><para>OpenDJ uses different sets of public and private keys for
+ different secure connections.</para></caption>
+ </mediaobject>
+
+ <itemizedlist>
+ <para>By default the key stores are located in the
+ <filename>/path/to/opendj/config</filename> directory.</para>
+
+ <listitem>
+ <para>The <filename>keystore</filename> and <filename>truststore</filename>
+ hold keys for securing connections with client applications.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>admin-keystore</filename> and
+ <filename>admin-truststore</filename> hold keys for securing administrative
+ connections, such as those used when connecting with the
+ <command>dsconfig</command> command.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <filename>ads-truststore</filename> holds keys for securing
+ replication connections with other OpenDJ servers in the replication
+ topology.</para>
+ </listitem>
+ </itemizedlist>
+
+ <variablelist>
+ <para>Each key store has a specific purpose.</para>
+
+ <varlistentry>
+ <term><filename>admin-keystore</filename></term>
+ <listitem>
+ <para>This Java Key Store holds the private key and administrative
+ certificate for the server, <literal>admin-cert</literal>. This key pair
+ is used to protect communications on the administration port. The password,
+ stored in <filename>admin-keystore.pin</filename>, is also the key password
+ for <literal>admin-cert</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>admin-truststore</filename></term>
+ <listitem>
+ <para>This Java Key Store holds a copy of the administrative certificate,
+ <literal>admin-cert</literal>. The password is the same as for the
+ <filename>admin-keystore</filename>, in other words the string in
+ <filename>admin-keystore.pin</filename>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>ads-truststore</filename></term>
+ <listitem>
+ <para>This Java Key Store holds public key certificates of all servers
+ replicating with the current server. It also includes the
+ <literal>ads-certificate</literal> key pair of the current server.
+ The password is stored in <filename>ads-truststore.pin</filename>.</para>
+
+ <para>Do not change this key store directly.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>keystore</filename></term>
+ <listitem>
+ <para>This Java Key Store holds the private key and server certificate,
+ <literal>server-cert</literal>, used to protect TLS/SSL communications
+ with client applications. The password, stored in
+ <filename>keystore.pin</filename>, is also the key password for
+ <literal>server-cert</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><filename>truststore</filename></term>
+ <listitem>
+ <para>This Java Key Store holds a copy of the <literal>server-cert</literal>
+ certificate from the <filename>keystore</filename>. This is also where you
+ import certificates of client applications if you want OpenDJ to recognize
+ them. The password is the same as for the <filename>keystore</filename>,
+ in other words the string in <filename>keystore.pin</filename>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <tip>
+ <para>Examples in this chapter use self-signed certificates, but you can
+ also use certificates signed by a Certificate Authority (CA).</para>
+
+ <para>When importing a certificate (<command>keytool -import</command>)
+ signed by a well-known CA, use the <option>-trustcacerts</option> option
+ to trust the CA certificates delivered with the Java runtime
+ environment.</para>
+ </tip>
+
+ <procedure xml:id="replace-key-pair">
+ <title>To Replace a Server Key Pair</title>
+
+ <para>This procedure shows how to replace a server key pair in the
+ <filename>admin-keystore</filename> and copy of the administrative certificate
+ in <filename>admin-truststore</filename>.</para>
+
+ <para>The examples also apply when replacing a key pair in the
+ <filename>keystore</filename> and copy of the server certificate in
+ <filename>truststore</filename>. Just adapt the commands to use the correct
+ key store, trust store, and PIN file names.</para>
+
+ <para>This procedure does not apply for replication key pairs. Instead, see
+ <xref linkend="replace-ads-cert" />.</para>
+
+ <step>
+ <para>Check the alias of the key pair and certificate copy to replace.</para>
+
+ <screen>$ cd /path/to/opendj/config
+$ keytool -list -keystore admin-keystore -storepass `cat admin-keystore.pin`
+
+Keystore type: JKS
+Keystore provider: SUN
+
+Your keystore contains 1 entry
+
+admin-cert, Mar 15, 2013, PrivateKeyEntry,
+Certificate fingerprint (SHA1): 54:9F:C3:F8:7B:B6:...:0A:98:D0:17:8E
+$ keytool -list -keystore admin-truststore -storepass `cat admin-keystore.pin`
+
+Keystore type: JKS
+Keystore provider: SUN
+
+Your keystore contains 1 entry
+
+admin-cert, Mar 15, 2013, trustedCertEntry,
+Certificate fingerprint (SHA1): 54:9F:C3:F8:7B:B6:...:0A:98:D0:17:8E</screen>
+
+ <para>This alias is also stored in the server configuration.</para>
+ </step>
+
+ <step>
+ <para>Remove the key pair and certificate copy to replace.</para>
+
+ <screen>$ keytool
+ -delete
+ -alias admin-cert
+ -keystore admin-keystore
+ -storepass `cat admin-keystore.pin`
+$ keytool
+ -delete
+ -alias admin-cert
+ -keystore admin-truststore
+ -storepass `cat admin-keystore.pin`</screen>
+ </step>
+
+ <step>
+ <para>Generate a new key pair in the key store.</para>
+
+ <screen width="83">$ keytool
+ -genkey
+ -alias admin-cert
+ -keyalg RSA
+ -validity 7300
+ -keysize 2048
+ -dname "CN=opendj.example.com, O=Administration Connector Self-Signed Certificate"
+ -keystore admin-keystore
+ -storepass `cat admin-keystore.pin`
+ -keypass `cat admin-keystore.pin`</screen>
+
+ <para>Notice that the <option>-alias</option> option takes the same alias
+ as before. This is because the <literal>ssl-cert-nickname</literal> for
+ the Administration Connector is configured as <literal>admin-cert</literal>.
+ Also, the <option>-dname</option> option has a CN value corresponding to the
+ fully-qualified domain name of the host where OpenDJ directory server is
+ running.</para>
+ </step>
+
+ <step>
+ <para>Get the new key pair's certificate signed, using one of the following
+ alternatives.</para>
+
+ <stepalternatives>
+ <step>
+ <para>Self-sign the certificate.</para>
+
+ <screen>$ keytool
+ -selfcert
+ -alias admin-cert
+ -keystore admin-keystore
+ -storepass `cat admin-keystore.pin`</screen>
+ </step>
+
+ <step>
+ <para>Create a certificate signing request, have it signed by a CA, and
+ import the signed certificate from the CA reply.</para>
+
+ <para>For examples of the <command>keytool</command> commands to use, see
+ the procedure <link xlink:href="admin-guide#new-ca-signed-cert"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Request and
+ Install a CA-Signed Certificate</citetitle></link>.</para>
+ </step>
+ </stepalternatives>
+
+ </step>
+
+ <step>
+ <para>Export a copy of the certificate from the key store.</para>
+
+ <screen>$ keytool
+ -export
+ -alias admin-cert
+ -keystore admin-keystore
+ -storepass `cat admin-keystore.pin`
+ -file admin-cert.crt
+Certificate stored in file <admin-cert.crt></screen>
+ </step>
+
+ <step>
+ <para>Import the copy of the certificate into the trust store.</para>
+
+ <screen width="81">$ keytool
+ -import
+ -alias admin-cert
+ -keystore admin-truststore
+ -storepass `cat admin-keystore.pin`
+ -file admin-cert.crt
+Owner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate
+Issuer: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate
+Serial number: 904fc2b
+Valid from: Fri Mar 15 15:15:20 CET 2013 until: Thu Jun 13 16:15:20 CEST 2013
+Certificate fingerprints:
+ MD5: DD:2A:A1:3A:39:87:DF:02:15:A4:8A:9D:77:89:F1:E4
+ SHA1: E1:99:82:92:D7:9B:28:B7:93:D2:B5:5B:C9:DA:4E:D2:62:C2:E7:B0
+ SHA256: C5:34:9C:04:E2:87:A9:B1:72:B5:...:99:86:3A:02:28:D0:AB:02:5F:F4:BE
+ Signature algorithm name: SHA256withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: FE 33 69 67 FF E8 64 F6 D3 FB CD 14 1C D3 01 44 .3ig..d........D
+0010: EE 62 40 DD .b@.
+]
+]
+
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+ </step>
+
+ <step>
+ <para>Restart OpenDJ to make sure it reloads the key stores.</para>
+
+ <screen>$ cd /path/to/opendj/bin
+$ stop-ds --restart</screen>
+ </step>
+
+ <step>
+ <para>If you have client applications trusting the self-signed certificate,
+ have them import the new one (<filename>admin-cert.crt</filename> in this
+ example).</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="replace-ads-cert">
+ <title>To Replace the Key Pair Used for Replication</title>
+
+ <para>Follow these steps to replace the key pair that is used to
+ secure replication connections.</para>
+
+ <step>
+ <para>Generate a new key pair for the server.</para>
+
+ <para>The changes you perform are replicated across the topology.</para>
+
+ <para>OpenDJ has an <literal>ads-certificate</literal> and private
+ key, which is a local copy of the key pair used to secure replication
+ connections.</para>
+
+ <para>To generate the new key pair, you remove the
+ <literal>ads-certificate</literal> key pair, prompt OpenDJ to
+ generate a new <literal>ads-certificate</literal> key pair, and
+ then add a copy to the administrative data using the MD5 fingerprint
+ of the certificate to define the RDN.</para>
+
+ <substeps>
+ <step>
+ <para>Delete the <literal>ads-certificate</literal> entry.</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: ds-cfg-key-id=ads-certificate,cn=ads-truststore
+changetype: delete
+
+Processing DELETE request for ds-cfg-key-id=ads-certificate,cn=ads-truststore
+DELETE operation successful for DN ds-cfg-key-id=ads-certificate,
+ cn=ads-truststore</screen>
+ </step>
+
+ <step>
+ <para>Prompt OpenDJ to generate a new, self-signed
+ <literal>ads-certificate</literal> key pair.</para>
+
+ <para>You do this by adding an <literal>ads-certificate</literal> entry
+ with object class <literal>ds-cfg-self-signed-cert-request</literal>.</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: ds-cfg-key-id=ads-certificate,cn=ads-truststore
+changetype: add
+objectclass: ds-cfg-self-signed-cert-request
+
+Processing ADD request for ds-cfg-key-id=ads-certificate,cn=ads-truststore
+ADD operation successful for DN ds-cfg-key-id=ads-certificate,cn=ads-truststore</screen>
+ </step>
+
+ <step>
+ <para>Retrieve the <literal>ads-certificate</literal> entry.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN cn=ads-truststore
+ "(ds-cfg-key-id=ads-certificate)"
+dn: ds-cfg-key-id=ads-certificate,cn=ads-truststore
+ds-cfg-key-id: ads-certificate
+ds-cfg-public-key-certificate;binary:: MIIB6zCCAVSgAwIBAgIEDKSUFjANBgkqhkiG9w0BA
+ QUFADA6MRswGQYDVQQKExJPcGVuREogQ2VydGlmaWNhdGUxGzAZBgNVBAMTEm9wZW5hbS5leGFtcGxl
+ LmNvbTAeFw0xMzAyMDcxMDMwMzNaFw0zMzAyMDIxMDMwMzNaMDoxGzAZBgNVBAoTEk9wZW5ESiBDZXJ
+ 0aWZpY2F0ZTEbMBkGA1UEAxMSb3BlbmFtLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNAD
+ CBiQKBgQCfGLAiUOz4sC8CM9T5DPTk9V9ErNC8N59XwBt1aN7UjhQl4/JZZsetubtUrZBLS9cRrnYdZ
+ cpFgLQNEmXifS+PdZ0DJkaLNFmd8ZX0spX8++fb4SkkggkmNRmi1fccDQ/DHMlwl7kk884lXummrzcD
+ GbZ7p4vnY7y7GmD1vZSP+wIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJciUzUP8T8A9VV6dQB0SYCNG1o
+ 7IvpE7jGVZh6KvM0m5sBNX3wPbTVJQNij3TDm8nx6yhi6DUkpiAZfz/OBL5k+WSw80TjpIZ2+klhP1s
+ srsST4Um4fHzDZXOXHR6NM83XxZBsR6MazYecL8CiGwnYW2AeBapzbAnGn1J831q1q
+objectClass: top
+objectClass: ds-cfg-instance-key</screen>
+ </step>
+
+ <step>
+ <para>Retrieve the MD5 fingerprint of the
+ <literal>ads-certificate</literal>.</para>
+
+ <para>In this example, the MD5 fingerprint is
+ <literal>07:35:80:D8:F3:CE:E1:39:9C:D0:73:DB:6C:FA:CC:1C</literal>.</para>
+
+ <screen>$ keytool
+ -list
+ -v
+ -alias ads-certificate
+ -keystore /path/to/opendj/config/ads-truststore
+ -storepass `cat /path/to/opendj/config/ads-truststore.pin`
+Alias name: ads-certificate
+Creation date: Feb 7, 2013
+Entry type: PrivateKeyEntry
+Certificate chain length: 1
+Certificate[1]:
+Owner: CN=opendj.example.com, O=OpenDJ Certificate
+Issuer: CN=opendj.example.com, O=OpenDJ Certificate
+Serial number: ca49416
+Valid from: Thu Feb 07 11:30:33 CET 2013 until: Wed Feb 02 11:30:33 CET 2033
+Certificate fingerprints:
+ MD5: 07:35:80:D8:F3:CE:E1:39:9C:D0:73:DB:6C:FA:CC:1C
+ SHA1: 56:30:F6:79:AA:C0:BD:61:88:3E:FB:38:38:9D:84:70:0B:E4:43:57
+ SHA256: A8:4B:81:EE:30:2A:0C:09:2E:...:C1:41:F5:AB:19:C6:EE:AB:50:64
+ Signature algorithm name: SHA1withRSA
+ Version: 3</screen>
+ </step>
+
+ <step>
+ <para>Using the MD5 fingerprint and the certificate entry, prepare LDIF
+ to update <literal>cn=admin data</literal> with the new server
+ certificate.</para>
+
+ <screen>$ cat /path/to/update-server-cert.ldif
+dn: ds-cfg-key-id=073580D8F3CEE1399CD073DB6CFACC1C,cn=instance keys,
+ cn=admin data
+changetype: add
+ds-cfg-key-id: 073580D8F3CEE1399CD073DB6CFACC1C
+ds-cfg-public-key-certificate;binary:: MIIB6zCCAVSgAwIBAgIEDKSUFjANBgkqhkiG9w0BA
+ QUFADA6MRswGQYDVQQKExJPcGVuREogQ2VydGlmaWNhdGUxGzAZBgNVBAMTEm9wZW5hbS5leGFtcGxl
+ LmNvbTAeFw0xMzAyMDcxMDMwMzNaFw0zMzAyMDIxMDMwMzNaMDoxGzAZBgNVBAoTEk9wZW5ESiBDZXJ
+ 0aWZpY2F0ZTEbMBkGA1UEAxMSb3BlbmFtLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNAD
+ CBiQKBgQCfGLAiUOz4sC8CM9T5DPTk9V9ErNC8N59XwBt1aN7UjhQl4/JZZsetubtUrZBLS9cRrnYdZ
+ cpFgLQNEmXifS+PdZ0DJkaLNFmd8ZX0spX8++fb4SkkggkmNRmi1fccDQ/DHMlwl7kk884lXummrzcD
+ GbZ7p4vnY7y7GmD1vZSP+wIDAQABMA0GCSqGSIb3DQEBBQUAA4GBAJciUzUP8T8A9VV6dQB0SYCNG1o
+ 7IvpE7jGVZh6KvM0m5sBNX3wPbTVJQNij3TDm8nx6yhi6DUkpiAZfz/OBL5k+WSw80TjpIZ2+klhP1s
+ srsST4Um4fHzDZXOXHR6NM83XxZBsR6MazYecL8CiGwnYW2AeBapzbAnGn1J831q1q
+objectClass: top
+objectClass: ds-cfg-instance-key
+
+dn: cn=opendj.example.com:4444,cn=Servers,cn=admin data
+changetype: modify
+replace: ds-cfg-key-id
+ds-cfg-key-id: 073580D8F3CEE1399CD073DB6CFACC1C
+
+</screen>
+ </step>
+
+ <step>
+ <para>Update the administrative data, causing OpenDJ to create a
+ copy of the new <literal>ads-certificate</literal> with its MD5 signature
+ as the alias in the <filename>ads-truststore</filename>.</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename /path/to/update-server-cert.ldif
+Processing ADD request for ds-cfg-key-id=073580D8F3CEE1399CD073DB6CFACC1C,
+ cn=instance keys,cn=admin data
+ADD operation successful for DN ds-cfg-key-id=073580D8F3CEE1399CD073DB6CFACC1C,
+ cn=instance keys,cn=admin data
+Processing MODIFY request for cn=opendj.example.com:4444,cn=Servers,
+ cn=admin data
+MODIFY operation successful for DN cn=opendj.example.com:4444,cn=Servers,
+ cn=admin data</screen>
+ </step>
+ </substeps>
+ </step>
+
+ <step>
+ <para>Force OpenDJ to reopen replication connections using the new key
+ pair.</para>
+
+ <para>Stop replication temporarily and then start it again as described
+ in the <citetitle>Administration Guide</citetitle> section on <link
+ xlink:href="admin-guide#configure-repl"
+ xlink:role="http://docbook.org/xlink/role/olink"
+ ><citetitle>Configuring Replication</citetitle></link>.</para>
+
+ <screen>$ dsconfig
+ set-synchronization-provider-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --set enabled:false
+ --no-prompt
+$ dsconfig
+ set-synchronization-provider-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --set enabled:true
+ --no-prompt</screen>
+ </step>
+ </procedure>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-connection-handlers.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-connection-handlers.xml
new file mode 100644
index 0000000..833cd9f
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-connection-handlers.xml
@@ -0,0 +1,1325 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-connection-handlers'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Configuring Connection Handlers</title>
+ <indexterm><primary>Ports</primary><secondary>Configuring</secondary></indexterm>
+ <para>This chapter shows you how to configure OpenDJ directory server to
+ listen for directory client requests, using connection handlers. You can view
+ information about connection handlers in the OpenDJ Control Panel, and update
+ the configuration using the <command>dsconfig</command> command.</para>
+
+ <section xml:id="configure-ldap-port">
+ <title>LDAP Client Access</title>
+
+ <para>You configure LDAP client access by using the command-line tool
+ <command>dsconfig</command>. By default you configure OpenDJ to listen for
+ LDAP when you install.</para>
+
+ <para>The standard port number for LDAP client access is 389. If you
+ install OpenDJ directory server as a user who can use port 389 and the port
+ is not yet in use, then 389 is the default port number presented at
+ installation time. If you install as a user who cannot use a port < 1024,
+ then the default port number presented at installation time is 1389.</para>
+
+ <procedure xml:id="change-ldap-port">
+ <title>To Change the LDAP Port Number</title>
+
+ <step>
+ <para>Change the port number using the <command>dsconfig</command>
+ command.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAP Connection Handler"
+ --set listen-port:11389
+ --trustAll
+ --no-prompt</screen>
+ <para>This example changes the port number to 11389 in the configuration.</para>
+ </step>
+ <step>
+ <para>Restart the connection handler so the change takes effect.</para>
+ <para> To restart the connection handler, you disable it, then enable
+ it again.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAP Connection Handler"
+ --set enabled:false
+ --trustAll
+ --no-prompt
+$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAP Connection Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="setup-server-cert">
+ <title>Preparing For Secure Communications</title>
+ <indexterm><primary>Certificates</primary></indexterm>
+
+ <para>One common way to protect connections between OpenDJ and client
+ applications involves using StartTLS for LDAP or LDAPS to secure
+ connections. OpenDJ and client applications use X.509 digital certificates
+ to set up secure connections.</para>
+
+ <para>Both OpenDJ and client applications check that certificates are signed
+ by a trusted party before accepting them. Merely setting up a secure
+ connection therefore involves a sort of authentication using certificates.
+ If either OpenDJ or the client application cannot trust the peer certificate,
+ then the attempt to set up a secure connection must fail.</para>
+
+ <para>By default OpenDJ client tools prompt you if they do not recognize the
+ server certificate. Other clients might not prompt you. OpenDJ server has no
+ one to prompt when a client presents a certificate that cannot be
+ trusted, so it must simply refuse to set up the
+ connection.<footnote><para>Unless you use the Blind Trust Manager
+ Provider, which is recommended only for test purposes.</para></footnote>
+ In other words, it is important for both OpenDJ and client applications
+ to be able to verify that peer certificates exchanged have been signed by
+ a trusted party.</para>
+
+ <para>In practice this means that both OpenDJ and client applications must
+ put the certificates that were used to sign each others' certificates in their
+ respective trust stores. Conventionally, certificates are therefore signed by
+ a Certificate Authority (CA). A CA is trusted to sign other certificates. The
+ Java runtime environment for example comes with a trust store holding
+ certificates from many well-known CAs.<footnote><para><filename
+ >$JAVA_HOME/jre/lib/security/cacerts</filename> holds the CA certificates.
+ To read the full list, use the following command.</para>
+ <screen>$ keytool
+ -list
+ -v
+ -keystore $JAVA_HOME/jre/lib/security/cacerts
+ -storepass changeit</screen></footnote> If your client uses a valid
+ certificate signed by one of these CAs, then OpenDJ can verify the
+ certificate without additional configuration, because OpenDJ can find
+ the CA certificate in the Java CA certificate trust store. Likewise if
+ you set up StartTLS or LDAPS in OpenDJ using a valid certificate signed
+ by one of these CAs, then many client applications can verify the OpenDJ
+ server certificate without further configuration.</para>
+
+ <para>In summary, if you need a certificate to be recognized automatically,
+ get the certificate signed by a well-known CA.</para>
+
+ <para>You can, however, choose to have your certificates signed some other
+ way. You can set up your own CA. You can use a CA whose signing certificate
+ is not widely distributed. You can also use self-signed certificates. In each
+ case, you must add the signing certificates into the trust store of each
+ peer making secure connections.</para>
+
+ <para>For OpenDJ directory server, you can choose to import your own CA-signed
+ certificate as part of the installation process, or later using command-line
+ tools. Alternatively, you can let the OpenDJ installation program create a
+ self-signed certificate as part of the OpenDJ installation process. In
+ addition, you can add a signing certificate to the OpenDJ trust store using
+ the Java <command>keytool</command> command.</para>
+
+ <para>The following example shows the <command>keytool</command> command to
+ add a client application's binary format, self-signed certificate to the
+ OpenDJ trust store (assuming OpenDJ is already configured to use secure
+ connections). This enables OpenDJ to recognize the self-signed client
+ application certificate. (By definition a self-signed certificate is itself
+ the signing certificate. Notice that the Owner and the Issuer are the
+ same.)</para>
+
+ <screen>$ keytool
+ -import
+ -alias myapp-cert
+ -file myapp-cert.crt
+ -keystore /path/to/opendj/config/truststore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+Owner: CN=My App, OU=Apps, DC=example, DC=com
+Issuer: CN=My App, OU=Apps, DC=example, DC=com
+Serial number: 5ae2277
+Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
+Certificate fingerprints:
+ MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
+ SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
+ SHA256: 2D:B1:58:CD:33:40:E9:ED:...:EA:C9:FF:6A:19:93:FE:E4:84:E3
+ Signature algorithm name: SHA256withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E..
+0010: C9 6B 32 95 .k2.
+]
+]
+
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+
+ <para>When working with a certificate in printable encoding format (.pem)
+ rather than binary format, use the <option>-rfc</option> option, too.</para>
+
+ <para>Restart OpenDJ after adding certificates to the trust store to make
+ sure that OpenDJ reads the updated trust store file.</para>
+
+ <para>On the client side, if your applications are also Java applications,
+ then you can also import the OpenDJ signing certificate into the trust
+ store for the applications using the <command>keytool</command>
+ command.</para>
+
+ <para>The following example shows the <command>keytool</command> command
+ to export the OpenDJ self-signed certificate in binary format.</para>
+
+ <screen>$ keytool
+ -export
+ -alias server-cert
+ -file server-cert.crt
+ -keystore /path/to/opendj/config/keystore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+Certificate stored in file <server-cert.crt></screen>
+
+ <para>Importing the server certificate is similar to importing the client
+ certificate, as shown above.</para>
+
+ <para>The following sections describe how to get and install certificates
+ for OpenDJ directory server on the command line, for use when setting up
+ StartTLS or LDAPS.</para>
+
+ <procedure xml:id="new-ca-signed-cert">
+ <title>To Request and Install a CA-Signed Certificate</title>
+
+ <para>First you create a server certificate in a Java Key Store. Next you
+ issue a signing request to the CA, and get the CA-signed certificate as a
+ reply. Then you set up the Key Manager Provider and Trust Manager Provider
+ to rely on your new server certificate stored in the OpenDJ key store.</para>
+
+ <step>
+ <para>Generate the server certificate by using the Java
+ <command>keytool</command> command.</para>
+
+ <para>The CN attribute value is the FQDN for OpenDJ directory server, which
+ you can see under Server Details in the OpenDJ Control Panel.</para>
+
+ <screen>$ keytool
+ -genkey
+ -alias server-cert
+ -keyalg rsa
+ -dname "CN=opendj.example.com,O=Example Corp,C=FR"
+ -keystore /path/to/opendj/config/keystore
+ -storepass changeit
+ -keypass changeit</screen>
+
+ <note><para>Notice that the <option>-storepass</option> and
+ <option>-keypass</option> options take identical password arguments.
+ OpenDJ requires that you use the same password to protect both the keystore
+ and also the private key.</para></note>
+ </step>
+
+ <step>
+ <para>Create a certificate signing request file for the certificate you
+ generated.</para>
+
+ <screen>$ keytool
+ -certreq
+ -alias server-cert
+ -keystore /path/to/opendj/config/keystore
+ -storepass changeit
+ -file server-cert.csr</screen>
+ </step>
+
+ <step>
+ <para>Have the CA sign the request
+ (<filename>server-cert.csr</filename>).</para>
+ <para>See the instructions from your CA on how to provide the
+ request.</para>
+ <para>The CA returns the signed certificate.</para>
+
+ <!-- Create a CA cert for signing certificates.
+
+Not part of the procedure, but helpful when trying this out:
+http://social.rocho.org/jan/selfsign.html
+
+$ openssl genrsa -des3 -out ca.key 4096
+Generating RSA private key, 4096 bit long modulus
+.....++
+.......................++
+e is 65537 (0x10001)
+Enter pass phrase for ca.key:
+Verifying - Enter pass phrase for ca.key:
+
+$ openssl req -new -x509 -days 7300 -key ca.key -out ca.crt
+Enter pass phrase for ca.key:
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+
+Country Name (2 letter code) [AU]:FR
+State or Province Name (full name) [Some-State]:
+Locality Name (eg, city) []:Grenoble
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example Corp
+Organizational Unit Name (eg, section) []:
+Common Name (eg, YOUR name) []:Example CA
+Email Address []:mark.craig@forgerock.com
+
+$ openssl x509 -req -in server-cert.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server-cert.crt
+Signature ok
+subject=/C=FR/O=Example Corp/CN=openam.example.com
+Getting CA Private Key
+Enter pass phrase for ca.key:
+
+$ openssl x509 -req -in myapp-cert.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out myapp-cert.crt
+Signature ok
+subject=/DC=com/DC=example/OU=Apps/CN=My App
+Getting CA Private Key
+Enter pass phrase for ca.key:
+
+-->
+ </step>
+
+ <step>
+ <para>If you have set up your own CA and signed the certificate, or are
+ using a CA whose signing certificate is not included in the Java runtime
+ environment, import the CA certificate into the key store so that it can be
+ trusted.</para>
+
+ <para>Otherwise, when you import the signed certificate in the reply from
+ the (unknown) CA, <command>keytool</command> fails to import the signed
+ certificate with the message <literal>keytool error: java.lang.Exception:
+ Failed to establish chain from reply</literal>.</para>
+
+ <para>The following example illustrates import of a CA certificate created
+ with the <command>openssl</command> command. See the
+ <command>openssl</command> documentation for instructions on creating CAs
+ and on signing other certificates with the CA you created.</para>
+
+ <screen>$ keytool
+ -import
+ -keystore /path/to/opendj/config/keystore
+ -file ca.crt
+ -alias ca-cert
+ -storepass changeit
+Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
+Issuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
+Serial number: d4586ea05c878b0c
+Valid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
+Certificate fingerprints:
+ MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
+ SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
+ SHA256: 5D:20:F1:86:CC:CD:64:50:...:DF:15:43:07:69:44:00:FB:36:CF
+ Signature algorithm name: SHA1withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.35 Criticality=false
+AuthorityKeyIdentifier [
+KeyIdentifier [
+0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
+0010: 03 D4 56 7B ..V.
+]
+[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
+SerialNumber: [ d4586ea0 5c878b0c]
+]
+
+#2: ObjectId: 2.5.29.19 Criticality=false
+BasicConstraints:[
+ CA:true
+ PathLen:2147483647
+]
+
+#3: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
+0010: 03 D4 56 7B ..V.
+]
+]
+
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+ </step>
+
+ <step>
+ <para>Import the signed certificate from the CA reply into the keystore
+ where you generated the server certificate.</para>
+
+ <para>In this example the certificate from the reply is
+ <filename>~/Downloads/server-cert.crt</filename>.</para>
+
+ <screen>$ keytool
+ -import
+ -trustcacerts
+ -alias server-cert
+ -file ~/Downloads/server-cert.crt
+ -keystore /path/to/opendj/config/keystore
+ -storepass changeit
+ -keypass changeit
+Certificate reply was installed in keystore</screen>
+ </step>
+
+ <step>
+ <para>Configure the File Based Key Manager Provider for JKS to use the file
+ name and key store PIN that you set up with the <command>keytool</command>
+ command.</para>
+
+ <screen>$ dsconfig
+ set-key-manager-provider-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name JKS
+ --set enabled:true
+ --set key-store-pin:changeit
+ --remove key-store-pin-file:config/keystore.pin
+ --trustAll
+ --no-prompt</screen>
+ </step>
+
+ <step>
+ <para>Configure the File Based Trust Manager Provider for JKS to use the
+ key store and PIN as well.</para>
+
+ <screen>$ dsconfig
+ set-trust-manager-provider-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name JKS
+ --set enabled:true
+ --set trust-store-file:config/keystore
+ --set trust-store-pin:changeit
+ --trustAll
+ --no-prompt</screen>
+
+ <para>At this point, OpenDJ directory server can use your new CA-signed
+ certificate, for example for StartTLS and LDAPS connection handlers.</para>
+ </step>
+
+ <step>
+ <para>If you use a CA certificate that is not known to clients, such as a
+ CA that you set up yourself rather than a well-known CA whose certificate
+ is included with the client system, import the CA certificate into the
+ client application trust store. Otherwise the client application cannot
+ trust the signature on the OpenDJ CA-signed server certificate.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="new-self-signed-cert">
+ <title>To Create & Install a Self-Signed Certificate</title>
+
+ <para>If you choose to configure LDAP Secure Access when setting up OpenDJ
+ directory server, the setup program generates a key pair in the Java Key
+ Store <filename>/path/to/opendj/config/keystore</filename>, and self-signs
+ the public key certificate, which has the alias <literal>server-cert</literal>.
+ The password for the key store and the private key is stored in clear text
+ in the file <filename>/path/to/opendj/config/keystore.pin</filename>.</para>
+
+ <para>If you want to secure communications, but did not chose to configure
+ LDAP Secure Access at setup time, this procedure can help. The following
+ steps explain how to create and install a key pair with a self-signed
+ certificate in preparation to configure LDAPS or HTTPS. First you create a
+ key pair in a new Java Key Store, and then self-sign the certificate. Next,
+ you set up the Key Manager Provider and Trust Manager Provider to access
+ the new server certificate in the new key store.</para>
+
+ <para>If instead you want to <emphasis>replace the existing server key pair
+ with self-signed certificate</emphasis>, then first use <command>keytool
+ -delete -alias server-cert</command> to delete the existing keys before you
+ generate a new key pair with the same alias. You can also either reuse the
+ existing password in <filename>keystore.pin</filename>, or use a new password
+ as shown in the steps below.</para>
+
+ <step>
+ <para>Generate the server certificate using the Java
+ <command>keytool</command> command.</para>
+ <screen>$ keytool
+ -genkey
+ -alias server-cert
+ -keyalg rsa
+ -dname "CN=opendj.example.com,O=Example Corp,C=FR"
+ -keystore /path/to/opendj/config/keystore
+ -storepass changeit
+ -keypass changeit</screen>
+
+ <para>In this example, OpenDJ is running on a system with fully qualified
+ host name <literal>opendj.example.com</literal>. The Java Key Store (JKS)
+ is created in the <filename>config</filename> directory where OpenDJ is
+ installed, which is the default value for JKS.</para>
+
+ <note>
+ <para>Notice that the <option>-storepass</option> and
+ <option>-keypass</option> options take identical password arguments.
+ OpenDJ requires that you use the same password to protect both the
+ key store and also the private key.</para>
+ </note>
+
+ <para>Keep track of the password provided to the <option>-storepass</option>
+ and <option>-keypass</option> options.</para>
+ </step>
+ <step>
+ <para>Self-sign the server certificate.</para>
+ <screen>$ keytool
+ -selfcert
+ -alias server-cert
+ -keystore /path/to/opendj/config/keystore
+ -storepass changeit</screen>
+ </step>
+ <step>
+ <para>Configure the File Based Key Manager Provider for JKS to access the
+ Java Key Store with key store/private key password.</para>
+
+ <para>In this example, the alias is <literal>server-cert</literal> and the
+ password is <literal>changeit</literal>.</para>
+
+ <para>If you are replacing a key pair with a self-signed certificate,
+ reusing the <literal>server-cert</literal> alias and password stored in
+ <filename>keystore.pin</filename>, then you can skip this step.</para>
+
+ <screen>$ echo changeit > /path/to/opendj/config/keystore.pin
+$ chmod 600 /path/to/opendj/config/keystore.pin
+$ dsconfig
+ set-key-manager-provider-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name JKS
+ --set enabled:true
+ --set key-store-file:config/keystore
+ --set key-store-pin-file:config/keystore.pin
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Configure the File Based Trust Manager Provider for JKS to use the
+ key store and PIN as well.</para>
+
+ <para>If you skipped the previous step, you can also skip this step.</para>
+
+ <screen>$ dsconfig
+ set-trust-manager-provider-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name JKS
+ --set enabled:true
+ --set trust-store-file:config/keystore
+ --set trust-store-pin-file:config/keystore.pin
+ --trustAll
+ --no-prompt</screen>
+
+ <para>At this point, OpenDJ directory server can use your new self-signed
+ certificate, for example for StartTLS and LDAPS or HTTPS connection
+ handlers.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="configure-starttls">
+ <title>LDAP Client Access With Transport Layer Security</title>
+ <indexterm><primary>StartTLS</primary></indexterm>
+ <para>StartTLS (Transport Layer Security) negotiations start on the unsecure
+ LDAP port, and then protect communication with the client. You can opt to
+ configure StartTLS during installation, or later using the
+ <command>dsconfig</command> command.</para>
+
+ <procedure xml:id="setup-starttls-port">
+ <title>To Enable StartTLS on the LDAP Port</title>
+
+ <step>
+ <para>Make sure you have a server certificate installed.</para>
+
+ <screen>$ keytool
+ -list
+ -alias server-cert
+ -keystore /path/to/opendj/config/keystore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+server-cert, Jun 17, 2013, PrivateKeyEntry,
+Certificate fingerprint (SHA1): 92:B7:4C:4F:2E:24:...:EB:7C:22:3F
+ </screen>
+ </step>
+ <step>
+ <para>Activate StartTLS on the current LDAP port.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAP Connection Handler"
+ --set allow-start-tls:true
+ --set key-manager-provider:JKS
+ --set trust-manager-provider:JKS
+ --trustAll
+ --no-prompt</screen>
+ <para>The change takes effect. No need to restart the server.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="configure-ssl">
+ <title>LDAP Client Access Over SSL</title>
+ <indexterm><primary>SSL</primary></indexterm>
+ <para>You configure LDAPS (LDAP/SSL) client access by using the command-line
+ tool <command>dsconfig</command>. You can opt to configure LDAPS access
+ when you install.</para>
+
+ <para>The standard port number for LDAPS client access is 636. If you
+ install OpenDJ directory server as a user who can use port 636 and the port
+ is not yet in use, then 636 is the default port number presented at
+ installation time. If you install as a user who cannot use a port < 1024,
+ then the default port number presented at installation time is 1636.</para>
+
+ <procedure xml:id="setup-ssl-port">
+ <title>To Set Up LDAPS Access</title>
+
+ <step>
+ <para>Make sure you have a server certificate installed.</para>
+
+ <screen>$ keytool
+ -list
+ -alias server-cert
+ -keystore /path/to/opendj/config/keystore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+server-cert, Jun 17, 2013, PrivateKeyEntry,
+Certificate fingerprint (SHA1): 92:B7:4C:4F:2E:24:...:EB:7C:22:3F
+ </screen>
+ </step>
+ <step>
+ <para>Configure the server to activate LDAPS access.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAPS Connection Handler"
+ --set listen-port:1636
+ --set enabled:true
+ --set use-ssl:true
+ --trustAll
+ --no-prompt</screen>
+ <para>This example changes the port number to 1636 in the configuration.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="change-ssl-port">
+ <title>To Change the LDAPS Port Number</title>
+
+ <step>
+ <para>Change the port number using the <command>dsconfig</command>
+ command.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAPS Connection Handler"
+ --set listen-port:11636
+ --trustAll
+ --no-prompt</screen>
+ <para>This example changes the port number to 11636 in the configuration.</para>
+ </step>
+ <step>
+ <para>Restart the connection handler so the change takes effect.</para>
+ <para> To restart the connection handler, you disable it, then enable
+ it again.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAPS Connection Handler"
+ --set enabled:false
+ --trustAll
+ --no-prompt
+$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAPS Connection Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="restrict-clients">
+ <title>Restricting Client Access</title>
+ <indexterm><primary>Access control</primary></indexterm>
+
+ <para>Using the OpenDJ directory server global configuration properties, you
+ can add global restrictions on how clients access the server. These settings
+ are per server, and so much be set independently on each server in replication
+ topology.</para>
+
+ <para>These global settings are fairly coarse-grained. For a full discussion
+ of the rich set of administrative privileges and fine-grained access control
+ instructions that OpenDJ supports, see the chapter on <link
+ xlink:href="admin-guide#chap-privileges-acis"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
+ Privileges & Access Control</citetitle></link>.</para>
+
+ <variablelist>
+ <para>Consider the following global configuration settings.</para>
+
+ <varlistentry>
+ <term><literal>bind-with-dn-requires-password</literal></term>
+ <listitem>
+ <para>Whether the directory server should reject any simple bind request
+ that contains a DN but no password. Default: <literal>true</literal></para>
+ <para>To change this setting use the following command.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set bind-with-dn-requires-password:false
+ --no-prompt</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>max-allowed-client-connections</literal></term>
+ <listitem>
+ <para>Restricts the number of concurrent client connections to the
+ directory server. Default: 0, meaning no limit is set</para>
+ <para>To set a limit of 32768 use the following command.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set max-allowed-client-connections:32768
+ --no-prompt</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>reject-unauthenticated-requests</literal></term>
+ <listitem>
+ <para>Rejects any request (other than bind or StartTLS requests) received
+ from a client that has not yet been authenticated, whose last
+ authentication attempt was unsuccessful, or whose last authentication
+ attempt used anonymous authentication. Default: <literal>false</literal></para>
+ <para>To shut down anonymous binds use the following command.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set reject-unauthenticated-requests:true
+ --no-prompt</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>return-bind-error-messages</literal></term>
+ <listitem>
+ <para>Does not restrict access, but by default prevents OpenDJ directory
+ server from returning extra information about why a bind failed, as that
+ information could be used by an attacker. Instead, the information is
+ written to the server errors log. Default: <literal>false</literal></para>
+ <para>To have OpenDJ return additional information about why a bind failed
+ use the following command.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set return-bind-error-messages:true
+ --no-prompt</screen>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="tls-protocols-cipher-suites">
+ <title>TLS Protocols & Cipher Suites</title>
+ <indexterm>
+ <primary>TLS</primary>
+ </indexterm>
+
+ <para>By default OpenDJ supports the SSL and TLS protocols and the cipher
+ suites supported by the underlying Java virtual machine. For details see the
+ documentation for the Java virtual machine in which you run OpenDJ. For Oracle
+ Java, see the <citetitle>Java Cryptography Architecture Oracle Providers
+ Documentation</citetitle> for the <link xlink:show="new"
+ xlink:href="http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider"
+ >The <literal>SunJSSE</literal> Provider</link>.</para>
+
+ <para>To list the available protocols and cipher suites, read the
+ <literal>supportedTLSProtocols</literal> and
+ <literal>supportedTLSCiphers</literal> attributes of the root DSE. Install
+ unlimited strength Java cryptography extensions for stronger ciphers.</para>
+
+ <screen
+ >$ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)"
+ supportedTLSCiphers supportedTLSProtocols
+dn:
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_RC4_128_SHA
+supportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
+supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
+supportedTLSProtocols: SSLv2Hello
+supportedTLSProtocols: SSLv3
+supportedTLSProtocols: TLSv1
+supportedTLSProtocols: TLSv1.1
+supportedTLSProtocols: TLSv1.2
+</screen>
+
+ <para>You can restrict the list of protocols and cipher suites used by setting
+ the <literal>ssl-protocol</literal> and <literal>ssl-cipher-suite</literal>
+ connection handler properties to include only the protocols or cipher suites
+ you want.</para>
+
+ <para>For example, to restrict the cipher suites to
+ <literal>TLS_EMPTY_RENEGOTIATION_INFO_SCSV</literal> and
+ <literal>TLS_RSA_WITH_AES_256_CBC_SHA</literal> use the <command>dsconfig
+ set-connection-handler-prop</command> command as shown in the following
+ example.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAPS Connection Handler"
+ --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV
+ --add ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA
+ --no-prompt
+ --trustAll</screen>
+ </section>
+
+ <section xml:id="setup-rest2ldap">
+ <title>RESTful Client Access</title>
+ <indexterm><primary>HTTP</primary></indexterm>
+ <indexterm><primary>JSON</primary></indexterm>
+ <indexterm><primary>REST</primary></indexterm>
+
+ <orderedlist>
+ <para>OpenDJ offers two ways to give RESTful client applications HTTP access
+ to directory data as JSON resources.</para>
+
+ <listitem>
+ <para>Enable the listener on OpenDJ directory server to respond
+ to REST requests.</para>
+
+ <para>With this approach, you do not need to install additional
+ software.</para>
+ </listitem>
+
+ <listitem>
+ <para>Configure the external REST LDAP gateway Servlet to access your
+ directory service.</para>
+
+ <para>With this approach, you must install the gateway separately.</para>
+ </listitem>
+ </orderedlist>
+
+ <procedure xml:id="setup-rest2ldap-connection-handler">
+ <title>To Set Up REST Access to OpenDJ Directory Server</title>
+
+ <para>OpenDJ directory server has a handler for HTTP connections, where it
+ exposes the RESTful API demonstrated in the chapter on
+ <link xlink:href="admin-guide#chap-rest-operations" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Performing
+ RESTful Operations</citetitle></link>. The HTTP connection handler is not
+ enabled by default.</para>
+
+ <para>You configure the mapping between JSON resources and LDAP entries
+ by editing the configuration file for the HTTP connection handler, by
+ default <filename>/path/to/opendj/config/http-config.json</filename>. The
+ configuration is described in the appendix, <link xlink:show="new"
+ xlink:href="admin-guide#appendix-rest2ldap"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
+ Configuration</citetitle></link>. The default mapping works out of the box
+ with Example.com data generated as part of the setup process and with
+ <link xlink:show="new" xlink:href="http://opendj.forgerock.org/Example.ldif"
+ >Example.ldif</link>.</para>
+
+ <step>
+ <para>Enable the connection handler.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ --set enabled:true
+ --no-prompt
+ --trustAll</screen>
+ </step>
+
+ <step>
+ <para>Enable the HTTP access log.</para>
+
+ <screen>$ dsconfig
+ set-log-publisher-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based HTTP Access Logger"
+ --set enabled:true
+ --no-prompt
+ --trustAll</screen>
+
+ <para>This enables the HTTP access log,
+ <filename>opendj/logs/http-access</filename>. For details on the
+ format of the HTTP access log, see the section on <link xlink:show="new"
+ xlink:href="admin-guide#logging"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Server
+ Logs</citetitle></link>.</para>
+ </step>
+
+ <step performance="optional">
+ <para>Try reading a resource.</para>
+
+ <para>The HTTP connection handler paths start by default at the root
+ context, as shown in the following example.</para>
+
+ <screen>$ curl http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen
+ ?_prettyPrint=true
+{
+ "_rev" : "00000000315fb731",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1862",
+ "emailAddress" : "bjensen@example.com"
+ },
+ "_id" : "bjensen",
+ "name" : {
+ "familyName" : "Jensen",
+ "givenName" : "Barbara"
+ },
+ "userName" : "bjensen@example.com",
+ "displayName" : "Barbara Jensen"
+}</screen>
+ </step>
+
+ <step performance="optional">
+ <para>If necessary, change the connection handler configuration using the
+ <command>dsconfig</command> command.</para>
+
+ <para>The following example shows how to set the port to 8443, and to
+ configure the connection handler to do SSL (using the default server
+ certificate). If you did not generate a default, self-signed certificate
+ when installing OpenDJ directory server see the instructions, <link
+ xlink:show="new" xlink:href="admin-guide#new-self-signed-cert"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Create &
+ Install a Self-Signed Certificate</citetitle></link>, and more generally the
+ section on <link xlink:show="new"
+ xlink:href="admin-guide#setup-server-cert"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
+ Secure Communications</citetitle></link> for additional instructions
+ including how to import a CA-signed certificate.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ --set listen-port:8443
+ --set use-ssl:true
+ --set key-manager-provider:JKS
+ --set trust-manager-provider:"Blind Trust"
+ --no-prompt
+$ stop-ds --restart
+Stopping Server...
+.... The Directory Server has started successfully
+$ keytool
+ -export
+ -rfc
+ -alias server-cert
+ -keystore /path/to/opendj/config/keystore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+ -file server-cert.pem
+Certificate stored in file <server-cert.pem>
+$ curl
+ --cacert server-cert.pem
+ --user bjensen:hifalutin
+ https://opendj.example.com:8443/users/bjensen?_prettyPrint=true
+{
+ "_rev" : "0000000018c8b685",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1862",
+ "emailAddress" : "bjensen@example.com"
+ },
+ "_id" : "bjensen",
+ "name" : {
+ "familyName" : "Jensen",
+ "givenName" : "Barbara"
+ },
+ "userName" : "bjensen@example.com",
+ "displayName" : "Barbara Jensen",
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ]
+}</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="setup-rest2ldap-gateway">
+ <title>To Set Up OpenDJ REST LDAP Gateway</title>
+
+ <para>Follow these steps to set up OpenDJ REST LDAP gateway Servlet to access
+ your directory service.</para>
+
+ <step>
+ <para>Download and install the gateway as described in <link
+ xlink:href="install-guide#install-rest2ldap-servlet"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Install
+ OpenDJ REST LDAP Gateway</citetitle></link>.</para>
+ </step>
+
+ <step>
+ <para>Adjust the configuration for your directory service as described in
+ <link xlink:href="admin-guide#appendix-rest2ldap"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
+ Configuration</citetitle></link>.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="setup-dsml">
+ <title>DSML Client Access</title>
+ <indexterm><primary>DSML</primary></indexterm>
+
+ <para>Directory Services Markup Language (DSML) client access is implemented
+ as a servlet that runs in a web application container.</para>
+
+ <para>You configure DSML client access by editing the
+ <filename>WEB-INF/web.xml</filename> after you deploy the web
+ application. In particular, you must at least set the
+ <literal>ldap.host</literal> and <literal>ldap.port</literal> parameters
+ if they differ from the default values, which are
+ <literal>localhost</literal> and <literal>389</literal>.</para>
+
+ <variablelist>
+ <para>The list of DSML configuration parameters, including those that are
+ optional, consists of the following.</para>
+ <varlistentry>
+ <term><literal>ldap.host</literal></term>
+ <listitem>
+ <para>Required parameter indicating the host name of the underlying
+ directory server. Default: <literal>localhost</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.port</literal></term>
+ <listitem>
+ <para>Required parameter indicating the LDAP port of the underlying
+ directory server. Default: 389.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.userdn</literal></term>
+ <listitem>
+ <para>Optional parameter specifying the DN used by the DSML gateway to
+ bind to the underlying directory server. Not used by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.userpassword</literal></term>
+ <listitem>
+ <para>Optional parameter specifying the password used by the DSML gateway
+ to bind to the underlying directory server. Not used by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.authzidtypeisid</literal></term>
+ <listitem>
+ <para>This parameter can help you set up the DSML gateway to do HTTP
+ Basic Access Authentication, given the appropriate mapping between the
+ user ID, and the user's entry in the directory.</para>
+ <para>Required boolean parameter specifying whether the HTTP Authorization
+ header field's Basic credentials in the request hold a plain ID, rather
+ than a DN. If set to <literal>true</literal>, then the gateway performs an
+ LDAP SASL bind using SASL plain, enabled by default in OpenDJ to look for
+ an exact match between a <literal>uid</literal> value and the plain ID
+ value from the header. In other words, if the plain ID is
+ <literal>bjensen</literal>, and that corresponds in the directory server
+ to Babs Jensen's entry with DN
+ <literal>uid=bjensen,ou=people,dc=example,dc=com</literal>, then the bind
+ happens as Babs Jensen. Note also that you can configure OpenDJ identity
+ mappers for scenarios that use a different attribute than
+ <literal>uid</literal>, such as the <literal>mail</literal>
+ attribute.</para>
+ <para>Default: <literal>false</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.usessl</literal></term>
+ <listitem>
+ <para>Required parameter indicating whether <literal>ldap.port</literal>
+ points to a port listening for LDAPS (LDAP/SSL) traffic. Default:
+ <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.usestarttls</literal></term>
+ <listitem>
+ <para>Required parameter indicating whether to use StartTLS to connect
+ to the specified <literal>ldap.port</literal>. Default:
+ <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.trustall</literal></term>
+ <listitem>
+ <para>Required parameter indicating whether blindly to trust all
+ certificates presented to the DSML gateway when using secure connections
+ (LDAPS or StartTLS). Default: <literal>false</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.truststore.path</literal></term>
+ <listitem>
+ <para>Optional parameter indicating the trust store used to verify
+ certificates when using secure connections. If you want to connect
+ using LDAPS or StartTLS, and do not want the gateway blindly to trust
+ all certificates, then you must set up a trust store. Not used by
+ default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap.truststore.password</literal></term>
+ <listitem>
+ <para>Optional parameter indicating the trust store password. If you
+ set up and configure a trust store, then you need to set this as well.
+ Not used by default.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The DSML servlet translates between DSML and LDAP, and passes requests
+ to the directory server. For initial testing purposes, you might try
+ <link xlink:href="http://jxplorer.org/">JXplorer</link>, where DSML Service:
+ /<replaceable>webapp-dir</replaceable>/DSMLServlet. Here,
+ <replaceable>webapp-dir</replaceable> refers to the name of the directory
+ in which you unpacked the DSML .war file.</para>
+
+ <mediaobject xml:id="figure-jxplorer-dsml">
+ <imageobject>
+ <imagedata fileref="images/JXplorer-dsml.png" format="PNG" />
+ </imageobject>
+ <caption><para>JXplorer accessing OpenDJ through DSML</para></caption>
+ </mediaobject>
+ </section>
+
+ <section xml:id="jmx-access">
+ <title>JMX Client Access</title>
+ <indexterm><primary>JMX</primary></indexterm>
+
+ <para>You configure Java Management Extensions (JMX) client access by using
+ the command-line tool, <command>dsconfig</command>.</para>
+
+ <procedure xml:id="setup-jmx">
+ <title>To Set Up JMX Access</title>
+
+ <step>
+ <para>Configure the server to activate JMX access.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "JMX Connection Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+ <para>This example uses the default port number, 1689.</para>
+ </step>
+ <step>
+ <para>Restart the server so the change takes effect.</para>
+ <screen>$ stop-ds --restart</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="access-jmx">
+ <title>To Configure Access To JMX</title>
+
+ <para>After you set up OpenDJ directory server to listen for JMX connections,
+ you must assign privileges in order to allow a user to connect over
+ protocol.</para>
+
+ <step>
+ <para>Assign the privileges, <literal>jmx-notify</literal>,
+ <literal>jmx-read</literal>, and <literal>jmx-write</literal> as
+ necessary to the user who connects over JMX.</para>
+ <para>See the section on <link xlink:href="admin-guide#configure-privileges"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
+ Privileges</citetitle></link> for details.</para>
+ </step>
+ <step>
+ <para>Connect using the service URI, user name, and password.</para>
+ <variablelist>
+ <varlistentry>
+ <term>Service URI</term>
+ <listitem>
+ <para>Full URI to the service including the hostname or IP address
+ and port number for JMX where OpenDJ directory server listens for
+ connections. For example, if the server IP is
+ <literal>192.168.0.10</literal> and you configured OpenDJ to listen
+ for JMX connections on port 1689, then the service URI is
+ <literal>service:jmx:rmi:///jndi/rmi://192.168.0.10:1689/org.opends.server.protocols.jmx.client-unknown</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>User name</term>
+ <listitem>
+ <para>The full DN of the user with privileges to connect over JMX such
+ as <literal>uid=kvaughan,ou=People,dc=example,dc=com</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Password</term>
+ <listitem>
+ <para>The bind password for the user.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="ldif-access">
+ <title>LDIF File Access</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>File as backend</secondary>
+ </indexterm>
+
+ <para>The LDIF connection handler lets you make changes to directory data
+ by placing LDIF in a file system directory that OpenDJ server regularly
+ polls for changes. The LDIF, once consumed, is deleted.</para>
+
+ <para>You configure LDIF file access by using the command-line tool
+ <command>dsconfig</command>.</para>
+
+ <procedure xml:id="setup-ldif-access">
+ <title>To Set Up LDIF File Access</title>
+
+ <step>
+ <para>Activate LDIF file access.</para>
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDIF Connection Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+ <para>The change takes effect immediately.</para>
+ </step>
+ <step>
+ <para>Add the directory where you put LDIF to be processed.</para>
+ <screen>$ mkdir /path/to/opendj/config/auto-process-ldif</screen>
+ <para>This example uses the default value of the
+ <literal>ldif-directory</literal> property for the LDIF connection
+ handler.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="snmp-access">
+ <title>SNMP Access</title>
+
+ <para>For instructions on setting up the SNMP Connection Handler, see the
+ section, <link xlink:href="admin-guide#snmp-monitoring"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>SNMP-Based
+ Monitoring</citetitle></link>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-failover.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-failover.xml
new file mode 100644
index 0000000..aad8e27
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-failover.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-failover'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Configuring Health Checks & Failover Policies</title>
+
+ <para>Directory proxy servers use health checks and failover policies
+ to switch from one directory server to another when something goes wrong
+ either with the directory server or with the network access to the
+ directory server. You can configure how the proxy determines to make
+ the switch. This chapter describes how to carry out the configuration.</para>
+
+</chapter>
+
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-groups.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-groups.xml
new file mode 100644
index 0000000..69b6623
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-groups.xml
@@ -0,0 +1,487 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-groups'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Working With Groups of Entries</title>
+
+ <para>OpenDJ supports several methods of grouping entries in the directory.
+ Static groups list their members, whereas dynamic groups look up their
+ membership based on an LDAP filter. OpenDJ also supports virtual static
+ groups, which uses a dynamic group style definition, but allows applications
+ to list group members as if the group were static.</para>
+
+ <para>When listing entries in static groups, you must also have a mechanism
+ for removing entries from the list when they are deleted or modified in ways
+ that end their membership. OpenDJ makes that possible with
+ <emphasis>referential integrity</emphasis> functionality.</para>
+
+ <para>This chapter demonstrates how to work with groups.</para>
+
+ <tip>
+ <para>The examples in this chapter assume that an
+ <literal>ou=Groups,dc=example,dc=com</literal> entry already exists. If you
+ imported data from <link xlink:href="http://opendj.forgerock.org/Example.ldif"
+ xlink:show="new">Example.ldif</link>, then you already have the entry. If you
+ generated data during setup and did not create an organizational unit for
+ groups yet, create the entry before you try the examples.</para>
+
+ <screen>$ ldapmodify
+ --defaultAdd
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: ou=Groups,dc=example,dc=com
+objectClass: organizationalunit
+objectClass: top
+ou: Groups
+
+Processing ADD request for ou=Groups,dc=example,dc=com
+ADD operation successful for DN ou=Groups,dc=example,dc=com</screen>
+ </tip>
+
+ <section xml:id="static-groups">
+ <title>Creating Static Groups</title>
+ <indexterm>
+ <primary>Groups</primary>
+ <secondary>Static</secondary>
+ </indexterm>
+
+ <para>A <firstterm>static group</firstterm> is expressed as an entry
+ that enumerates all the entries that belong to the group. Static group
+ entries grow as their membership increases.</para>
+
+ <para>Static group entries can take the standard object class
+ <literal>groupOfNames</literal> where each <literal>member</literal>
+ attribute value is a distinguished name of an entry, or
+ <literal>groupOfUniqueNames</literal> where each
+ <literal>uniqueMember</literal> attribute value has Name and Optional UID
+ syntax.<footnote><para>Name and Optional UID syntax values are a DN optionally
+ followed by <literal>#<replaceable>BitString</replaceable></literal>. The
+ <replaceable>BitString</replaceable>, such as <literal>'0101111101'B</literal>,
+ serves to distinguish the entry from another entry having the same DN, which
+ can occur when the original entry was deleted and a new entry created with the
+ same DN.</para></footnote> Like other LDAP attributes,
+ <literal>member</literal> and <literal>uniqueMember</literal> attributes take
+ sets of unique values.</para>
+
+ <para>Static group entries can also have the object class
+ <literal>groupOfEntries</literal>, which is like
+ <literal>groupOfNames</literal> except that it is designed to allow
+ groups not to have members.</para>
+
+ <para>When creating a group entry, use <literal>groupOfNames</literal> or
+ <literal>groupOfEntries</literal> where possible.</para>
+
+ <para>To create a static group, add a group entry such as the following
+ to the directory.</para>
+
+ <screen>$ cat static.ldif
+dn: cn=My Static Group,ou=Groups,dc=example,dc=com
+cn: My Static Group
+objectClass: groupOfNames
+objectClass: top
+ou: Groups
+member: uid=ahunter,ou=People,dc=example,dc=com
+member: uid=bjensen,ou=People,dc=example,dc=com
+member: uid=tmorris,ou=People,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename static.ldif
+Processing ADD request for cn=My Static Group,ou=Groups,dc=example,dc=com
+ADD operation successful for DN cn=My Static Group,ou=Groups,dc=example,dc=com</screen>
+
+ <para>To change group membership, modify the values of the membership
+ attribute.</para>
+
+ <screen>$ cat add2grp.ldif
+dn: cn=My Static Group,ou=Groups,dc=example,dc=com
+changetype: modify
+add: member
+member: uid=scarter,ou=People,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename add2grp.ldif
+Processing MODIFY request for cn=My Static Group,ou=Groups,dc=example,dc=com
+MODIFY operation successful for DN
+ cn=My Static Group,ou=Groups,dc=example,dc=com
+$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(cn=My Static Group)"
+dn: cn=My Static Group,ou=Groups,dc=example,dc=com
+ou: Groups
+objectClass: groupOfNames
+objectClass: top
+member: uid=ahunter,ou=People,dc=example,dc=com
+member: uid=bjensen,ou=People,dc=example,dc=com
+member: uid=tmorris,ou=People,dc=example,dc=com
+member: uid=scarter,ou=People,dc=example,dc=com
+cn: My Static Group</screen>
+
+ <para>RFC 4519 says a <literal>groupOfNames</literal> entry must have
+ at least one member. Although OpenDJ allows you to create a
+ <literal>groupOfNames</literal> without members, strictly speaking that
+ behavior is not standard. Alternatively, you can use the
+ <literal>groupOfEntries</literal> object class as shown in the following
+ example.</para>
+
+ <screen>$ cat group-of-entries.ldif
+dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
+cn: Initially Empty Static Group
+objectClass: groupOfEntries
+objectClass: top
+ou: Groups
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename group-of-entries.ldif
+Processing ADD request for
+ cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
+ADD operation successful for DN
+ cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
+$ cat add-members.ldif
+# Now add some members to the group.
+dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
+changetype: modify
+add: member
+member: uid=ahunter,ou=People,dc=example,dc=com
+member: uid=bjensen,ou=People,dc=example,dc=com
+member: uid=tmorris,ou=People,dc=example,dc=com
+member: uid=scarter,ou=People,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename add-members.ldif
+Processing MODIFY request for
+ cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
+MODIFY operation successful for DN
+ cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com</screen>
+ </section>
+
+ <section xml:id="dynamic-groups">
+ <title>Creating Dynamic Groups</title>
+ <indexterm>
+ <primary>Groups</primary>
+ <secondary>Dynamic</secondary>
+ </indexterm>
+
+ <para>A <firstterm>dynamic group</firstterm> specifies members using
+ LDAP URLs. Dynamic groups entries can stay small even as their
+ membership increases.</para>
+
+ <para>Dynamic group entries take the <literal>groupOfURLs</literal>
+ object class, with one or more <literal>memberURL</literal> values
+ specifying LDAP URLs to identify group members.</para>
+
+ <para>To create a dynamic group, add a group entry such as the following to
+ the directory.</para>
+
+ <para>The following example builds a dynamic group of entries effectively
+ matching the filter <literal>"(l=Cupertino)"</literal> (users whose location
+ is Cupertino). Change the filter if your data is different, and so no
+ entries have <literal>l: Cupertino</literal>.</para>
+
+ <screen>$ cat dynamic.ldif
+dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
+cn: My Dynamic Group
+objectClass: top
+objectClass: groupOfURLs
+ou: Groups
+memberURL: ldap:///ou=People,dc=example,dc=com??sub?l=Cupertino
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename dynamic.ldif
+Processing ADD request for cn=My Dynamic Group,ou=Groups,dc=example,dc=com
+ADD operation successful for DN cn=My Dynamic Group,ou=Groups,dc=example,dc=com</screen>
+
+ <para>Group membership changes dynamically as entries change to match the
+ <literal>memberURL</literal> values.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(&(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))"
+ mail
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+mail: rjensen@example.com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: uid=ajensen,ou=People,dc=example,dc=com
+changetype: modify
+replace: l
+l: Cupertino
+
+Processing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=ajensen,ou=People,dc=example,dc=com
+^D
+$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(&(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))"
+ mail
+dn: uid=ajensen,ou=People,dc=example,dc=com
+mail: ajensen@example.com
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+mail: rjensen@example.com</screen>
+ </section>
+
+ <section xml:id="virtual-static-groups">
+ <title>Creating Virtual Static Groups</title>
+ <indexterm>
+ <primary>Groups</primary>
+ <secondary>Virtual static</secondary>
+ </indexterm>
+
+ <para>OpenDJ lets you create <firstterm>virtual static groups</firstterm>,
+ which let applications see dynamic groups as what appear to be static
+ groups.</para>
+
+ <para>The virtual static group takes auxiliary object class
+ <literal>ds-virtual-static-group</literal>. Virtual static groups also take
+ either the object class <literal>groupOfNames</literal>, or
+ <literal>groupOfUniqueNames</literal>, but instead of having
+ <literal>member</literal> or <literal>uniqueMember</literal> attributes,
+ have <literal>ds-target-group-dn</literal> attributes pointing to other
+ groups.</para>
+
+ <para>Generating the list of members can be resource intensive for large
+ groups, so by default you cannot retrieve the list of members. You can
+ change this with the <command>dsconfig</command> command by setting the
+ <literal>Virtual Static member</literal> or
+ <literal>Virtual Static uniqueMember</literal> property.</para>
+
+ <screen>$ dsconfig
+ set-virtual-attribute-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --name "Virtual Static member"
+ --set allow-retrieving-membership:true
+ --trustAll
+ --no-prompt</screen>
+
+ <para>The following example creates a virtual static group, and reads the
+ group entry with all members.</para>
+
+ <screen>$ cat virtual.ldif
+dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
+cn: Virtual Static
+objectclass: top
+objectclass: groupOfNames
+objectclass: ds-virtual-static-group
+ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename virtual.ldif
+Processing ADD request for cn=Virtual Static,ou=Groups,dc=example,dc=com
+ADD operation successful for DN cn=Virtual Static,ou=Groups,dc=example,dc=com
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Virtual Static)"
+dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
+objectClass: groupOfNames
+objectClass: ds-virtual-static-group
+objectClass: top
+member: uid=jwalker,ou=People,dc=example,dc=com
+member: uid=jmuffly,ou=People,dc=example,dc=com
+member: uid=tlabonte,ou=People,dc=example,dc=com
+member: uid=dakers,ou=People,dc=example,dc=com
+member: uid=jreuter,ou=People,dc=example,dc=com
+member: uid=rfisher,ou=People,dc=example,dc=com
+member: uid=pshelton,ou=People,dc=example,dc=com
+member: uid=rjensen,ou=People,dc=example,dc=com
+member: uid=jcampaig,ou=People,dc=example,dc=com
+member: uid=mjablons,ou=People,dc=example,dc=com
+member: uid=mlangdon,ou=People,dc=example,dc=com
+member: uid=aknutson,ou=People,dc=example,dc=com
+member: uid=bplante,ou=People,dc=example,dc=com
+member: uid=awalker,ou=People,dc=example,dc=com
+member: uid=smason,ou=People,dc=example,dc=com
+member: uid=ewalker,ou=People,dc=example,dc=com
+member: uid=dthorud,ou=People,dc=example,dc=com
+member: uid=btalbot,ou=People,dc=example,dc=com
+member: uid=tcruse,ou=People,dc=example,dc=com
+member: uid=kcarter,ou=People,dc=example,dc=com
+member: uid=aworrell,ou=People,dc=example,dc=com
+member: uid=bjensen,ou=People,dc=example,dc=com
+member: uid=ajensen,ou=People,dc=example,dc=com
+member: uid=cwallace,ou=People,dc=example,dc=com
+member: uid=mwhite,ou=People,dc=example,dc=com
+member: uid=kschmith,ou=People,dc=example,dc=com
+member: uid=mtalbot,ou=People,dc=example,dc=com
+member: uid=tschmith,ou=People,dc=example,dc=com
+member: uid=gfarmer,ou=People,dc=example,dc=com
+member: uid=speterso,ou=People,dc=example,dc=com
+member: uid=prose,ou=People,dc=example,dc=com
+member: uid=jbourke,ou=People,dc=example,dc=com
+member: uid=mtyler,ou=People,dc=example,dc=com
+member: uid=abergin,ou=People,dc=example,dc=com
+member: uid=mschneid,ou=People,dc=example,dc=com
+cn: Virtual Static
+ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com</screen>
+ </section>
+
+ <section xml:id="group-membership">
+ <title>Looking Up Group Membership</title>
+ <indexterm>
+ <primary>Groups</primary>
+ <secondary>Membership</secondary>
+ </indexterm>
+
+ <para>OpenDJ lets you look up which groups a user belongs to by using the
+ <literal>isMemberOf</literal> attribute.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ isMemberOf
+dn: uid=bjensen,ou=People,dc=example,dc=com
+isMemberOf: cn=My Static Group,ou=Groups,dc=example,dc=com
+isMemberOf: cn=Virtual Static,ou=Groups,dc=example,dc=com
+isMemberOf: cn=My Dynamic Group,ou=Groups,dc=example,dc=com</screen>
+
+ <para>You must request <literal>isMemberOf</literal> explicitly.</para>
+ </section>
+
+ <section xml:id="referential-integrity">
+ <title>Configuring Referential Integrity</title>
+ <indexterm>
+ <primary>Groups</primary>
+ <secondary>Referential integrity</secondary>
+ </indexterm>
+
+ <para>When you delete or rename an entry that belongs to static groups, that
+ entry's DN must be removed or changed in the list of each group to which it
+ belongs. You can configure OpenDJ to resolve membership on your behalf after
+ the change operation succeeds by enabling referential integrity.</para>
+
+ <para>Referential integrity functionality is implemented as a plugin. The
+ referential integrity plugin is disabled by default. To enable the plugin,
+ use the <command>dsconfig</command> command.</para>
+
+ <screen>$ dsconfig
+ set-plugin-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --plugin-name "Referential Integrity"
+ --set enabled:true
+ --trustAll --no-prompt</screen>
+
+ <para>With the plugin enabled, you can see OpenDJ referential integrity
+ resolving group membership automatically.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"
+dn: cn=My Static Group,ou=Groups,dc=example,dc=com
+ou: Groups
+objectClass: groupOfNames
+objectClass: top
+member: uid=ahunter,ou=People,dc=example,dc=com
+member: uid=bjensen,ou=People,dc=example,dc=com
+member: uid=tmorris,ou=People,dc=example,dc=com
+member: uid=scarter,ou=People,dc=example,dc=com
+cn: My Static Group
+
+$ ldapdelete
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ uid=scarter,ou=People,dc=example,dc=com
+Processing DELETE request for uid=scarter,ou=People,dc=example,dc=com
+DELETE operation successful for DN uid=scarter,ou=People,dc=example,dc=com
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"
+dn: cn=My Static Group,ou=Groups,dc=example,dc=com
+ou: Groups
+objectClass: groupOfNames
+objectClass: top
+cn: My Static Group
+member: uid=ahunter,ou=People,dc=example,dc=com
+member: uid=bjensen,ou=People,dc=example,dc=com
+member: uid=tmorris,ou=People,dc=example,dc=com</screen>
+
+ <para>By default the referential integrity plugin is configured to manage
+ <literal>member</literal> and <literal>uniqueMember</literal> attributes.
+ These attributes take values that are DNs, and are indexed for equality by
+ default. Before you add an additional attribute to manage, make sure that
+ it has DN syntax and that it is indexed for equality. OpenDJ requires that
+ the attribute be indexed because an unindexed search for integrity would
+ potentially consume too many of the server's resources. Attribute syntax is
+ explained in the chapter on <link xlink:href="admin-guide#chap-schema"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"><citetitle
+ >Managing Schema</citetitle></link>. For instructions on indexing attributes,
+ see the section on <link xlink:href="admin-guide#configure-indexes"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"><citetitle
+ >Configuring & Rebuilding Indexes</citetitle></link>.</para>
+
+ <para>You can also configure the referential integrity plugin to check that
+ new entries added to groups actually exist in the directory by setting the
+ <literal>check-references</literal> property to <literal>true</literal>. You
+ can specify additional criteria once you have activated the check. To ensure
+ that entries added must match a filter, set the
+ <literal>check-references-filter-criteria</literal> to identify the attribute
+ and the filter. For example, you can specify that group members must be person
+ entries by setting <literal>check-references-filter-criteria</literal> to
+ <literal>member:(objectclass=person)</literal>. To ensure that entries must be
+ located in the same naming context, set
+ <literal>check-references-scope-criteria</literal> to
+ <literal>naming-context</literal>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-import-export.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-import-export.xml
new file mode 100644
index 0000000..f28d409
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-import-export.xml
@@ -0,0 +1,412 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-import-export'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Importing & Exporting LDIF Data</title>
+ <indexterm><primary>Provisioning</primary></indexterm>
+ <indexterm><primary>Importing data</primary></indexterm>
+ <indexterm>
+ <primary>Restoring</primary>
+ <secondary>From LDIF</secondary>
+ </indexterm>
+ <indexterm><primary>Exporting data</primary></indexterm>
+ <indexterm><primary>Backup</primary></indexterm>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Import</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Export</secondary>
+ </indexterm>
+
+ <para>LDAP Data Interchange Format provides a mechanism for representing
+ directory data in text format. LDIF data is typically used to initialize
+ directory databases, but also may be used to move data between different
+ directories that cannot replicate directly, or even as an alternative
+ backup format.</para>
+
+ <para>This chapter shows you how to import and export LDIF.
+ This chapter also covers creating test data in LDIF format, and manipulating
+ LDIF data with command-line tools.</para>
+
+ <section xml:id="generating-ldif">
+ <title>Generating Test Data</title>
+ <para>When you install OpenDJ, you have the option of importing sample
+ data generated during the installation. This procedure demonstrates how to
+ generate LDIF using the <command>make-ldif</command> command.</para>
+
+ <procedure xml:id="generate-ldif">
+ <title>To Generate Test LDIF Data</title>
+ <indexterm>
+ <primary>Importing data</primary>
+ <secondary>Test data</secondary>
+ </indexterm>
+
+ <para>The <command>make-ldif</command> command uses templates to provide
+ sample data. Default templates are located in the
+ <filename>OpenDJ/config/MakeLDIF/</filename> directory. The
+ <filename>example.template</filename> file can be used to create
+ a suffix with entries of the type <literal>inetOrgPerson</literal>. You can
+ do the equivalent in OpenDJ Control Panel (Directory Data > New Base
+ DN... > Import Automatically Generated Example Data).</para>
+
+ <step>
+ <para>Write a file to act as the template for your generated LDIF.</para>
+ <para>The resulting test data template depends on what data you expect to
+ encounter in production. Base your work on your knowledge of the production
+ data, and on the sample template,
+ <filename>OpenDJ/config/MakeLDIF/example.template</filename>, and
+ associated data.</para>
+
+ <para>See <link xlink:href="admin-guide#make-ldif-template-5"
+ xlink:role="http://docbook.org/xlink/role/olink" xlink:show="new"><citetitle
+ >make-ldif.template</citetitle></link> for reference information about
+ template files.</para>
+ </step>
+ <step>
+ <para>Create additional data files for the content in your template to be
+ selected randomly from a file, rather than generated by an expression.</para>
+ <para>Additional data files are located in the same directory as your
+ template file.</para>
+ </step>
+ <step>
+ <para>Decide whether you want to generate the same test data each time
+ you run the <command>make-ldif</command> command with your template.</para>
+ <para>If so, provide the same <literal>randomSeed</literal> integer each
+ time you run the command.</para>
+ </step>
+ <step>
+ <para>Before generating a very large LDIF file, make sure you have enough
+ space on disk.</para>
+ </step>
+ <step>
+ <para>Run the <command>make-ldif</command> command to generate your
+ LDIF file.</para>
+ <screen>$ make-ldif
+ --randomSeed 0
+ --templateFile /path/to/my.template
+ --ldifFile /path/to/generated.ldif
+Processed 1000 entries
+Processed 2000 entries
+...
+Processed 10000 entries
+LDIF processing complete. 10003 entries written</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="importing-exporting-ldif">
+ <title>Importing & Exporting Data</title>
+
+ <para>You can use the OpenDJ Control Panel to import data (Directory
+ Data > Import LDIF...) and to export data (Directory Data > Export
+ LDIF...). The following procedures demonstrate how to use the
+ <command>import-ldif</command> and <command>export-ldif</command>
+ commands.</para>
+
+ <procedure xml:id="import-ldif">
+ <title>To Import LDIF Data</title>
+
+ <para>The most efficient method of importing LDIF data is to take the
+ OpenDJ server offline. Alternatively, you can schedule a task to import
+ the data while the server is online.</para>
+
+ <step performance="optional">
+ <para>If you do not want to use the default <literal>userRoot</literal>
+ backend, create a new JE backend for your data.</para>
+ <para>See <xref linkend="create-database-backend" /> for details.</para>
+ </step>
+ <step>
+ <para>The following example imports <literal>dc=example,dc=org</literal>
+ data into the <literal>userRoot</literal> backend, overwriting existing
+ data.</para>
+ <stepalternatives>
+ <step>
+ <para>If you want to speed up the process—for example because you
+ have millions of directory entries to import—first shut down the
+ server, and then run the <command>import-ldif</command> command.</para>
+ <screen>$ stop-ds
+$ import-ldif
+ --includeBranch dc=example,dc=org
+ --backendID userRoot
+ --ldifFile /path/to/generated.ldif</screen>
+ </step>
+ <step>
+ <para>If not, schedule a task to import the data while online.</para>
+ <screen>$ import-ldif
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --includeBranch dc=example,dc=org
+ --backendID userRoot
+ --ldifFile /path/to/generated.ldif
+ --trustAll</screen>
+ <para>Notice that the task is scheduled through communication over SSL on
+ the administration port, by default <literal>4444</literal>. You can
+ schedule the import task to start at a particular time using the
+ <option>--start</option> option.</para>
+ <para>The <option>--trustAll</option> option trusts all SSL certificates,
+ such as a default self-signed certificate used for testing.</para>
+ </step>
+ </stepalternatives>
+ </step>
+ </procedure>
+
+ <procedure xml:id="export-ldif">
+ <title>To Export LDIF Data</title>
+
+ <step>
+ <para>The following example exports <literal>dc=example,dc=org</literal>
+ data from the <literal>userRoot</literal> backend.</para>
+ <stepalternatives>
+ <step>
+ <para>If you want to speed up export, first shut down the server, and then
+ export data using the <command>export-ldif</command> command.</para>
+ <screen>$ stop-ds
+$ export-ldif
+ --includeBranch dc=example,dc=org
+ --backendID userRoot
+ --ldifFile /path/to/backup.ldif</screen>
+ </step>
+ <step>
+ <para>If not, schedule a task to export the data while online.</para>
+ <screen>$ export-ldif
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --includeBranch dc=example,dc=org
+ --backendID userRoot
+ --ldifFile /path/to/backup.ldif
+ --start 20111221230000
+ --trustAll</screen>
+ <para>The <option>--start 20111221230000</option> option tells OpenDJ to
+ start the export at 11 PM on December 21, 2012.</para>
+ <para>If OpenDJ is stopped at this time, then when you start OpenDJ again,
+ the server attempts to perform the task after starting up.</para>
+ </step>
+ </stepalternatives>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="ldif-tools">
+ <title>Other Tools For Working With LDIF Data</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Tools</secondary>
+ </indexterm>
+
+ <para>This section demonstrates the <command>ldifsearch</command>,
+ <command>ldifmodify</command>, and <command>ldif-diff</command> tools.</para>
+
+ <section xml:id="ldifsearch-example">
+ <title>Searching in LDIF With <command>ldifsearch</command></title>
+
+ <para>The <command>ldifsearch</command> command lets you search LDIF files
+ in a similar way to how you search LDAP directories with the
+ <command>ldapsearch</command> command.</para>
+
+ <screen>$ ldifsearch
+ --baseDN dc=example,dc=org
+ --ldifFile generated.ldif
+ "(sn=Grenier)"
+ mobile
+dn: uid=user.4630,ou=People,dc=example,dc=org
+mobile: +1 728 983 6669</screen>
+
+ <para>The <option>--ldifFile <replaceable>ldif-file</replaceable></option>
+ option replaces the <option>--hostname</option> and <option>--port</option>
+ options used to connect to an LDAP directory. Otherwise the command syntax
+ and LDIF output is familiar to <command>ldapsearch</command> users.</para>
+ </section>
+
+ <section xml:id="ldifmodify-example">
+ <title>Updating LDIF With <command>ldifmodify</command></title>
+
+ <para>The <command>ldifmodify</command> command lets you apply changes to
+ LDIF files, generating a new, changed version of the original file.</para>
+
+ <screen>$ cat changes.ldif
+dn: uid=user.0,ou=People,dc=example,dc=org
+changetype: modify
+replace: description
+description: This is the new description for Aaccf Amar.
+-
+replace: initials
+initials: AAA
+
+$ ldifmodify
+ --sourceLDIF generated.ldif
+ --changesLDIF changes.ldif
+ --targetLDIF new.ldif</screen>
+
+ <para>Notice that the resulting new LDIF file is likely to be about the
+ same size as the source LDIF file.</para>
+ </section>
+
+ <section xml:id="ldif-diff-example">
+ <title>Comparing LDIF With <command>ldif-diff</command></title>
+
+ <para>The <command>ldif-diff</command> command reports differences between
+ two LDIF files in LDIF format.</para>
+
+ <screen>$ ldif-diff --sourceLDIF old.ldif --targetLDIF new.ldif
+dn: uid=user.0,ou=People,dc=example,dc=org
+changetype: modify
+add: initials
+initials: AAA
+-
+delete: initials
+initials: ASA
+-
+add: description
+description: This is the new description for Aaccf Amar.
+-
+delete: description
+description: This is the description for Aaccf Amar.
+
+</screen>
+
+ <para>As the <command>ldif-diff</command> command reads both files into
+ memory, constructing tree maps to perform the comparison, the command
+ is designed to work with small files and fragments. The command can quickly
+ run out of memory when calculating differences between large files.</para>
+ </section>
+ </section>
+
+ <section xml:id="create-database-backend">
+ <title>Creating a New Database Backend</title>
+ <indexterm>
+ <primary>Database backend</primary>
+ <secondary>Creating</secondary>
+ </indexterm>
+
+ <para>OpenDJ stores your data in a <firstterm>backend</firstterm>. OpenDJ
+ stores directory data in backends. Backends are what you backup and restore.
+ By default, OpenDJ stores your data in a backend named
+ <literal>userRoot</literal>. You can create new backends using the
+ <command>dsconfig</command> command. The following example creates a
+ local backend named <literal>testData</literal>.</para>
+ <screen>$ dsconfig create-backend --backend-name testData --type local-db
+
+
+>>>> Configuring the "base-dn" property
+
+ Specifies the base DN(s) for the data that the backend handles.
+
+ A single backend may be responsible for one or more base DNs. Note that no
+ two backends may have the same base DN although one backend may have a
+ base DN that is below a base DN provided by another backend (similar to
+ the use of sub-suffixes in the Sun Java System Directory Server). If any
+ of the base DNs is subordinate to a base DN for another backend, then all
+ base DNs for that backend must be subordinate to that same base DN.
+
+ Syntax: DN
+
+Enter a value for the "base-dn" property: dc=example,dc=org
+
+Enter another value for the "base-dn" property [continue]:
+
+
+>>>> Configuring the "enabled" property
+
+ Indicates whether the backend is enabled in the server.
+
+ If a backend is not enabled, then its contents are not accessible when
+ processing operations.
+
+Select a value for the "enabled" property:
+
+ 1) true
+ 2) false
+
+ ?) help
+ q) quit
+
+Enter choice: 1
+
+
+>>>> Configure the properties of the Local DB Backend
+
+ Property Value(s)
+ --------------------------------------
+ 1) backend-id testData
+ 2) base-dn "dc=example,dc=org"
+ 3) compact-encoding true
+ 4) db-cache-percent 10
+ 5) db-cache-size 0 b
+ 6) db-directory db
+ 7) enabled true
+ 8) index-entry-limit 4000
+ 9) writability-mode enabled
+
+ ?) help
+ f) finish - create the new Local DB Backend
+ q) quit
+
+Enter choice [f]:
+
+The Local DB Backend was created successfully</screen>
+ <para>Alternatively, you can create a new backend in OpenDJ Control Panel
+ (Directory Data > New Base DN... > Backend > New Backend:
+ <replaceable>backend-name</replaceable>).</para>
+ </section>
+
+ <section xml:id="delete-database-backend">
+ <title>Deleting a Database Backend</title>
+ <indexterm>
+ <primary>Database backend</primary>
+ <secondary>Deleting</secondary>
+ </indexterm>
+
+ <para>You delete a database backend by using the <command>dsconfig
+ delete-backend</command> command.</para>
+
+ <para>When you delete a database backend by using the <command>dsconfig
+ delete-backend</command> command, OpenDJ does not actually remove the
+ database files for two reasons. First, a mistake could potentially cause
+ lots of data to be lost. Second, deleting a large database backend could
+ cause severe service degradation due to a sudden increase in I/O load.</para>
+
+ <para>Instead, after you run the <command>dsconfig delete-backend</command>
+ command you must also manually remove the database backend files.</para>
+
+ <para>If you do run the <command>dsconfig delete-backend</command> command by
+ mistake and have not yet deleted the actual files, then you can recover from
+ the mistake by creating the backend again, reconfiguring the indexes that
+ were removed, and rebuilding the indexes as described in the section on <link
+ xlink:href="admin-guide#configure-indexes"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring &
+ Rebuilding Indexes</citetitle></link>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-indexing.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-indexing.xml
new file mode 100644
index 0000000..005f871
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-indexing.xml
@@ -0,0 +1,800 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-indexing'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Indexing Attribute Values</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ </indexterm>
+
+ <para>OpenDJ provides several indexing schemes to speed up searches.</para>
+
+ <para>When a client requests a directory search operation, the client sends
+ the server a filter expression such as
+ <literal>(&(uid=*jensen*)(l=Stavanger))</literal>. The server then uses
+ applicable indexes to find entries with attribute values likely to match
+ the search. If no indexes are applicable, then the server potentially has
+ to go through all entries to look for candidate matches.</para>
+
+ <para>Looking through all entries is resource-intensive for large directories.
+ For this reason, the <literal>unindexed-search</literal> privilege, allowing
+ users to request searches for which no applicable index exists, is reserved
+ for the directory root user by default.</para>
+
+ <para>Rather than granting the <literal>unindexed-search</literal> privilege
+ to more users and client applications, you configure indexes to correspond
+ to the searches that clients need to perform.</para>
+
+ <para>This chapter first describes index types, then demonstrates how to
+ index attribute values. This chapter also lists the default indexing
+ configuration for OpenDJ directory server.</para>
+
+ <section xml:id="indexes-overview">
+ <title>Index Types & What Each Does</title>
+
+ <para>OpenDJ provides several different index types, each corresponding
+ to a different type of search.</para>
+
+ <section xml:id="indexes-approximate">
+ <title>Approximate Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Approximate</secondary>
+ </indexterm>
+
+ <para>An approximate index is used to match values that "sound like" those
+ provided in the filter. An approximate index on <literal>cn</literal>
+ allows clients to find people even when they misspell names as in the
+ following example.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn~=Babs Jansen)" cn
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen</screen>
+ </section>
+
+ <section xml:id="indexes-equality">
+ <title>Equality Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Equality</secondary>
+ </indexterm>
+
+ <para>An equality index is used to match values that correspond exactly
+ (though generally without case sensitivity) to the value provided in
+ the search filter. An equality index requires clients to match values
+ without wildcards or misspellings.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)" mail
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com</screen>
+ </section>
+
+ <section xml:id="indexes-ordering">
+ <title>Ordering Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Ordering</secondary>
+ </indexterm>
+
+ <para>An ordering index is used to match values for a filter that
+ specifies a range. The <literal>ds-sync-hist</literal> has an ordering
+ index by default because searches on that attribute often seek entries
+ with changes more recent than the last time a search was performed.</para>
+
+ <para>The following example shows a search that specifies ranges.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com
+ "(&(uidNumber>=1120)(roomNumber>=4500))" uid
+dn: uid=charvey,ou=People,dc=example,dc=com
+uid: charvey
+
+dn: uid=eward,ou=People,dc=example,dc=com
+uid: eward
+
+dn: uid=mvaughan,ou=People,dc=example,dc=com
+uid: mvaughan
+
+dn: uid=pchassin,ou=People,dc=example,dc=com
+uid: pchassin</screen>
+ </section>
+
+ <section xml:id="indexes-presence">
+ <title>Presence Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Presence</secondary>
+ </indexterm>
+
+ <para>A presence index is used to match the fact that an attribute is
+ present on the entry, regardless of the value. The <literal>aci</literal>
+ attribute is indexed for presence by default to allow quick retrieval
+ of entries with ACIs.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(aci=*)" -
+dn: dc=example,dc=com
+
+dn: ou=People,dc=example,dc=com</screen>
+ </section>
+
+ <section xml:id="indexes-substring">
+ <title>Substring Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Substring</secondary>
+ </indexterm>
+
+ <para>A substring index is used to match values specified with wildcards
+ in the filter. Substring indexes can be expensive to maintain, especially
+ for large attribute values.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Barb*)" cn
+dn: uid=bfrancis,ou=People,dc=example,dc=com
+cn: Barbara Francis
+
+dn: uid=bhal2,ou=People,dc=example,dc=com
+cn: Barbara Hall
+
+dn: uid=bjablons,ou=People,dc=example,dc=com
+cn: Barbara Jablonski
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+
+dn: uid=bmaddox,ou=People,dc=example,dc=com
+cn: Barbara Maddox</screen>
+ </section>
+
+ <section xml:id="indexes-vlv">
+ <title>Virtual List View (Browsing) Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Virtual list view (browsing)</secondary>
+ </indexterm>
+
+ <para>A VLV or browsing index are designed to help the server respond to
+ client applications that need virtual list view results, for example to
+ browse through a long list in a GUI. They also help the server respond
+ to clients that request server-side sorting of the search results.</para>
+
+ <para>VLV indexes correspond to particular searches. Configure your
+ VLV indexes using the Control Panel, and copy the command-line
+ equivalent from the Details pane for the operation, if necessary.</para>
+ </section>
+
+ <section xml:id="indexes-extensible">
+ <title>Extensible Matching Rule Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Extensible matching rule</secondary>
+ </indexterm>
+
+ <para>In some cases you need an index for a matching rule other than those
+ described above. For example, OpenDJ supports generalized time based
+ matching so applications can search for all times later than, or earlier
+ than a specified time.</para>
+ </section>
+ </section>
+
+ <section xml:id="configure-indexes">
+ <title>Configuring & Rebuilding Indexes</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Configuring</secondary>
+ </indexterm>
+
+ <para>You modify index configurations using the <command>dsconfig</command>
+ command. The configuration changes then take effect after you rebuild the
+ index according to the new configuration, using the
+ <command>rebuild-index</command>. The <command>dsconfig
+ --help-database</command> command lists subcommands for creating, reading,
+ updating, and deleting index configuration.</para>
+
+ <tip>
+ <para>Indexes are per directory backend rather than per suffix. To maintain
+ separate indexes for different suffixes on the same directory server, put
+ the suffixes in different backends.</para>
+ </tip>
+
+ <section xml:id="configure-standard-index">
+ <title>Configuring a Standard Index</title>
+
+ <para>You can configure standard indexes from the Control Panel, and also
+ on the command line using the <command>dsconfig</command> command. After
+ you finish configuring the index, you must rebuild the index for the changes
+ to take effect.</para>
+
+ <example xml:id="create-index-example">
+ <title>Create a New Index</title>
+
+ <para>The following example creates a new substring index for
+ <literal>description</literal>.</para>
+
+ <screen>$ dsconfig
+ create-local-db-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --index-name description
+ --set index-type:substring
+ --trustAll
+ --no-prompt</screen>
+ </example>
+
+ <example xml:id="approx-index-example">
+ <title>Configure an Approximate Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Approximate</secondary>
+ </indexterm>
+
+ <para>The following example configures an approximate index for
+ <literal>cn</literal> (common name).</para>
+
+ <screen>$ dsconfig
+ set-local-db-index-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --index-name cn
+ --set index-type:approximate
+ --trustAll
+ --no-prompt</screen>
+ </example>
+
+ <example xml:id="extensible-match-index-example">
+ <title>Configure an Extensible Match Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Extensible matching rule</secondary>
+ </indexterm>
+
+ <para>The OpenDJ Control Panel New Index window does not help you set up
+ extensible matching rule indexes. Use the <command>dsconfig</command>
+ command instead.</para>
+
+ <para>The following example configures an extensible matching rule
+ index for "later than" and "earlier than" generalized time matching on
+ a <literal>lastLoginTime</literal> attribute.</para>
+
+ <screen>$ dsconfig
+ create-local-db-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --set index-type:extensible
+ --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.5
+ --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.6
+ --index-name lastLoginTime
+ --trustAll
+ --no-prompt</screen>
+ </example>
+ </section>
+
+ <section xml:id="configure-vlv">
+ <title>Configuring a Virtual List View Index</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Virtual list view (browsing)</secondary>
+ </indexterm>
+
+ <para>In the OpenDJ Control Panel, select Manage Indexes >
+ New VLV Index..., and then set up your VLV index using the New VLV
+ Index window.</para>
+
+ <mediaobject xml:id="figure-create-vlv-index">
+ <imageobject>
+ <imagedata fileref="images/create-vlv-index.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>After you finish configuring your index and click OK, the Control
+ Panel prompts you to make the additional changes necessary to complete the
+ VLV index configuration, and then to build the index.</para>
+
+ <para>You can also create the equivalent index configuration using the
+ <command>dsconfig</command> command.</para>
+
+ <screen>$ dsconfig
+ create-local-db-vlv-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDn "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --index-name people-by-last-name
+ --set base-dn:ou=People,dc=example,dc=com
+ --set filter:"(|(givenName=*)(sn=*))"
+ --set scope:single-level
+ --set sort-order:"+sn +givenName"
+ --trustAll
+ --no-prompt</screen>
+
+ <note>
+ <para>When referring to a virtual list view (VLV) index after creation, you
+ must add <literal>vlv.</literal> as a prefix. In other words, if you named
+ the VLV index <literal>people-by-last-name</literal>, you refer to it as
+ <literal>vlv.people-by-last-name</literal> when rebuilding indexes,
+ changing index properties such as the index entry limit, or verifying
+ indexes.</para>
+ </note>
+ </section>
+
+ <section xml:id="rebuild-index">
+ <title>Rebuilding Indexes</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Rebuilding</secondary>
+ </indexterm>
+
+ <para>After you change an index configuration, or when you find that
+ an index is corrupt, you can rebuild the index. When you rebuild indexes,
+ you specify the base DN of the data to index, and either the list of indexes
+ to rebuild or <option>--rebuildAll</option>. You can rebuild indexes while
+ the server is offline, or while the server is online. If you rebuild the
+ index while the server is online, then you must schedule the rebuild process
+ as a task.</para>
+
+ <example xml:id="rebuild-index-example">
+ <title>Rebuild Index</title>
+
+ <para>The following example rebuilds the <literal>cn</literal> index
+ immediately with the server online.</para>
+
+ <screen>$ rebuild-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ --index cn
+ --start 0
+Rebuild Index task 20110607171639867 scheduled to start Jun 7, 2011 5:16:39 PM</screen>
+ </example>
+
+ <example xml:id="rebuild-degraded-indexes-example">
+ <title>Rebuild Degraded Indexes</title>
+
+ <para>The following example rebuilds degraded indexes immediately with
+ the server online.</para>
+
+ <screen>$ rebuild-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ --rebuildDegraded
+...
+[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=7 msgID=8847510
+ message="Due to changes in the configuration, index
+ dc_example_dc_com_description is currently operating in a degraded state
+ and must be rebuilt before it can be used"
+[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=8 msgID=8847591
+ message="Rebuild of all degraded indexes started with 160 total entries
+ to process"
+...
+[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=10 msgID=8847493
+ message="Rebuild complete. Processed 160 entries in 0 seconds (average
+ rate 1860.5/sec)"
+...
+Rebuild Index task 20120131164324838 has been successfully completed</screen>
+ </example>
+
+ <example xml:id="clear-degraded-indexes-example">
+ <title>Clear New, Unused, "Degraded" Indexes</title>
+
+ <para>When you add a new attribute as described in <link
+ xlink:href="admin-guide#update-schema"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Updating
+ Directory Schema</citetitle></link>, and then create indexes for the new
+ attribute, the new indexes appear as degraded, even though the attribute
+ has not yet been used, and so indexes are sure to be empty, rather than
+ degraded.</para>
+
+ <para>In this special case, you can safely use the
+ <command>rebuild-index</command> command
+ <option>--clearDegradedState</option> option to avoid having to scan
+ the entire directory backend to rebuild the new, unused index. This
+ is shown in the following example, where an index has just been created
+ for <literal>newUnusedAttribute</literal>.</para>
+
+ <screen>$ dbtest
+ list-index-status
+ --backendID userRoot
+ --baseDN dc=example,dc=com
+ | grep newUnusedAttribute
+newUnusedAttribute.equality Index ...newUnusedAttribute.equality false...
+newUnusedAttribute.presence Index ...newUnusedAttribute.presence false...
+newUnusedAttribute.substring Index ...newUnusedAttribute.substring false...
+$ rebuild-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ --clearDegradedState
+ --index newUnusedAttribute
+ --start 0
+Rebuild Index task 20130211175925012 scheduled to start Feb 11, 2013 5:59:25
+ PM CET
+$ dbtest
+ list-index-status
+ --backendID userRoot
+ --baseDN dc=example,dc=com
+ | grep newUnusedAttribute
+newUnusedAttribute.equality Index ...newUnusedAttribute.equality true...
+newUnusedAttribute.presence Index ...newUnusedAttribute.presence true...
+newUnusedAttribute.substring Index ...newUnusedAttribute.substring true...</screen>
+
+ <para>If the newly indexed attribute has already been used, rebuild indexes
+ instead.</para>
+ </example>
+ </section>
+
+ <section xml:id="index-entry-limits">
+ <title>Changing Index Entry Limits</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Entry limits</secondary>
+ </indexterm>
+
+ <para>As the number of entries in your directory grows, it can make sense
+ not to maintain indexes for particular values. For example, every entry
+ in the directory has the value <literal>top</literal> for the
+ <literal>objectClass</literal> attribute, so maintaining a list of entries
+ that match the filter <literal>(objectClass=top)</literal> is not a
+ reasonable use of resources. In a very, very large directory, the same can
+ be true for <literal>(givenName=John)</literal> and
+ <literal>(sn=Smith)</literal>.</para>
+
+ <para>In an index, each index key points to a list of entries that
+ are candidates to match. For the <literal>objectClass</literal> index key
+ that corresponds to <literal>=top</literal>, the list of entries can
+ include every entry in the directory.</para>
+
+ <para>OpenDJ directory server therefore defines an index entry limit. When
+ the number of entries that an index key points to exceeds the index entry
+ limit, OpenDJ stops maintaining the list of entries for that index key.</para>
+
+ <para>The default index entry limit value is 4000. 4000 is usually plenty
+ large for all index keys, except for <literal>objectClass</literal> indexes.
+ If you have clients performing searches with filters such as
+ <literal>(objectClass=person)</literal>, you might suggest that they adjust
+ the search to be more specific, such as
+ <literal>(&(mail=username@maildomain.net)(objectClass=person))</literal>,
+ so that the server can use an index, in this case equality for mail, to
+ limit the number of candidate entries to check for matches.</para>
+
+ <para>You can change the index entry limit on a per index basis.</para>
+
+ <example xml:id="change-index-entry-limit">
+ <title>Change Index Entry Limit</title>
+
+ <para>The following example changes the index entry limit for the
+ <literal>objectClass</literal> index, and then rebuilds the index for the
+ configuration change to take effect.</para>
+
+ <screen>$ dsconfig
+ set-local-db-index-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --index-name objectClass
+ --set index-entry-limit:5000
+ --trustAll
+ --no-prompt
+$ rebuild-index
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ --index objectclass
+ --start 0
+Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</screen>
+ </example>
+
+ <para>Alternatively, you can configure the index entry limit for all
+ indexes stored in a backend by using the <command>dsconfig
+ set-backend-prop</command> command with the <option>--backend-name
+ <replaceable>backendName</replaceable> --set
+ index-entry-limit:<replaceable>limitValue</replaceable></option>
+ options.</para>
+ </section>
+ </section>
+
+ <section xml:id="verify-index">
+ <title>Verifying Indexes</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Verifying</secondary>
+ </indexterm>
+
+ <para>You can verify that indexes correspond to current directory data,
+ and that indexes do not contain errors using the
+ <command>verify-index</command> command.</para>
+
+ <example xml:id="verify-index-example">
+ <title>Verify Index</title>
+
+ <para>The following example verifies the <literal>cn</literal> (common
+ name) index for completeness and for errors.</para>
+
+ <screen>$ verify-index
+ --baseDN dc=example,dc=com
+ --index cn
+ --clean
+ --countErrors
+[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
+ msgID=9437595 msg=Local DB backend userRoot does not specify the number of
+ lock tables: defaulting to 97
+[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
+ msgID=9437594 msg=Local DB backend userRoot does not specify the number of
+ cleaner threads: defaulting to 24 threads
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=NOTICE msgID=8847461
+ msg=Checked 1316 records and found 0 error(s) in 0 seconds
+ (average rate 2506.7/sec)
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388710 msg=Number of records referencing more than one entry: 315
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388711 msg=Number of records that exceed the entry limit: 0
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388712 msg=Average number of entries referenced is 1.58/record
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388713 msg=Maximum number of entries referenced by any
+ record is 32</screen>
+
+ <para>Ignore the messages regarding lock tables and cleaner threads. The
+ important information is whether any errors are found in the indexes.</para>
+ </example>
+ </section>
+
+ <section xml:id="debug-search-indexes">
+ <title>Checking Indexes For a Search</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Debugging searches</secondary>
+ </indexterm>
+
+ <para>When searching, you can improve performance by making sure your search
+ is indexed as you expect. One way of checking is to request the
+ <literal>debugsearchindex</literal> attribute in your results.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(uid=bjensen)"
+ debugsearchindex
+dn: cn=debugsearch
+debugsearchindex: filter=(uid=bjensen)[INDEX:uid.equality][COUNT:1]
+ final=[COUNT:1]</screen>
+
+ <para>When you request the <literal>debugsearchindex</literal> attribute,
+ instead of performing the search, OpenDJ returns debug information indicating
+ how it would process the search operation. In the example above you notice
+ OpenDJ hits the equality index for <literal>uid</literal> right away.</para>
+
+ <para>A less exact search requires more work from OpenDJ. In the following
+ example OpenDJ would have to return 160 entries.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(uid=*)"
+ debugsearchindex
+dn: cn=debugsearch
+debugsearchindex: filter=(uid=*)[NOT-INDEXED] scope=wholeSubtree[COUNT:160]
+ final=[COUNT:160]</screen>
+
+ <para>By default OpenDJ rejects unindexed searches when the number of
+ candidate entries goes beyond the search or look-though limit.</para>
+ </section>
+
+ <section xml:id="default-indexes">
+ <title>Default Indexes</title>
+ <indexterm>
+ <primary>Indexes</primary>
+ <secondary>Default settings</secondary>
+ </indexterm>
+
+ <para>When you first install OpenDJ directory server and import your
+ data from LDIF, the following indexes are configured.</para>
+
+ <table pgwide="1" rules="none">
+ <title>Default Indexes</title>
+ <tgroup cols="7">
+ <colspec colnum="2" colname="c2" />
+ <colspec colnum="7" colname="c7" />
+ <thead>
+ <row>
+ <entry>Index</entry>
+ <entry>Approx.</entry>
+ <entry>Equality</entry>
+ <entry>Ordering</entry>
+ <entry>Presence</entry>
+ <entry>Substring</entry>
+ <entry>Entry Limit</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>aci</literal></entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>cn</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>dn2id</literal></entry>
+ <entry namest="c2" nameend="c7" align="center">Non-configurable
+ internal index</entry>
+ </row>
+ <row>
+ <entry><literal>ds-sync-conflict</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>ds-sync-hist</literal></entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>entryUUID</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>givenName</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>id2children</literal></entry>
+ <entry namest="c2" nameend="c7" align="center">Non-configurable
+ internal index</entry>
+ </row>
+ <row>
+ <entry><literal>id2subtree</literal></entry>
+ <entry namest="c2" nameend="c7" align="center">Non-configurable
+ internal index</entry>
+ </row>
+ <row>
+ <entry><literal>mail</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>member</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>objectClass</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>sn</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>telephone­Number</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>uid</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ <row>
+ <entry><literal>unique­Member</literal></entry>
+ <entry>-</entry>
+ <entry>Yes</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>-</entry>
+ <entry>4000</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>When you create a JE backend using the <command>dsconfig</command>
+ command, OpenDJ creates the <literal>aci</literal> presence,
+ <literal>ds-sync-conflict</literal> equality,
+ <literal>ds-sync-hist</literal> ordering,
+ <literal>entryUUID</literal> equality, and
+ <literal>objectClass</literal> equality indexes automatically.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-ldap-operations.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-ldap-operations.xml
new file mode 100644
index 0000000..a9ce3a1
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-ldap-operations.xml
@@ -0,0 +1,1906 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-ldap-operations'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Performing LDAP Operations</title>
+
+ <para>OpenDJ comes with a Control Panel browser for managing entries and also
+ command-line tools for performing LDAP operations. This chapter demonstrates
+ how to use the command line tools to script LDAP operations.</para>
+
+ <section xml:id="search-ldap">
+ <title>Searching the Directory</title>
+ <indexterm><primary>Searching data</primary></indexterm>
+
+ <para>Searching the directory resembles searching for a phone number in
+ a paper phone book. You can look up a phone number because you know the
+ last name of a subscriber's entry. In other words, you use the value of
+ one attribute of the entry to find entries that have another attribute
+ you want.</para>
+
+ <para>Yet whereas a paper phone book has only one index (alphabetical order
+ by name), the directory has many indexes. For a search you therefore always
+ specify which index to use, by specifying which attribute(s) you are using
+ to lookup entries.</para>
+
+ <para>Your paper phone book might be divided into white pages for residential
+ subscribers, and yellow pages for businesses. If you are looking up an
+ individual's phone number, you limit your search to the white pages.
+ Directory services divide entries in various ways, often to separate
+ organizations, and to separate groups from user entries from printers for
+ example, but potentially in other ways. When searching you therefore also
+ specify where in the directory to search.</para>
+
+ <para>The <command>ldapsearch</command> command thus takes at minimum a
+ search base DN option and an LDAP filter. The search base DN identifies
+ where in the directory to search for entries that match the filter.
+ For example, if you are looking for printers, you might specify the base
+ DN as <literal>ou=Printers,dc=example,dc=com</literal>. Perhaps you are
+ visiting the <literal>GNB00</literal> office and are looking for a
+ printer.</para>
+
+ <screen>$ ldapsearch --baseDN ou=Printers,dc=example,dc=com "(printerLocation=GNB00)"</screen>
+
+ <para>In the example, the LDAP filter indicates to the directory that you
+ want to lookup printer entries where the <literal>printerLocation</literal>
+ attribute is equal to <literal>GNB00</literal>.</para>
+
+ <para>You also specify the host and port to access directory services,
+ what protocol to use (for example, LDAP/SSL, or StartTLS to protect
+ communication). If the directory service does not allow anonymous access
+ to the data you want to search, you also identify who is performing the
+ search and provide their credentials, such as a password or
+ certificate. Finally, you can specify a list of attributes to return.
+ If you do not specify attributes, then the search returns all user attributes
+ for the entry.</para>
+
+ <itemizedlist>
+ <para>Review the following examples in this section to get a sense of how
+ searches work.</para>
+ <listitem><para><xref linkend="simple-filter-search"/></para></listitem>
+ <listitem><para><xref linkend="complex-filter-search"/></para></listitem>
+ <listitem><para><xref linkend="operational-attrs-search"/></para></listitem>
+ <listitem><para><xref linkend="attr-desc-list-search"/></para></listitem>
+ <listitem><para><xref linkend="escape-characters-in-filter"/></para></listitem>
+ <listitem><para><xref linkend="extensible-match-search"/></para></listitem>
+ <listitem><para><xref linkend="localized-search"/></para></listitem>
+ </itemizedlist>
+
+ <example xml:id="simple-filter-search">
+ <title>Search: Simple Filter</title>
+
+ <para>The following example searches for entries with user IDs
+ (<literal>uid</literal>) containing <literal>jensen</literal>, returning
+ only DNs and user ID values.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*jensen*)" uid
+dn: uid=ajensen,ou=People,dc=example,dc=com
+uid: ajensen
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+uid: bjensen
+
+dn: uid=gjensen,ou=People,dc=example,dc=com
+uid: gjensen
+
+dn: uid=jjensen,ou=People,dc=example,dc=com
+uid: jjensen
+
+dn: uid=kjensen,ou=People,dc=example,dc=com
+uid: kjensen
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+uid: rjensen
+
+dn: uid=tjensen,ou=People,dc=example,dc=com
+uid: tjensen
+
+
+Result Code: 0 (Success)</screen>
+ </example>
+
+ <example xml:id="complex-filter-search">
+ <title>Search: Complex Filter</title>
+
+ <para>The following example returns entries with <literal>uid</literal>
+ containing <literal>jensen</literal> for users located in Santa Clara. The
+ command returns the attributes associated with the <literal>person</literal>
+ object class.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN ou=people,dc=example,dc=com
+ "(&(uid=*jensen*)(l=Santa Clara))"
+ @person
+dn: uid=ajensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+cn: Allison Jensen
+telephoneNumber: +1 408 555 7892
+sn: Jensen
+
+dn: uid=gjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+cn: Gern Jensen
+telephoneNumber: +1 408 555 3299
+sn: Jensen
+
+dn: uid=kjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+cn: Kurt Jensen
+telephoneNumber: +1 408 555 6127
+sn: Jensen
+
+dn: uid=tjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+cn: Ted Jensen
+telephoneNumber: +1 408 555 8622
+sn: Jensen
+
+</screen>
+
+ <para>Complex filters can use both "and" syntax,
+ <literal>(&(<replaceable>filtercomp</replaceable>)(<replaceable>filtercomp</replaceable>))</literal>,
+ and "or" syntax,
+ <literal>(|(<replaceable>filtercomp</replaceable>)(<replaceable>filtercomp</replaceable>))</literal>.</para>
+ </example>
+
+ <example xml:id="operational-attrs-search">
+ <title>Search: Return Operational Attributes</title>
+
+ <para>Use <literal>+</literal> in the attribute list after the filter
+ to return all operational attributes. Alternatively, specify operational
+ attributes by name.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen +
+dn: uid=bjensen,ou=People,dc=example,dc=com
+numSubordinates: 0
+structuralObjectClass: inetOrgPerson
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: uid=bjensen,ou=people,dc=example,dc=com
+entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c</screen>
+ </example>
+
+ <example xml:id="attr-desc-list-search">
+ <title>Search: Return Attributes for an Object Class</title>
+
+ <para>Use <literal>@<replaceable>objectClass</replaceable></literal> in the
+ attribute list after the filter to return the attributes associated with
+ a particular object class.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen @person
+dn: uid=bjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+cn: Barbara Jensen
+cn: Babs Jensen
+telephoneNumber: +1 408 555 1862
+sn: Jensen</screen>
+ </example>
+
+ <example xml:id="escape-characters-in-filter">
+ <title>Search: Escaping Search Filter Characters</title>
+
+ <para><link xlink:href='http://tools.ietf.org/html/rfc4515'>RFC 4515:
+ Lightweight Directory Access Protocol (LDAP): String Representation
+ of Search Filters</link> mentions a number of characters that you must
+ handle with care when using them in search filters.</para>
+
+ <itemizedlist>
+ <para>For a filter like <literal>(attr=<replaceable
+ >value</replaceable>)</literal>, the following list indicates characters
+ that you must replace with a backslash ( <literal>\</literal> ) followed
+ by two hexadecimal digits when using them as part of the
+ <replaceable>value</replaceable> string.</para>
+ <listitem>
+ <para>Replace <literal>*</literal> with <literal>\2a</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal>(</literal> with <literal>\28</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal>)</literal> with <literal>\29</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal>\</literal> with <literal>\5c</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace NUL (0x00) with <literal>\00</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following example shows a filter with escaped characters matching
+ an actual value.</para>
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com
+ "(description=\28*\5c*\2a\29)" description
+dn: uid=bjensen,ou=People,dc=example,dc=com
+description: (A \great\ description*)</screen>
+ </example>
+
+ <example xml:id="extensible-match-search"><?dbfo keep-together="auto"?>
+ <title>Search: List Active Accounts</title>
+
+ <para>OpenDJ supports extensible matching rules, meaning you can pass in
+ filters specifying a matching rule OID that extends your search beyond what
+ you can do with standard LDAP. One specific matching rule of this type that
+ OpenDJ supports is the generalized time based "later than" and "earlier
+ than" matching rules. See the example, <link
+ xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#extensible-match-index-example"><citetitle>Configure
+ an Extensible Match Index</citetitle></link>, showing how to build an index
+ for these matching rules.</para>
+
+ <para>You can use these matching rules to list, for example, all users who
+ have authenticated recently.</para>
+
+ <para>First set up an attribute to store a last login timestamp.
+ You can do this by adding a schema file for the attribute.</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: cn=schema
+changetype: modify
+add: attributeTypes
+attributeTypes: ( lastLoginTime-oid
+ NAME 'lastLoginTime'
+ DESC 'Last time the user logged in'
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation
+ X-ORIGIN 'OpenDJ example documentation' )
+
+Processing MODIFY request for cn=schema
+MODIFY operation successful for DN cn=schema
+
+</screen>
+
+ <para>Configure the applicable password policy to write the last login
+ timestamp when a user authenticates. The following command configures the
+ default password policy to write the timestamp in generalized time format
+ to the <literal>lastLoginTime</literal> operational attribute on the user's
+ entry.</para>
+
+ <screen>$ dsconfig
+ set-password-policy-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set last-login-time-attribute:lastLoginTime
+ --set last-login-time-format:"yyyyMMddHH'Z'"
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Wait a while for users to authenticate again (or test it yourself) so
+ that OpenDJ writes the timestamps. The following search then returns users
+ who have authenticated in the last three months (13 weeks) after you
+ configured OpenDJ to keep the last login timestamps.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(lastLoginTime:1.3.6.1.4.1.26027.1.4.6:=13w)" mail
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com
+
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+mail: kvaughan@example.com</screen>
+ </example>
+
+ <example xml:id="localized-search"><?dbfo keep-together="auto"?>
+ <title>Search: Language Subtype</title>
+
+ <para>OpenDJ directory server supports many language subtypes. See the
+ chapter on <link xlink:href="admin-guide#appendix-l10n"
+ xlink:role="http://docbook.org/xlink/role/olink"
+ ><citetitle>Localization</citetitle></link> for a list.</para>
+
+ <para>When you perform a search you can request the language subtype by
+ OID or by language subtype string. For example, the following search gets
+ the French version of a common name. The example uses the
+ <command>base64</command> command provided with OpenDJ directory server to
+ decode the attribute value.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ "(givenName:fr:=Fréderique)" cn\;lang-fr
+dn: uid=fdupont,ou=People,dc=example,dc=com
+cn;lang-fr:: RnJlZMOpcmlxdWUgRHVwb250
+
+$ base64 decode -d RnJlZMOpcmlxdWUgRHVwb250
+Fredérique Dupont</screen>
+
+ <itemizedlist>
+ <para>At the end of the OID or language subtype, you further specify the
+ matching rule as follows:</para>
+ <listitem>
+ <para>Add <literal>.1</literal> for less than</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.2</literal> for less than or equal to</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.3</literal> for equal to (default)</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.4</literal> for greater than or equal to</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.5</literal> for greater than</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.6</literal> for substring</para>
+ </listitem>
+ </itemizedlist>
+ </example>
+
+ <para>The following table describes the operators you can use in LDAP search
+ filters.</para>
+ <xinclude:include href="../shared/table-filter-operators.xml" />
+ </section>
+
+ <section xml:id="compare-ldap">
+ <title>Comparing Attribute Values</title>
+ <indexterm><primary>Comparing attribute values</primary></indexterm>
+
+ <para>The compare operation checks whether an attribute value you specify
+ matches the attribute value stored on one or more directory entries.</para>
+
+ <example xml:id="compare-example">
+ <title>Compare: Checking <literal>authPassword</literal></title>
+
+ <para>In this example, Kirsten Vaughan checks whether the hashed password
+ value matches the stored value on <literal>authPassword</literal>.</para>
+
+ <screen>$ <userinput>ldapcompare
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ 'authPassword:MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q=='
+ uid=kvaughan,ou=people,dc=example,dc=com</userinput>
+Comparing type authPassword with value
+ MD5$dFHgpDxXUT8=$qlC4xMXvmVlusJLz9/WJ5Q== in entry
+ uid=kvaughan,ou=people,dc=example,dc=com
+Compare operation returned true for entry
+ uid=kvaughan,ou=people,dc=example,dc=com</screen>
+ </example>
+ </section>
+
+ <section xml:id="write-ldap">
+ <title>Updating the Directory</title>
+ <indexterm><primary>Updating data</primary></indexterm>
+ <indexterm><primary>LDIF</primary><secondary>Examples</secondary></indexterm>
+ <para>Authorized users can change directory data using the LDAP add, modify,
+ modify DN, and delete operations.</para>
+
+ <section xml:id="add-ldap">
+ <title>Adding Entries</title>
+
+ <para>With the <command>ldapmodify -a</command> command, authorized users
+ can add entire entries from the same sort of LDIF file used to import
+ and export data.</para>
+
+ <example xml:id="add-two-users">
+ <title>Add: Two New Users</title>
+
+ <screen>$ cat new-users.ldif
+dn: cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
+objectClass: person
+objectClass: top
+cn: Arsene Lupin
+telephoneNumber: +33 1 23 45 67 89
+sn: Lupin
+
+dn: cn=Horace Velmont,ou=Special Users,dc=example,dc=com
+objectClass: person
+objectClass: top
+cn: Horace Velmont
+telephoneNumber: +33 1 12 23 34 45
+sn: Velmont
+
+$ ldapmodify
+ --defaultAdd
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --filename new-users.ldif
+Processing ADD request for cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
+ADD operation successful for DN
+ cn=Arsene Lupin,ou=Special Users,dc=example,dc=com
+Processing ADD request for cn=Horace Velmont,ou=Special Users,dc=example,dc=com
+ADD operation successful for DN
+ cn=Horace Velmont,ou=Special Users,dc=example,dc=com</screen>
+ </example>
+ </section>
+
+ <section xml:id="modify-ldap">
+ <title>Modifying Entry Attributes</title>
+
+ <para>With the <command>ldapmodify</command> command, authorized users
+ can change the values of attributes in the directory using LDIF as specified
+ in <link xlink:href='http://tools.ietf.org/html/rfc2849'>RFC 2849</link>.</para>
+
+ <example xml:id="modify-add-attribute">
+ <title>Modify: Adding Attributes</title>
+
+ <para>The following example adds a description and JPEG photo to Sam
+ Carter's entry.</para>
+
+ <screen>$ cat scarter-mods.ldif
+dn: uid=scarter,ou=people,dc=example,dc=com
+changetype: modify
+add: description
+description: Accounting Manager
+-
+add: jpegphoto
+jpegphoto:<file:///tmp/Samantha-Carter.jpg
+
+$ ldapmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --filename scarter-mods.ldif
+Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
+MODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</screen>
+ </example>
+
+ <example xml:id="modify-replace-attribute">
+ <title>Modify: Changing an Attribute Value</title>
+
+ <para>The following example replaces the description on Sam Carter's
+ entry.</para>
+
+ <screen>$ cat scarter-newdesc.ldif
+dn: uid=scarter,ou=people,dc=example,dc=com
+changetype: modify
+replace: description
+description: Accounting Director
+
+$ ldapmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --filename scarter-newdesc.ldif
+Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
+MODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</screen>
+ </example>
+
+ <example xml:id="modify-delete-attribute">
+ <title>Modify: Deleting an Attribute Value</title>
+
+ <para>The following example deletes the JPEG photo on Sam Carter's
+ entry.</para>
+
+ <screen>$ cat /path/to/scarter-deljpeg.ldif
+dn: uid=scarter,ou=people,dc=example,dc=com
+changetype: modify
+delete: jpegphoto
+
+$ ldapmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --filename scarter-deljpeg.ldif
+Processing MODIFY request for uid=scarter,ou=people,dc=example,dc=com
+MODIFY operation successful for DN uid=scarter,ou=people,dc=example,dc=com</screen>
+ </example>
+
+ <example xml:id="modify-optimistic-concurrency"><?dbfo keep-together="auto"?>
+ <title>Modify: Optimistic Concurrency</title>
+
+ <para>Imagine you are writing an application that lets end users update
+ user profiles through a browser. You store user profiles as OpenDJ entries.
+ Your end users can look up user profiles and modify them. Your application
+ assumes that the end users can tell the right information when they see it,
+ and so aims to update profiles exactly as users see them on their
+ screens.</para>
+
+ <para>Consider two users, Alice and Bob, both busy and often interrupted.
+ Alice has Babs Jensen's new phone and room numbers. Bob has Babs's new
+ location and description. Both assume that they have all the information
+ that has changed. What can you do to make sure that your application
+ applies the right changes when Alice and Bob simulaneously update Babs
+ Jensen's profile?</para>
+
+ <para>OpenDJ offers a couple of features to help you in this situation.
+ One of the features is the <link
+ xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#assertion-request-control">LDAP Assertion
+ Control</link>, used to tell OpenDJ to perform the modify only if
+ an assertion you make stays true. The other feature is OpenDJ's support
+ for <link xlink:href="http://tools.ietf.org/html/rfc2616#section-3.11"
+ xlink:show="new">entity tag</link> (ETag) attributes, making it easy to
+ check whether the entry in the directory is the same as the entry you
+ read.</para>
+
+ <para>Alice and Bob both get Babs's entry. In LDIF the relevant
+ attributes from the entry look like this. Notice the ETag.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+telephoneNumber: +1 408 555 1862
+roomNumber: 0209
+l: Cupertino
+ETag: 000000007a1999df</programlisting>
+
+ <para>Bob prepares his changes in your application. Bob is almost ready
+ to submit the new location and description when Carol stops by to ask Bob
+ a few questions.</para>
+
+ <para>Alice starts just after Bob, but manages to submit her changes
+ without getting interrupted. Now Babs's entry looks like this.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description: Updated by Alice
+telephoneNumber: +47 2108 1746
+roomNumber: 1389
+l: Cupertino
+ETag: 00000000aec2c1e9</programlisting>
+
+ <para>In your application, you use the ETag attribute value with the
+ assertion control to prevent Bob's update from going through when the
+ ETag value has changed. Your application tries the equivalent of the
+ following commands with Bob's updates.</para>
+
+ <screen>$ cat /path/to/bobs.ldif
+dn: uid=bjensen,ou=People,dc=example,dc=com
+changetype: modify
+replace: l
+l: Grenoble
+-
+add: description
+description: Employee of the Month
+
+$ ldapmodify
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --port 1389
+ --filename /path/to/bobs.ldif
+ --assertionFilter "(ETag=000000007a1999df)"
+Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
+MODIFY operation failed
+Result Code: 122 (Assertion Failed)
+Additional Information: Entry uid=bjensen,ou=People,dc=example,dc=com
+ cannot be modified because the request contained an LDAP assertion control
+ and the associated filter did not match the contents of the that entry</screen>
+
+ <para>Your application therefore reloads Babs's entry, also getting the new
+ ETag value, <literal>00000000aec2c1e9</literal>, and lets Bob try again.
+ This time Bob's changes do not collide with other changes. Babs's entry is
+ successfully updated.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description: Employee of the Month
+telephoneNumber: +47 2108 1746
+roomNumber: 1389
+l: Grenoble
+ETag: 00000000e882c35e</programlisting>
+ </example>
+ </section>
+
+ <section xml:id="filter-adds-modifies">
+ <title>Filtering Add & Modify Operations</title>
+ <indexterm>
+ <primary>Updating data</primary>
+ <secondary>Filtering</secondary>
+ </indexterm>
+
+ <para>Some client applications send updates including attributes with names
+ that differ from the attribute names defined in OpenDJ. Other client
+ applications might try to update attributes they should not update, such
+ as the operational attributes <literal>creatorsName</literal>,
+ <literal>createTimestamp</literal>, <literal>modifiersName</literal>,
+ and <literal>modifyTimestamp</literal>. Ideally you would fix the client
+ application behavior, but that is not always feasible.</para>
+
+ <para>You can configure the attribute cleanup plugin to filter add and
+ modify requests, renaming attributes in requests using incorrect names,
+ and removing attributes that applications should not change.</para>
+
+ <example xml:id="attr-cleanup-rename">
+ <title>Renaming Incoming Attributes</title>
+
+ <para>The following example renames incoming <literal>email</literal>
+ attributes to <literal>mail</literal> attributes. First, configure the
+ attribute cleanup plugin to rename the inbound attribute.</para>
+
+ <screen>$ dsconfig
+ create-plugin
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --type attribute-cleanup
+ --plugin-name "Rename email to mail"
+ --set enabled:true
+ --set rename-inbound-attributes:email:mail
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Next, see that it works as expected.</para>
+
+ <screen>$ cat email.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+email: newuser@example.com
+userPassword: changeme
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename email.ldif
+Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
+ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=newuser mail
+dn: uid=newuser,ou=People,dc=example,dc=com
+mail: newuser@example.com</screen>
+ </example>
+
+ <example xml:id="attr-cleanup-remove">
+ <title>Removing Incoming Attributes</title>
+
+ <para>The following example prevents client applications from adding or
+ modifying <literal>creatorsName</literal>,
+ <literal>createTimestamp</literal>, <literal>modifiersName</literal>,
+ and <literal>modifyTimestamp</literal> attributes. First, set up the
+ attribute cleanup plugin.</para>
+
+ <screen>$ dsconfig
+ create-plugin
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --type attribute-cleanup
+ --plugin-name "Remove attrs"
+ --set enabled:true
+ --set remove-inbound-attributes:creatorsName
+ --set remove-inbound-attributes:createTimestamp
+ --set remove-inbound-attributes:modifiersName
+ --set remove-inbound-attributes:modifyTimestamp
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Next, see that it works as expected.</para>
+
+ <screen>$ cat badattrs.ldif
+dn: uid=badattr,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: Bad Attr
+sn: Attr
+ou: People
+mail: badattr@example.com
+userPassword: changeme
+creatorsName: cn=Bad Attr
+createTimestamp: Never in a million years.
+modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
+modifyTimestamp: 20110930164937Z
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename badattrs.ldif
+Processing ADD request for uid=badattr,ou=People,dc=example,dc=com
+ADD operation successful for DN uid=badattr,ou=People,dc=example,dc=com
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=badattr +
+dn: uid=badattr,ou=People,dc=example,dc=com
+numSubordinates: 0
+structuralObjectClass: inetOrgPerson
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: uid=badattr,ou=people,dc=example,dc=com
+entryUUID: 35e5cb0e-e929-49d8-a50f-2df036d60db9
+pwdChangedTime: 20110930165959.135Z
+creatorsName: cn=Directory Manager,cn=Root DNs,cn=config
+createTimestamp: 20110930165959Z</screen>
+ </example>
+ </section>
+
+ <section xml:id="rename-ldap">
+ <title>Renaming Entries</title>
+
+ <para>The Relative Distinguished Name (RDN) refers to the part of an
+ entry's DN that distinguishes it from all other DNs at the same level
+ in the directory tree. For example <literal>uid=bjensen</literal> is
+ the RDN of the entry having DN
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.</para>
+
+ <para>With the <command>ldapmodify</command> command, authorized users
+ can rename entries in the directory.</para>
+
+ <para>When you change the RDN of the entry, you are renaming the entry,
+ modifying the value of the naming attribute, but also modifying the entry's
+ DN.</para>
+
+ <example xml:id="rename-modrdn">
+ <title>Rename: Modifying the DN</title>
+
+ <para>Sam Carter is changing her last name to Jensen, and changing her
+ login from <literal>scarter</literal> to <literal>sjensen</literal>.
+ The following example renames and changes Sam Carter's entry accordingly.
+ Notice the boolean field, <literal>deleteoldrdn: 1</literal>, which
+ indicates that the previous RDN, <literal>uid: scarter</literal>, should
+ be removed. (Setting <literal>deleteoldrdn: 0</literal> instead would
+ preserve <literal>uid: scarter</literal> on the entry.)</para>
+
+ <screen>$ cat /path/to/scarter-sjensen.ldif
+dn: uid=scarter,ou=people,dc=example,dc=com
+changetype: modrdn
+newrdn: uid=sjensen
+deleteoldrdn: 1
+
+dn: uid=sjensen,ou=people,dc=example,dc=com
+changetype: modify
+replace: cn
+cn: Sam Jensen
+-
+replace: sn
+sn: Jensen
+-
+replace: homeDirectory
+homeDirectory: /home/sjensen
+-
+replace: mail
+mail: sjensen@example.com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --filename /path/to/scarter-sjensen.ldif
+Processing MODIFY DN request for uid=scarter,ou=people,dc=example,dc=com
+MODIFY DN operation successful for DN uid=scarter,ou=people,dc=example,dc=com
+Processing MODIFY request for uid=sjensen,ou=people,dc=example,dc=com
+MODIFY operation successful for DN uid=sjensen,ou=people,dc=example,dc=com</screen>
+ </example>
+ </section>
+
+ <section xml:id="rename-moddn">
+ <title>Moving Entries</title>
+
+ <para>When you rename an entry with child entries, the directory has
+ to move all the entries underneath.</para>
+
+ <note>
+ <para>The modify DN operation only works when moving entries in the same
+ backend, under the same suffix. Also, depending on the number of entries
+ you move, this can be a resource-intensive operation.</para>
+ </note>
+
+ <para>With the <command>ldapmodify</command> command, authorized users
+ can move entries in the directory.</para>
+
+ <example xml:id="move-entry-example"><?dbfo keep-together="auto"?>
+ <title>Move: Merging Customer and Employees Under
+ <literal>ou=People</literal></title>
+
+ <para>The following example moves
+ <literal>ou=Customers,dc=example,dc=com</literal> to
+ <literal>ou=People,dc=example,dc=com</literal>, and then moves each
+ employee under <literal>ou=Employees,dc=example,dc=com</literal>
+ under <literal>ou=People,dc=example,dc=com</literal> as well, finally
+ removing the empty <literal>ou=Employees,dc=example,dc=com</literal>
+ container. Here, <literal>deleteoldrdn: 1</literal> indicates that the
+ old RDN, <literal>ou: Customers</literal>, should be removed from the
+ entry. For employees, <literal>deleteoldrdn: 0</literal> indicates that
+ old RDNs, in this case <literal>uid</literal> attribute values, should
+ be preserved.</para>
+
+ <screen>$ cat move-customers.ldif
+dn: ou=Customers,dc=example,dc=com
+changetype: modrdn
+newrdn: ou=People
+deleteoldrdn: 1
+newsuperior: dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename move-customers.ldif
+Processing MODIFY DN request for ou=Customers,dc=example,dc=com
+MODIFY DN operation successful for DN ou=Customers,dc=example,dc=com
+$ cat move-employees.pl
+#!/usr/bin/perl -w
+
+# For each employee, construct a spec to move under ou=People.
+while (<>)
+{
+ # Next line folded for readability only. Should not be split.
+ $_ =~ s/dn: (.*?)(,.*)/dn: $1$2\nchangetype: moddn\nnewrdn: $1\n
+ deleteoldrdn: 0\nnewsuperior: ou=People,dc=example,dc=com/;
+ print;
+}
+$ ldapsearch --port 1389 --baseDN ou=Employees,dc=example,dc=com uid=* - |
+ move-employees.pl > /tmp/move-employees.ldif
+$ head -n 6 /tmp/move-employees.ldif
+dn: uid=abarnes,ou=Employees,dc=example,dc=com
+changetype: moddn
+newrdn: uid=abarnes
+deleteoldrdn: 0
+newsuperior: ou=People,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename /tmp/move-employees.ldif
+Processing MODIFY DN request for uid=abarnes,ou=Employees,dc=example,dc=com
+MODIFY DN operation successful for DN uid=abarnes,ou=Employees,dc=example,dc=com
+Processing MODIFY DN request for uid=abergin,ou=Employees,dc=example,dc=com
+MODIFY DN operation successful for DN uid=abergin,ou=Employees,dc=example,dc=com
+...
+Processing MODIFY DN request for uid=wlutz,ou=Employees,dc=example,dc=com
+MODIFY DN operation successful for DN uid=wlutz,ou=Employees,dc=example,dc=com
+$ ldapdelete
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ ou=Employees,dc=example,dc=com
+Processing DELETE request for ou=Employees,dc=example,dc=com
+DELETE operation successful for DN ou=Employees,dc=example,dc=com</screen>
+ </example>
+ </section>
+
+ <section xml:id="delete-ldap">
+ <title>Deleting Entries</title>
+
+ <para>With the <command>ldapmodify</command> command, authorized users
+ can delete entries from the directory.</para>
+
+ <example xml:id="delete-subtree">
+ <title>Delete: Removing a Subtree</title>
+
+ <para>The following example uses the subtree delete option to remove
+ all Special Users from the directory.</para>
+
+ <screen>$ ldapdelete
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --deleteSubtree "ou=Special Users,dc=example,dc=com"
+Processing DELETE request for ou=Special Users,dc=example,dc=com
+DELETE operation successful for DN ou=Special Users,dc=example,dc=com</screen>
+ </example>
+ </section>
+ </section>
+
+ <section xml:id="change-password">
+ <title>Changing Passwords</title>
+ <indexterm><primary>Passwords</primary><secondary>Changing</secondary></indexterm>
+
+ <para>With the <command>ldappasswordmodify</command> command, authorized
+ users can change and reset user passwords.</para>
+
+ <example xml:id="password-reset">
+ <title>Password Reset</title>
+ <indexterm>
+ <primary>Resetting passwords</primary>
+ </indexterm>
+
+ <para>The following example shows Kirsten Vaughan resetting Sam Carter's
+ password. Kirsten has the appropriate privilege to reset Sam's
+ password.</para>
+
+ <screen>$ ldappasswordmodify
+ --useStartTLS
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --authzID "dn:uid=scarter,ou=people,dc=example,dc=com"
+ --newPassword ChangeMe
+The LDAP password modify operation was successful</screen>
+
+ <tip>
+ <para>Whenever one user changes another user's password, OpenDJ considers
+ it a password reset. That often means the user has to change her password
+ again after the reset.</para>
+ <para>If you want your application to change a user's password, rather
+ than reset a user's password, have your application request the password
+ change as the user whose password is changing. To change the password as
+ the user, either bind as the user or use proxied authorization. For
+ instructions on the latter, see the section on <link
+ xlink:href="admin-guide#proxied-authz"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
+ Proxied Authorization</citetitle></link>.</para>
+ </tip>
+
+ <para>You could also accomplish password reset with the following command,
+ but <command>set-password-is-reset</command> is a hidden option, supported
+ only for testing.</para>
+
+ <screen>$ manage-account
+ set-password-is-reset
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --targetDN uid=scarter,ou=people,dc=example,dc=com
+ --operationValue true
+Password Is Reset: true</screen>
+ </example>
+
+ <example xml:id="change-own-password">
+ <title>Change Own Password</title>
+
+ <para>You can use the <command>ldappasswordmodify</command> command to
+ change your password, as long as you know your current password.</para>
+
+ <screen>$ ldappasswordmodify
+ --port 1389
+ --authzID "dn:uid=bjensen,ou=people,dc=example,dc=com"
+ --currentPassword hifalutin
+ --newPassword secret12
+The LDAP password modify operation was successful</screen>
+
+ <para>The same operation works for <literal>cn=Directory
+ Manager</literal>.</para>
+
+ <screen>$ ldappasswordmodify
+ --port 1389
+ --authzID "dn:cn=Directory Manager"
+ --currentPassword password
+ --newPassword secret12
+The LDAP password modify operation was successful</screen>
+ </example>
+
+ <example xml:id="non-ascii-password">
+ <title>Passwords With Special Characters</title>
+
+ <para>OpenDJ expects passwords to be UTF-8 encoded (base64 encoded when
+ included in LDIF).</para>
+
+ <screen>$ echo $LANG
+en_US.utf8
+$ ldappasswordmodify
+ --port 1389
+ --bindDN uid=bjensen,ou=People,dc=example,dc=com
+ --bindPassword hifalutin
+ --currentPassword hifalutin
+ --newPassword pàsswȏrd
+The LDAP password modify operation was successful
+$ ldapsearch
+ --port 1389
+ --bindDN uid=bjensen,ou=People,dc=example,dc=com
+ --bindPassword pàsswȏrd
+ --baseDN dc=example,dc=com
+ "(uid=bjensen)" cn
+dn: uid=bjensen,ou=People,dc=example,dc=com
+userPassword: {SSHA}k0eEeCxj9YRXUp8yJn0Z/mwqe+wrcFb1N1gg2g==
+cn: Barbara Jensen
+cn: Babs Jensen
+</screen>
+ </example>
+ </section>
+
+ <section xml:id="tools-properties">
+ <title>Configuring Default Settings</title>
+ <indexterm><primary>Ports</primary><secondary>Settings for tools</secondary></indexterm>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ <para>The location on Windows is
+ <filename>%UserProfile%/.opendj/tools.properties</filename>.</para>
+ </section>
+
+ <section xml:id="client-auth">
+ <title>Authenticating To the Directory Server</title>
+ <indexterm><primary>Authenticating</primary></indexterm>
+
+ <para>Authentication is the act of confirming the identity of a principal.
+ Authorization is the act of determining whether to grant or to deny access to
+ a principal. Authentication is done to make authorization decisions.</para>
+
+ <para>As explained in <link xlink:href="admin-guide#chap-privileges-acis"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
+ Privileges & Access Control</citetitle></link>, OpenDJ directory server
+ implements fine-grained access control for authorization. What is authorized
+ depends on who is requesting the operation. Directory servers like OpenDJ must
+ first therefore authenticate the principals using the clients before they can
+ authorize or deny access. The LDAP bind operation, where a directory client
+ authenticates with the directory server, is therefore the first LDAP operation
+ in every LDAP session.</para>
+
+ <para>Clients bind by providing both a means to find their principal's entry
+ in the directory and also providing some credentials that the directory server
+ can check against their entry.</para>
+
+ <para>In the simplest bind operation, the client provides a zero-length
+ name and a zero-length password. This results in an anonymous bind, meaning
+ the client is authenticated as an anonymous user of the directory. In the
+ simplest examples in <xref linkend="search-ldap" />, notice that no
+ authentication information is provided. The examples work because the
+ client commands default to requesting anonymous binds when you provide no
+ credentials, and because access controls for the sample data allow anonymous
+ clients to read, search, and compare some directory data.</para>
+
+ <para>In a simple bind operation, the client provides an LDAP name, such as
+ the DN identifying its entry, and the corresponding password stored on the
+ <literal>userPassword</literal> attribute of the entry. In
+ <xref linkend="write-ldap" />, notice that to change directory data the
+ client provides the bind DN and bind password of a user who has permission
+ to change directory data. The commands do not work with a bind DN and bind
+ password because access controls for the sample data only allow authorized
+ users to change directory data.</para>
+
+ <para>Users rarely provide client applications with DNs, however. Instead
+ users might provide a client application with an identity string like a user
+ ID or an email address for example. Depending on how the DNs are constructed,
+ the client application can either build the DN directly from the user's
+ identity string, or use a session where the bind has been done with some
+ other identity to search for the user entry based on the user's identity
+ string. Given the DN constructed or found, the client application can then
+ perform a simple bind.</para>
+
+ <para>For example, suppose Babs Jensen enters her email address,
+ <literal>bjensen@example.com</literal>, and her password in order to log in.
+ The client application might search for the entry matching
+ <literal>(mail=bjensen@example.com)</literal> under base DN
+ <literal>dc=example,dc=com</literal>. Alternatively, the client application
+ might know to extract the user ID <literal>bjensen</literal> from the address,
+ and then build the corresponding DN,
+ <literal>uid=bjensen,ou=people,dc=example,dc=com</literal> in order to
+ bind.</para>
+
+ <indexterm><primary>Identity mappers</primary></indexterm>
+ <para>When an identifier string provided by the user can readily be mapped to
+ the user's entry DN, OpenDJ directory server can do the translation between
+ the identifier string and the entry DN. This translation is the job of a
+ component called an identity mapper. Identity mappers are used to perform
+ PLAIN SASL authentication (with a user name and password), SASL GSSAPI
+ authentication (Kerberos V5), SASL CRAM MD5 and DIGEST MD5 authentication.
+ They also handle authorization IDs during password modify extended operations
+ and proxied authorization.</para>
+
+ <para>One use of PLAIN SASL is to translate user names from HTTP Basic
+ authentication to LDAP authentication. The following example shows PLAIN SASL
+ authentication using the default Exact Match identity mapper. In this
+ (contrived) example, Babs Jensen reads the hashed value of her password.
+ (According to the access controls in the example data, Babs must authenticate
+ to read her password.) Notice the authentication ID is her user ID,
+ <literal>u:bjensen</literal>, rather than the DN of her entry.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --useStartTLS
+ --baseDN dc=example,dc=com
+ --saslOption mech=PLAIN
+ --saslOption authid=u:bjensen
+ --bindPassword hifalutin
+ "(cn=Babs Jensen)" cn userPassword
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</screen>
+
+ <para>The Exact Match identity mapper searches for a match between the string
+ provided (here, <literal>bjensen</literal>) and the value of a specified
+ attribute (by default the <literal>uid</literal> attribute). If
+ you know users are entering their email addresses, you could create an
+ exact match identity mapper for email addresses, and then use that for PLAIN
+ SASL authentication as in the following example.</para>
+
+ <screen>$ dsconfig
+ create-identity-mapper
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --mapper-name "Email Mapper"
+ --type exact-match
+ --set match-attribute:mail
+ --set enabled:true
+ --no-prompt
+$ dsconfig
+ set-sasl-mechanism-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name PLAIN
+ --set identity-mapper:"Email Mapper"
+ --no-prompt
+$ ldapsearch
+ --port 1389
+ --useStartTLS
+ --baseDN dc=example,dc=com
+ --saslOption mech=PLAIN
+ --saslOption authid=u:bjensen@example.com
+ --bindPassword hifalutin
+ "(cn=Babs Jensen)" cn userPassword
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</screen>
+
+ <para>The Regular Expression identity mapper uses a regular expression to
+ extract a substring from the string provided, and then searches for a match
+ between the substring and the value of a specified attribute. In the case
+ of example data where an email address is <replaceable>user ID</replaceable>
+ + @ + <replaceable>domain</replaceable>, you can use the default Regular
+ Expression identity mapper in the same way as the email mapper from the
+ previous example. The default regular expression pattern is
+ <literal>^([^@]+)@.+$</literal>, and the part of the identity string matching
+ <literal>([^@]+)</literal> is used to find the entry by user ID.</para>
+
+ <screen>$ dsconfig
+ set-sasl-mechanism-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name PLAIN
+ --set identity-mapper:"Regular Expression"
+ --no-prompt
+$ ldapsearch
+ --port 1389
+ --useStartTLS
+ --baseDN dc=example,dc=com
+ --saslOption mech=PLAIN
+ --saslOption authid=u:bjensen@example.com
+ --bindPassword hifalutin
+ "(cn=Babs Jensen)" cn userPassword
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</screen>
+
+ <para>Try the <command>dsconfig</command> command interactively to experiment
+ with <literal>match-pattern</literal> and <literal>replace-pattern</literal>
+ settings for the Regular Expression identity mapper. The
+ <literal>match-pattern</literal> can be any regular expression supported by
+ <literal>javax.util.regex.Pattern</literal>.</para>
+ </section>
+
+ <section xml:id="proxied-authz">
+ <title>Configuring Proxied Authorization</title>
+ <indexterm><primary>Proxied authorization</primary></indexterm>
+ <para>Proxied authorization provides a standard control as defined in <link
+ xlink:href='http://tools.ietf.org/html/rfc4370'>RFC 4370</link> (and an
+ earlier Internet-Draft) for binding with the user credentials of a proxy, who
+ carries out LDAP operations on behalf of other users. You might use proxied
+ authorization, for example, to have your application bind with its
+ credentials, and then carry out operations as the users who login to the
+ application.</para>
+
+ <para>Suppose you have an administrative directory client application that
+ has an entry in the directory with DN
+ <literal>cn=My App,ou=Apps,dc=example,dc=com</literal>. You can give that
+ application the access rights and privileges to use proxied authorization.
+ The default access control for OpenDJ permits authenticated users to use
+ the proxied authorization control.</para>
+
+ <para>Suppose also that when directory administrator, Kirsten Vaughan, logs
+ in to your application to change Babs Jensen's entry, your application looks
+ up Kirsten's entry, and finds that she has DN
+ <literal>uid=kvaughan,ou=People,dc=example,dc=com</literal>. For the example
+ commands in the following procedure. My App uses proxied authorization to
+ make a change to Babs's entry as Kirsten.</para>
+
+ <procedure xml:id="setup-proxied-authz">
+ <title>To Set Up Proxied Authorization</title>
+ <step>
+ <para>Grant access to applications that can use proxied authorization.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: dc=example,dc=com
+changetype: modify
+add: aci
+aci: (target="ldap:///dc=example,dc=com") (targetattr ="*
+ ")(version 3.0; acl "Allow apps proxied auth"; allow(all, proxy
+ )(userdn = "ldap:///cn=*,ou=Apps,dc=example,dc=com");)
+
+Processing MODIFY request for dc=example,dc=com
+MODIFY operation successful for DN dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Grant the privilege to use proxied authorization to My App.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: cn=My App,ou=Apps,dc=example,dc=com
+changetype: modify
+add: ds-privilege-name
+ds-privilege-name: proxied-auth
+
+Processing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
+MODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Test that My App can use proxied authorization.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=My App,ou=Apps,dc=example,dc=com"
+ --bindPassword password
+ --proxyAs "dn:uid=kvaughan,ou=People,dc=example,dc=com"
+dn: uid=bjensen,ou=People,dc=example,dc=com
+changetype: modify
+replace: description
+description: Changed through proxied auth
+
+Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com</screen>
+ </step>
+ </procedure>
+
+ <para>If you need to map authorization identifiers using the
+ <literal>u:</literal> form rather than using <literal>dn:</literal>, you can
+ set the identity mapper with the global configuration setting,
+ <literal>proxied-authorization-identity-mapper</literal>. For example, if you
+ get user ID values from the client, such as <literal>bjensen</literal>, you
+ can use the Exact Match Identity Mapper to match those to DNs based on an
+ attribute of the entry. Use the <command>dsconfig</command> command
+ interactively to investigate the settings you need.</para>
+ </section>
+
+ <section xml:id="client-cert-auth">
+ <title>Authenticating Using a Certificate</title>
+ <indexterm><primary>Certificates</primary></indexterm>
+ <indexterm><primary>StartTLS</primary></indexterm>
+ <indexterm><primary>SSL</primary></indexterm>
+
+ <para>One alternative to simple binds with user name/password combinations
+ consists in storing a digital certificate on the user entry, and then using
+ the certificate as credentials during the bind. You can use this mechanism for
+ example to let applications bind without using passwords.</para>
+
+ <para>Simply by setting up a secure connection with a certificate, the client
+ is in effect authenticating to the server. The server must close the
+ connection if it cannot trust the client certificate. However, the process
+ of establishing a secure connection does not in itself identify the client
+ to OpenDJ directory server.</para>
+
+ <para>Instead when binding with a certificate, the client must request the
+ SASL External mechanism by which OpenDJ directory server maps the certificate
+ to the client entry in the directory. When it finds a match, OpenDJ sets the
+ authorization identity for the connection to that of the client, and the bind
+ is successful.</para>
+
+ <para>For the whole process of authenticating with a certificate to work
+ smoothly, OpenDJ and the client must trust each others' certificates, the
+ client certificate must be stored on the client entry in the directory, and
+ OpenDJ must be configured to map the certificate to the client entry.</para>
+
+ <procedure xml:id="add-client-cert">
+ <title>To Add Certificate Information to an Entry</title>
+
+ <para>Before trying to bind to OpenDJ directory server using a certificate,
+ create a certificate, and then add the certificate attributes to the
+ entry.</para>
+
+ <para><link xlink:href="http://opendj.forgerock.org/Example.ldif"
+ xlink:show="new">Example.ldif</link> includes an entry for
+ <literal>cn=My App,ou=Apps,dc=example,dc=com</literal>. Examples in this
+ section use that entry, and use the Java <command>keytool</command> command
+ to manage the certificate.</para>
+
+ <step>
+ <para>Create a certificate using the DN of the client entry as the
+ distinguished name string.</para>
+
+ <screen>$ keytool
+ -genkey
+ -alias myapp-cert
+ -keyalg rsa
+ -dname "cn=My App,ou=Apps,dc=example,dc=com"
+ -keystore keystore
+ -storepass changeit
+ -keypass changeit</screen>
+ </step>
+
+ <step>
+ <para>Get the certificate signed.</para>
+
+ <para>If you cannot get the certificate signed by a Certificate Authority,
+ self-sign the certificate.</para>
+
+ <screen>$ keytool
+ -selfcert
+ -alias myapp-cert
+ -validity 7300
+ -keystore keystore
+ -storepass changeit
+ -keypass changeit</screen>
+ </step>
+
+ <step>
+ <para>Make note of the certificate fingerprints.</para>
+
+ <para>Later in this procedure you update the client application entry with
+ the MD5 fingerprint, which in this example is
+ <literal>48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37</literal>.</para>
+ <screen>$ keytool
+ -list
+ -v
+ -alias myapp-cert
+ -keystore keystore
+ -storepass changeit
+Alias name: myapp-cert
+Creation date: Jan 18, 2013
+Entry type: PrivateKeyEntry
+Certificate chain length: 1
+Certificate[1]:
+Owner: CN=My App, OU=Apps, DC=example, DC=com
+Issuer: CN=My App, OU=Apps, DC=example, DC=com
+Serial number: 5ae2277
+Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
+Certificate fingerprints:
+ MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
+ SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
+ SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3
+ Signature algorithm name: SHA256withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E..
+0010: C9 6B 32 95 .k2.
+]
+]</screen>
+ </step>
+
+ <step>
+ <para>Export the certificate to a file in binary format.</para>
+
+ <screen>$ keytool
+ -export
+ -alias myapp-cert
+ -keystore keystore
+ -storepass changeit
+ -keypass changeit
+ -file myapp-cert.crt
+Certificate stored in file </path/to/myapp-cert.crt></screen>
+ </step>
+
+ <step>
+ <para>Modify the entry to add attributes related to the certificate.</para>
+
+ <para>By default, you need the <literal>userCertificate</literal>
+ value.</para>
+
+ <para>If you want OpenDJ to map the certificate to its fingerprint, use
+ <literal>ds-certificate-fingerprint</literal>. This example uses the MD5
+ fingerprint, which corresponds to the default setting for the Fingerprint
+ Certificate Mapper.</para>
+
+ <para>If you want to map the certificate subject DN to an attribute of the
+ entry, use <literal>ds-certificate-subject-dn</literal>.</para>
+
+ <screen>$ cat addcert.ldif
+dn: cn=My App,ou=Apps,dc=example,dc=com
+changetype: modify
+add: objectclass
+objectclass: ds-certificate-user
+-
+add: ds-certificate-fingerprint
+ds-certificate-fingerprint: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
+-
+add: ds-certificate-subject-dn
+ds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com
+-
+add: userCertificate;binary
+userCertificate;binary:<file:///path/to/myapp-cert.crt
+
+$ ldapmodify
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename addcert.ldif
+Processing MODIFY request for cn=My App,ou=Apps,dc=example,dc=com
+MODIFY operation successful for DN cn=My App,ou=Apps,dc=example,dc=com</screen>
+ </step>
+
+ <step>
+ <para>Check your work.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ "(cn=My App)"
+dn: cn=My App,ou=Apps,dc=example,dc=com
+ds-certificate-fingerprint: 4B:F5:CF:2C:2D:B3:86:14:FF:43:A8:37:17:DD:E7:55
+userCertificate;binary:: MIIDOzCCAiOgAwIBAgIESfC6IjANBgkqhkiG9w0BAQsFADBOMRMwEQY
+ KCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhhbXBsZTENMAsGA1UECxMEQXBwczEPMA
+ 0GA1UEAxMGTXkgQXBwMB4XDTEzMDExNzE3MTEwM1oXDTEzMDQxNzE3MTEwM1owTjETMBEGCgmSJomT8
+ ixkARkWA2NvbTEXMBUGCgmSJomT8ixkARkWB2V4YW1wbGUxDTALBgNVBAsTBEFwcHMxDzANBgNVBAMT
+ Bk15IEFwcDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJQYq+jG4ZQdNkyBT4OQBZ0sFkl
+ X5o2yBViDMGl1sSWIRGLpFwu6iq1chndPBJYTC+FkT66yEEOwWOpSfcYdFHkMQP0qp5A8mgP6bYkeH1
+ ROvQ1nhLs0ILuksR10CVIQ5b1zv6bGEFhA9gSKmpHfQOSt9PXq8+kuz+4RgZk9Il28tgDNMm91wSJr7
+ kqi5g7a2a7Io5s9L2FeLhVSBYwinWQnASk8nENrhcE0hHkrpGsaxdhIQBQQvm+SRC0dI4E9iwBGI3Lw
+ lV3a4KTa5DlYD6cDREI6B8XlSdc1DaIhwC8CbsE0WJQoCERSURdjkuHrPck6f69HKUFRiC7JMT3dFbs
+ CAwEAAaMhMB8wHQYDVR0OBBYEFFTAxZxzN4VL8jvTN/1FCqvJazKVMA0GCSqGSIb3DQEBCwUAA4IBAQ
+ BXsAIEw7I5XUzLFHvXb2N0hmW/Vmhb/Vlv9LTT8JcCRJy4zaiyS9Q+Sp9zQUkrXauFnNAhJLwpAymjZ
+ MCOq1Th1bw9LnIzbccPQ/1+ZHLKDU5pgnc5BcvaV6Zl6COLLH2OOt0XMZ/OrODBV1M6STfhChqcowff
+ xp72pWMQe+kpZfzjeDBk4kK2hUNTZsimB9qRyrDAMCIXdmdmFv1o07orxjy8c/6S1329swiiVqFckBR
+ aXIa8wCcXjpQbZacDODeKk6wZIKxw4miLg1YByCMa7vkUfz+Jj+JHgbHjyoT/G82mtDbX02chLgXbDm
+ xJPFN3mwAC7NEkSPbqd35nJlf3
+objectClass: person
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: ds-certificate-user
+objectClass: top
+ds-certificate-subject-dn: CN=My App, OU=Apps, DC=example, DC=com
+cn: My App
+sn: App</screen>
+ </step>
+
+ <step>
+ <para>When using a self-signed certificate, import the client certificate
+ into the trust store for OpenDJ.</para>
+
+ <para>When the client presents its certificate to OpenDJ, by default OpenDJ
+ has to be able to trust the client certificate before it can accept the
+ connection. If OpenDJ cannot trust the client certificate, it cannot
+ establish a secure connection.</para>
+
+ <screen>$ keytool
+ -import
+ -alias myapp-cert
+ -file /path/to/myapp-cert.crt
+ -keystore /path/to/opendj/config/truststore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+Owner: CN=My App, OU=Apps, DC=example, DC=com
+Issuer: CN=My App, OU=Apps, DC=example, DC=com
+Serial number: 5ae2277
+Valid from: Fri Jan 18 18:27:09 CET 2013 until: Thu Jan 13 18:27:09 CET 2033
+Certificate fingerprints:
+ MD5: 48:AC:F9:13:11:E0:AB:C4:65:A2:83:9E:DB:FE:0C:37
+ SHA1: F9:61:54:37:AA:C1:BC:92:45:07:64:4B:23:6C:BC:C9:CD:1D:44:0F
+ SHA256: 2D:B1:58:CD:33:40:E9:...:FD:61:EA:C9:FF:6A:19:93:FE:E4:84:E3
+ Signature algorithm name: SHA256withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 54 C0 C5 9C 73 37 85 4B F2 3B D3 37 FD 45 0A AB T...s7.K.;.7.E..
+0010: C9 6B 32 95 .k2.
+]
+]
+
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+ </step>
+
+ <step>
+ <para>When using a certificate signed by a CA whose certificate is not
+ delivered with the Java runtime environment<footnote>
+ <para><filename>$JAVA_HOME/jre/lib/security/cacerts</filename> holds the
+ certificates for many CAs. To get the full list, use the following
+ command.</para>
+ <screen>$ keytool
+ -list
+ -v
+ -keystore $JAVA_HOME/jre/lib/security/cacerts
+ -storepass changeit</screen></footnote>, import the CA certificate either
+ into the Java runtime environment trust store, or into the OpenDJ trust
+ store as shown in the following example.</para>
+
+ <screen>$ keytool
+ -import
+ -alias ca-cert
+ -file ca.crt
+ -keystore /path/to/opendj/config/truststore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+Owner: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
+Issuer: EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR
+Serial number: d4586ea05c878b0c
+Valid from: Tue Jan 29 09:30:31 CET 2013 until: Mon Jan 24 09:30:31 CET 2033
+Certificate fingerprints:
+ MD5: 8A:83:61:9B:E7:18:A2:21:CE:92:94:96:59:68:60:FA
+ SHA1: 01:99:18:38:3A:57:D7:92:7B:D6:03:8C:7B:E4:1D:37:45:0E:29:DA
+ SHA256: 5D:20:F1:86:CC:CD:64:50:1E:54:...:DF:15:43:07:69:44:00:FB:36:CF
+ Signature algorithm name: SHA1withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.35 Criticality=false
+AuthorityKeyIdentifier [
+KeyIdentifier [
+0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
+0010: 03 D4 56 7B ..V.
+]
+[EMAILADDRESS=admin@example.com, CN=Example CA, O=Example Corp, C=FR]
+SerialNumber: [ d4586ea0 5c878b0c]
+]
+
+#2: ObjectId: 2.5.29.19 Criticality=false
+BasicConstraints:[
+ CA:true
+ PathLen:2147483647
+]
+
+#3: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: 30 07 67 7D 1F 09 B6 E6 90 85 95 58 94 37 FD 31 0.g........X.7.1
+0010: 03 D4 56 7B ..V.
+]
+]
+
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+ </step>
+
+ <step>
+ <para>If you updated the OpenDJ trust store to add a certificate, restart
+ OpenDJ to make sure it reads the updated trust store and can recognize the
+ certificate.</para>
+
+ <screen>$ stop-ds --restart
+Stopping Server...
+...
+... The Directory Server has started successfully</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="config-cert-mappers">
+ <title>To Configure Certificate Mappers</title>
+
+ <variablelist>
+ <para>OpenDJ uses certificate mappers during binds to establish a mapping
+ between a client certificate and the entry that corresponds to that
+ certificate. The certificate mappers provided out of the box include the
+ following.</para>
+
+ <varlistentry>
+ <term>Fingerprint Certificate Mapper</term>
+ <listitem>
+ <para>Looks for the MD5 (default) or SHA1 certificate fingerprint in an
+ attribute of the entry (default:
+ <literal>ds-certificate-fingerprint</literal>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Subject Attribute To User Attribute Mapper</term>
+ <listitem>
+ <para>Looks for a match between an attribute of the certificate subject
+ and an attribute of the entry (default: match <literal>cn</literal> in
+ the certificate to <literal>cn</literal> on the entry, or match
+ <literal>emailAddress</literal> in the certificate to
+ <literal>mail</literal> on the entry).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Subject DN to User Attribute Certificate Mapper</term>
+ <listitem>
+ <para>Looks for the certificate subject DN in an attribute of the entry
+ (default: <literal>ds-certificate-subject-dn</literal>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Subject Equals DN Certificate Mapper</term>
+ <listitem>
+ <para>Looks for an entry whose DN matches the certificate subject DN.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>If the default configurations for the certificate mappers are
+ acceptable, you do not need to change them. They are enabled by
+ default.</para>
+
+ <para>The following steps demonstrate how to change the Fingerprint Mapper
+ default algorithm of MD5 to SHA1.</para>
+
+ <step>
+ <para>List the certificate mappers to retrieve the correct name.</para>
+
+ <screen width="83">$ dsconfig
+ list-certificate-mappers
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+
+Certificate Mapper : Type : enabled
+------------------------------------:-------------------------------------:--------
+Fingerprint Mapper : fingerprint : true
+Subject Attribute to User Attribute : subject-attribute-to-user-attribute : true
+Subject DN to User Attribute : subject-dn-to-user-attribute : true
+Subject Equals DN : subject-equals-dn : true</screen>
+ </step>
+
+ <step>
+ <para>Examine the current configuration.</para>
+
+ <screen>$ dsconfig
+ get-certificate-mapper-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --mapper-name "Fingerprint Mapper"
+
+Property : Value(s)
+----------------------:---------------------------
+enabled : true
+fingerprint-algorithm : md5
+fingerprint-attribute : ds-certificate-fingerprint
+user-base-dn : -</screen>
+ </step>
+
+ <step>
+ <para>Change the configuration as necessary.</para>
+
+ <screen>$ dsconfig
+ set-certificate-mapper-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --mapper-name "Fingerprint Mapper"
+ --set fingerprint-algorithm:sha1
+ --no-prompt</screen>
+ </step>
+
+ <step>
+ <para>Set the External SASL Mechanism Handler to use the appropriate
+ certificate mapper (default: Subject Equals DN).</para>
+
+ <para>Clients applications use the SASL External mechanism during the bind
+ to have OpenDJ set the authorization identifier based on the entry that
+ matches the client certificate.</para>
+
+ <screen>$ dsconfig
+ set-sasl-mechanism-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name External
+ --set certificate-mapper:"Fingerprint Mapper"
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <example xml:id="auth-with-client-cert"><?dbfo keep-together="auto"?>
+ <title>Authenticate With Client Certificate</title>
+
+ <para>Instead of providing a bind DN and password as for simple
+ authentication, use the SASL EXTERNAL authentication mechanism, and provide
+ the certificate. As a test with example data you can try an anonymous search,
+ and then try with certificate-based authentication.</para>
+
+ <para>Before you try this example, make sure OpenDJ is set up to accept
+ StartTLS from clients, and that you have set up the client certificate
+ as described above. Next, create a password .pin file for your client key
+ store.</para>
+
+ <screen>$ echo changeit > keystore.pin
+$ chmod 400 keystore.pin</screen>
+
+ <para>Also, if OpenDJ directory server uses a certificate for StartTLS that
+ was not signed by a well-known CA, import the appropriate certificate into
+ the client key store, which can then double as a trust store. For example,
+ if OpenDJ uses a self-signed certificate, import the server certificate into
+ the key store.</para>
+
+ <screen>$ keytool
+ -export
+ -alias server-cert
+ -file server-cert.crt
+ -keystore /path/to/opendj/config/keystore
+ -storepass `cat /path/to/opendj/config/keystore.pin`
+$ keytool
+ -import
+ -trustcacerts
+ -alias server-cert
+ -file server-cert.crt
+ -keystore keystore
+ -storepass `cat keystore.pin`</screen>
+
+ <para>If OpenDJ directory server uses a CA-signed certificate, but the CA is
+ not well known, import the CA certificate into your keystore.</para>
+
+ <screen>$ keytool
+ -import
+ -trustcacerts
+ -alias ca-cert
+ -file ca-cert.crt
+ -keystore keystore
+ -storepass `cat keystore.pin`</screen>
+
+ <para>Now that you can try the example, notice that OpenDJ does not return
+ the <literal>userPassword</literal> value for an anonymous search.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ --useStartTLS
+ --trustStorePath keystore
+ --trustStorePasswordFile keystore.pin
+ "(cn=My App)" userPassword
+dn: cn=My App,ou=Apps,dc=example,dc=com
+</screen>
+
+ <para>OpenDJ does let users read the values of their own
+ <literal>userPassword</literal> attributes after they bind
+ successfully.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ --useStartTLS
+ --useSASLExternal
+ --certNickName myapp-cert
+ --keyStorePath keystore
+ --keyStorePasswordFile keystore.pin
+ --trustStorePath keystore
+ --trustStorePasswordFile keystore.pin
+ "(cn=My App)" userPassword
+dn: cn=My App,ou=Apps,dc=example,dc=com
+userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</screen>
+
+ <para>You can also try the same test with other certificate mappers.</para>
+
+ <screen># Fingerprint mapper
+$ dsconfig
+ set-sasl-mechanism-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name External
+ --set certificate-mapper:"Fingerprint Mapper"
+ --no-prompt
+$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ --useStartTLS
+ --useSASLExternal
+ --certNickName myapp-cert
+ --keyStorePath keystore
+ --keyStorePasswordFile keystore.pin
+ --trustStorePath keystore
+ --trustStorePasswordFile keystore.pin
+ "(cn=My App)" userPassword
+dn: cn=My App,ou=Apps,dc=example,dc=com
+userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==
+
+# Subject Attribute to User Attribute mapper
+$ dsconfig
+ set-sasl-mechanism-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name External
+ --set certificate-mapper:"Subject Attribute to User Attribute"
+ --no-prompt
+$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ --useStartTLS
+ --useSASLExternal
+ --certNickName myapp-cert
+ --keyStorePath keystore
+ --keyStorePasswordFile keystore.pin
+ --trustStorePath keystore
+ --trustStorePasswordFile keystore.pin
+ "(cn=My App)" userPassword
+dn: cn=My App,ou=Apps,dc=example,dc=com
+userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==
+
+# Subject DN to User Attribute mapper
+$ dsconfig
+ set-sasl-mechanism-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name External
+ --set certificate-mapper:"Subject DN to User Attribute"
+ --no-prompt
+$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ --useStartTLS
+ --useSASLExternal
+ --certNickName myapp-cert
+ --keyStorePath keystore
+ --keyStorePasswordFile keystore.pin
+ --trustStorePath keystore
+ --trustStorePasswordFile keystore.pin
+ "(cn=My App)" userPassword
+dn: cn=My App,ou=Apps,dc=example,dc=com
+userPassword: {SSHA}vy/vTthOQoV/wH3MciTOBKKR4OX+0dSN/a09Ew==</screen>
+ </example>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-load-balancing.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-load-balancing.xml
new file mode 100644
index 0000000..54b6ccd
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-load-balancing.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-load-balancing'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Balancing Workload Across Servers</title>
+
+ <para>One main reason for deploying a directory proxy server is to balance
+ workload across the directory servers available. Load balancing works
+ particularly well for read operations, as each directory server can respond
+ to read operations without impact on other directory servers. Load balancing
+ can also be used in reverse for write operations, as in a replicated
+ environment the results of each write operation must be applied on all
+ directory servers to keep their data in sync.</para>
+
+ <para>This chapter demonstrates how to configure proxy load balancing of
+ client application traffic.</para>
+
+</chapter>
+
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-monitoring.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-monitoring.xml
new file mode 100644
index 0000000..6032203
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-monitoring.xml
@@ -0,0 +1,989 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-monitoring'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Monitoring, Logging, & Alerts</title>
+
+ <para>This chapter describes the monitoring capabilities that OpenDJ
+ implements, and shows how to configure them.</para>
+
+ <indexterm><primary>Monitoring</primary></indexterm>
+
+ <para>OpenDJ Control Panel provides basic monitoring capabilities under
+ Monitoring > General Information, Monitoring > Connection Handler, and
+ Monitoring > Manage Tasks. This chapter covers the other options for
+ monitoring OpenDJ.</para>
+
+ <section xml:id="ldap-monitoring">
+ <title>LDAP-Based Monitoring</title>
+
+ <para>OpenDJ exposes monitoring information over LDAP under the entry
+ <literal>cn=monitor</literal>. Many different types of information are
+ exposed. The following example shows monitoring information about the
+ <literal>userRoot</literal> backend holding Example.com data.</para>
+
+ <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ >Evolving</link></para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN cn=monitor "(cn=userRoot backend)"
+dn: cn=userRoot backend,cn=Disk Space Monitor,cn=monitor
+disk-state: normal
+objectClass: top
+objectClass: ds-monitor-entry
+objectClass: extensibleObject
+disk-dir: /path/to/opendj/db/userRoot
+disk-free: 343039315968
+cn: userRoot backend
+
+dn: cn=userRoot Backend,cn=monitor
+objectClass: top
+objectClass: ds-monitor-entry
+objectClass: ds-backend-monitor-entry
+ds-backend-is-private: FALSE
+ds-backend-writability-mode: enabled
+cn: userRoot Backend
+ds-backend-entry-count: 163
+ds-backend-id: userRoot
+ds-base-dn-entry-count: 163 dc=example,dc=com
+ds-backend-base-dn: dc=example,dc=com
+</screen>
+
+ <para>You can set global ACIs on the Access Control Handler if you want
+ to limit read access under <literal>cn=monitor</literal>.</para>
+ </section>
+
+ <section xml:id="snmp-monitoring">
+ <title>SNMP-Based Monitoring</title>
+ <indexterm><primary>SNMP</primary></indexterm>
+
+ <para>OpenDJ lets you monitor the server over the Simple Network Management
+ Protocol (SNMP), with support for the Management Information Base described
+ in <link xlink:href="http://tools.ietf.org/html/rfc2605">RFC 2605: Directory
+ Server Monitoring MIB</link>.</para>
+
+ <para>OpenDJ SNMP-based monitoring depends on OpenDMK, which you must
+ <link xlink:href="http://opendmk.java.net/download/" xlink:show="new">download
+ separately</link>. Install the <link xlink:show="new"
+ xlink:href="http://java.net/projects/opendmk/content/download/opendmk-1.0-b02-bin-dual-01-Oct-2007_19-17-46.jar"
+ >Full Binary Bundle</link> by using the graphical installer, which requires
+ that you accept the <link xlink:show="new"
+ xlink:href="http://java.net/projects/opendmk/content/legal_notices/LICENSE_BINARY.txt"
+ >Binary License for Project OpenDMK</link>. OpenDJ directory server that you
+ download from ForgeRock is built with OpenDMK, but due to licensing OpenDMK
+ is not part of OpenDJ. SNMP is therefore not enabled by default.</para>
+
+ <para>To run the OpenDMK installer, use the self-extracting .jar.</para>
+
+ <screen>$ java -jar ~/Downloads/opendmk-1.0-b02-*.jar</screen>
+
+ <para>If you install under <filename>/path/to</filename>, then the runtime
+ library needed for SNMP is
+ <filename>/path/to/OpenDMK-bin/lib/jdmkrt.jar</filename>.</para>
+
+ <para>Once you have installed OpenDMK, you can set up a connection handler
+ for SNMP by enabling the connection handler, and pointing OpenDJ to your
+ installation of the OpenDMK <filename>jdmkrt.jar</filename> library.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "SNMP Connection Handler"
+ --set enabled:true
+ --set opendmk-jarfile:/path/to/OpenDMK-bin/lib/jdmkrt.jar
+ --trustAll
+ --no-prompt</screen>
+
+ <para>By default, the SNMP Connection Handler listens on port 161 and uses
+ port 162 for traps. On UNIX and Linux systems, only root can normally open
+ these ports. Therefore if you install as a normal user, you might want
+ to change the listen and trap ports.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "SNMP Connection Handler"
+ --set listen-port:11161
+ --set trap-port:11162
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Restart the SNMP Connection Handler to take the port number changes
+ into account.</para>
+ <para> To restart the connection handler, you disable it, then enable
+ it again.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "SNMP Connection Handler"
+ --set enabled:false
+ --trustAll
+ --no-prompt
+$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "SNMP Connection Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Use a command such as <command>snmpwalk</command> to check that the
+ SNMP listen port works.</para>
+
+ <screen>$ snmpwalk -v 2c -c OpenDJ@OpenDJ localhost:11161
+SNMPv2-SMI::mib-2.66.1.1.1.1 = STRING: "OpenDJ <?eval ${docTargetVersion}?>..."
+SNMPv2-SMI::mib-2.66.1.1.2.1 = STRING: "/path/to/opendj"
+...</screen>
+
+ </section>
+
+ <section xml:id="jmx-monitoring">
+ <title>JMX-Based Monitoring</title>
+ <indexterm><primary>JMX</primary></indexterm>
+
+ <para>OpenDJ provides Java Management eXtensions (JMX) based monitoring. A
+ number of tools support JMX, including <command>jconsole</command> and
+ <command>jvisualvm</command>, which are bundled with the Sun/Oracle Java
+ platform. JMX is not configured by default. Use the
+ <command>dsconfig</command> command to configure the JMX connection
+ handler.</para>
+
+ <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ >Evolving</link></para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "JMX Connection Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+
+ <para>By default, no users have privileges to access the JMX connection. The
+ following command adds JMX privileges for Directory Manager.</para>
+
+ <screen>$ dsconfig
+ set-root-dn-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --add default-root-privilege-name:jmx-notify
+ --add default-root-privilege-name:jmx-read
+ --add default-root-privilege-name:jmx-write
+ --trustAll
+ --no-prompt</screen>
+
+ <para>You must also configure security to login remotely. See the section on
+ <citetitle>Using SSL</citetitle> in <link
+ xlink:href="http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html#SSL_enabled"
+ xlink:show="new"><citetitle>Monitoring and Management Using
+ JMX</citetitle></link> for hints.</para>
+
+ <para>Alternatively, you can connect to a local server process by using the
+ server process identifier.</para>
+
+ <screen>$ cat ../logs/server.pid
+3363
+$ jvisualvm --openpid 3363 &</screen>
+ </section>
+
+ <section xml:id="monitoring-status-and-tasks">
+ <title>Server Operation & Tasks</title>
+
+ <para>OpenDJ comes with two commands for monitoring server processes and
+ tasks. The <command>status</command> command displays basic information
+ about the local server, similar to what is seen in the default window of the
+ Control Panel. The <command>manage-tasks</command> command lets you manage
+ tasks scheduled on a server, such as nightly backup.</para>
+
+ <para>The <command>status</command> command takes administrative credentials
+ to read the configuration, as does the Control Panel.</para>
+ <screen>$ status --bindDN "cn=Directory Manager" --bindPassword password
+
+ --- Server Status ---
+Server Run Status: Started
+Open Connections: 1
+
+ --- Server Details ---
+Host Name: localhost
+Administrative Users: cn=Directory Manager
+Installation Path: /path/to/opendj
+Version: OpenDJ <?eval ${docTargetVersion}?>
+Java Version: 1.6.0_24
+Administration Connector: Port 4444 (LDAPS)
+
+ --- Connection Handlers ---
+Address:Port : Protocol : State
+-------------:----------:---------
+-- : LDIF : Disabled
+0.0.0.0:636 : LDAPS : Disabled
+0.0.0.0:1389 : LDAP : Enabled
+0.0.0.0:1689 : JMX : Disabled
+
+ --- Data Sources ---
+Base DN: dc=example,dc=com
+Backend ID: userRoot
+Entries: 163
+Replication: Disabled</screen>
+
+ <para>The <command>manage-tasks</command> command connects over the
+ administration port, and so can connect to both local and remote
+ servers.</para>
+
+ <screen>$ manage-tasks
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --trustAll
+ --no-prompt
+
+ID Type Status
+--------------------------------------------------------
+example Backup Recurring
+example-20110623030000000 Backup Waiting on start time</screen>
+ </section>
+
+ <section xml:id="logging">
+ <title>Server Logs</title>
+ <indexterm><primary>Logs</primary></indexterm>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Log</secondary>
+ </indexterm>
+
+ <para>By default OpenDJ stores access and errors logs as well as a
+ server process ID file under the <filename>logs/</filename> directory.
+ For the replication service, OpenDJ also keeps a replication log there.
+ You can also configure a debug log. Furthermore, you can configure policies
+ about how logs are rotated, and how they are retained. You configure logging
+ using the <command>dsconfig</command> command.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <firstterm>access log</firstterm> traces the operations the
+ server processes including timestamps, connection information, and
+ information about the operation itself. The access log can therefore
+ grow quickly, as each client request results in at least one new log
+ message.</para>
+ <para>The following access log excerpt shows a search operation from the
+ local host, with the first three lines wrapped for readability.</para>
+ <screen>
+[21/Jun/2011:08:01:53 +0200] CONNECT conn=4 from=127.0.0.1:49708
+ to=127.0.0.1:1389 protocol=LDAP
+[21/Jun/2011:08:01:53 +0200] SEARCH REQ conn=4 op=0 msgID=1
+ base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="ALL"
+[21/Jun/2011:08:01:53 +0200] SEARCH RES conn=4 op=0 msgID=1
+ result=0 nentries=1 etime=3
+[21/Jun/2011:08:01:53 +0200] UNBIND REQ conn=4 op=1 msgID=2
+[21/Jun/2011:08:01:53 +0200] DISCONNECT conn=4 reason="Client Unbind"</screen>
+ </listitem>
+ <listitem>
+ <para>The <firstterm>errors log</firstterm> traces server events, error
+ conditions, and warnings, categorized and identified by severity.</para>
+ <para>The following errors log excerpt shows log entries about a
+ backup task, with lines wrapped for readability.</para>
+ <screen>
+[22/Jun/2011:12:32:23 +0200] category=BACKEND severity=NOTICE msgID=9896349
+ msg=Backup task 20110622123224088 started execution
+[22/Jun/2011:12:32:23 +0200] category=TOOLS severity=NOTICE msgID=10944792
+ msg=Starting backup for backend userRoot
+[22/Jun/2011:12:32:24 +0200] category=JEB severity=NOTICE msgID=8847446
+ msg=Archived: 00000000.jdb
+[22/Jun/2011:12:32:24 +0200] category=TOOLS severity=NOTICE msgID=10944795
+ msg=The backup process completed successfully
+[22/Jun/2011:12:32:24 +0200] category=BACKEND severity=NOTICE msgID=9896350
+ msg=Backup task 20110622123224088 finished execution</screen>
+ </listitem>
+
+ <listitem>
+ <para>If you use the HTTP Connection Handler, OpenDJ maintains a separate
+ access log in <filename>logs/http-access</filename>. This access log, by
+ default configured as the File Based HTTP Access Log Publisher, uses
+ a different format than the LDAP access log. This HTTP access log uses
+ <link xlink:href="http://www.w3.org/TR/WD-logfile.html" xlink:show="new"
+ >Extended Log File Format</link> with fields described in <link
+ xlink:show="new"
+ xlink:href="http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/676400bc-8969-4aa7-851a-9319490a9bbb.mspx?mfr=true"
+ >Microsoft's implementation</link> as well. The following default
+ fields are shown here in the order they occur in the log file.</para>
+
+ <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ >Evolving</link></para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>cs-host</literal></term>
+ <listitem>
+ <para>Client host name</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>c-ip</literal></term>
+ <listitem>
+ <para>Client IP address</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cs-username</literal></term>
+ <listitem>
+ <para>Username used to authenticate</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>x-datetime</literal></term>
+ <listitem>
+ <para>Completion timestamp for the HTTP request, which you can configure
+ using the <literal>log-record-time-format</literal> property</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cs-method</literal></term>
+ <listitem>
+ <para>HTTP method requested by the client</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cs-uri-query</literal></term>
+ <listitem>
+ <para>Path and query string requested by the client</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cs-version</literal></term>
+ <listitem>
+ <para>HTTP version requested by the client</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>sc-status</literal></term>
+ <listitem>
+ <para>HTTP status code for the operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cs(User-Agent)</literal></term>
+ <listitem>
+ <para>User-Agent identifier</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>x-connection-id</literal></term>
+ <listitem>
+ <para>Connection ID used for OpenDJ internal operations</para>
+ <para>When using this field to match HTTP requests with internal
+ operations in the LDAP access log, first set the access log advanced
+ property, <literal>suppress-internal-operations</literal>, to
+ <literal>false</literal>. By default, internal operations do not appear
+ in the LDAP access log.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>x-etime</literal></term>
+ <listitem>
+ <para>Execution time in milliseconds needed by OpenDJ to service the
+ HTTP request</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Missing values are replaced with <literal>-</literal>. Tabs separate
+ the fields, and if a field contains a tab character, then the field is
+ surrounded with double quotes. OpenDJ then doubles double quotes in the
+ field to escape them.</para>
+
+ <para>The following example shows an excerpt of an HTTP access log with
+ the default configuration. Lines are folded and space reformatted for the
+ printed page.</para>
+
+ <screen>- 192.168.0.15 bjensen 22/May/2013:10:06:18 +0200
+ GET /users/bjensen?_prettyPrint=true HTTP/1.1 200
+ curl/7.21.4 3 40
+- 192.168.0.15 bjensen 22/May/2013:10:06:52 +0200
+ GET /groups/Directory%20Administrators?_prettyPrint=true HTTP/1.1 200
+ curl/7.21.4 4 41
+- 192.168.0.12 bjensen 22/May/2013:10:07:07 +0200
+ GET /users/missing?_prettyPrint=true HTTP/1.1 200
+ curl/7.21.4 5 9
+- 192.168.0.12 - 22/May/2013:10:07:46 +0200
+ GET /users/missing?_prettyPrint=true HTTP/1.1 401
+ curl/7.21.4 6 0
+- 192.168.0.15 kvaughan 22/May/2013:10:09:10 +0200
+ POST /users?_action=create&_prettyPrint=true HTTP/1.1 200
+ curl/7.21.4 7 120</screen>
+
+ <para>You can configure the <literal>log-format</literal> for the access log
+ using the <command>dsconfig</command> command. In addition to the default
+ fields, the following standard fields are supported.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>c-port</literal></term>
+ <listitem>
+ <para>Client port number</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>s-computername</literal></term>
+ <listitem>
+ <para>Server name where the access log was written</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>s-ip</literal></term>
+ <listitem>
+ <para>Server IP address</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>s-port</literal></term>
+ <listitem>
+ <para>Server port number</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+
+ <listitem>
+ <para>The <firstterm>replication log</firstterm> traces replication
+ events, with entries similar to the errors log. The following excerpt has
+ lines wrapped for readability.</para>
+ <screen>
+[22/Jun/2011:14:37:34 +0200] category=SYNC severity=NOTICE msgID=15139026
+ msg=Finished total update: exported domain "dc=example,dc=com" from this
+ directory server DS(24065) to all remote directory servers.
+[22/Jun/2011:14:37:35 +0200] category=SYNC severity=MILD_WARNING msgID=14745663
+ msg=Replication server RS(23947) at opendj.example.com/10.10.0.168:8989 has
+ closed the connection to this directory server DS(24065). This directory
+ server will now try to connect to another replication server in order to
+ receive changes for the domain "dc=example,dc=com"
+[22/Jun/2011:14:37:35 +0200] category=SYNC severity=NOTICE msgID=15138894
+ msg=The generation ID for domain "dc=example,dc=com" has been reset to 3679640</screen>
+ <para>Notice that the replication log does not trace replication operations.
+ Use the external change log instead to get notifications about changes to
+ directory data over protocol. You can alternatively configure an audit
+ log, which is a type of access log that dumps changes in LDIF.</para>
+ </listitem>
+ <listitem>
+ <para>A <firstterm>debug log</firstterm> traces details needed to
+ troubleshoot a problem in the server. Debug logs can grow large quickly,
+ and therefore no debug logs are enabled by default.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Each log depends on a <firstterm>log publisher</firstterm>, whose
+ type corresponds to the type of log. OpenDJ uses file-based log publishers.
+ The design allows for custom log publishers, however, which could publish
+ the logs elsewhere besides a file.</para>
+
+ <para>For debug logging, you also set a <firstterm>debug target</firstterm>
+ to control what gets logged.</para>
+
+ <section xml:id="log-rotation">
+ <title>Log Rotation & Retention</title>
+
+ <para>Each file-based log can be associated with a <firstterm>log rotation
+ policy</firstterm>, and a <firstterm>log retention policy</firstterm>. The
+ former can specify when, after how much time, or at what maximum size a log
+ is rotated. The latter can specify a maximum number or size of logs to
+ retain, or an amount of free disk space to maintain. The design allows
+ for custom policies as well.</para>
+
+ <para>By default the file-based logs are subject to rotation and retention
+ policies that you can list with <command>dsconfig
+ list-log-rotation-policies</command> and <command>dsconfig
+ list-log-retention-policies</command>.</para>
+
+ <para>For example, view the log rotation policies with the following
+ command.</para>
+
+ <screen width="101">$ dsconfig
+ list-log-rotation-policies
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+
+
+Log Rotation Policy : Type : file-size-limit : rotation-interval : time-of-day
+------------------------------------:------------:-----------------:-------------------:------------
+24 Hours Time Limit Rotation Policy : time-limit : - : 1 d : -
+7 Days Time Limit Rotation Policy : time-limit : - : 1 w : -
+Fixed Time Rotation Policy : fixed-time : - : - : 2359
+Size Limit Rotation Policy : size-limit : 100 mb : - : -</screen>
+
+ <para>View the log retention policies with the following command.</para>
+
+ <screen width="105">$ dsconfig
+ list-log-retention-policies
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+
+
+Log Retention Policy : Type : disk-space-used : free-disk-space : number-of-files
+---------------------------------:-----------------:-----------------:-----------------:----------------
+File Count Retention Policy : file-count : - : - : 10
+Free Disk Space Retention Policy : free-disk-space : - : 500 mb : -
+Size Limit Retention Policy : size-limit : 500 mb : - : -</screen>
+
+ <para>Use the <command>dsconfig get-log-publisher-prop</command> command to
+ examine the policies that apply to a particular logger.</para>
+
+ <screen>$ dsconfig
+ get-log-publisher-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Access Logger"
+ --property retention-policy
+ --property rotation-policy
+Property : Value(s)
+-----------------:-------------------------------------------------------------
+retention-policy : File Count Retention Policy
+rotation-policy : 24 Hours Time Limit Rotation Policy, Size Limit Rotation
+ : Policy</screen>
+
+ <para>In other words, by default OpenDJ keeps 10 access log files, rotating
+ the access log each day, or when the log size reaches 100 MB.</para>
+
+ <para>The <command>dsconfig</command> command offers a number of subcommands
+ for creating and deleting log rotation and retention policies, and for
+ setting policy properties. You can update which policies apply to a logger
+ by using the <command>dsconfig set-log-publisher-prop</command>
+ command.</para>
+ </section>
+
+ <section xml:id="log-filtering">
+ <title>Log Filtering</title>
+ <indexterm>
+ <primary>Logs</primary>
+ <secondary>Filtering</secondary>
+ </indexterm>
+
+ <para>Each time a client application sends a request to OpenDJ, the server
+ writes to its access log. As shown above, a simple search operation results
+ in five messages written to the access log. This volume of logging gives you
+ the information to analyze overall access patterns, or to audit access when
+ you do not know in advance what you are looking for.</para>
+
+ <para>Yet when you do know what you are looking for, log filtering
+ lets you limit what the server logs, and focus on what you want to see.
+ You define the filter criteria, and also set the filtering policy.</para>
+
+ <para>You can filter both access and also audit logs.</para>
+
+ <itemizedlist>
+ <para>Log filtering lets you define rules based these criteria.</para>
+ <listitem>
+ <para>Client IP address, bind DN, group membership</para>
+ </listitem>
+ <listitem>
+ <para>Port number</para>
+ </listitem>
+ <listitem>
+ <para>Protocol used (such as LDAP, LDAPS, JMX)</para>
+ </listitem>
+ <listitem>
+ <para>Response times</para>
+ </listitem>
+ <listitem>
+ <para>Result codes (only log error results, for example)</para>
+ </listitem>
+ <listitem>
+ <para>Search response criteria (number of entries returned, whether the
+ search was indexed)</para>
+ </listitem>
+ <listitem>
+ <para>Target DN</para>
+ </listitem>
+ <listitem>
+ <para>Type of operation (connect, bind, add, delete, modify, rename,
+ search, etc.)</para>
+ </listitem>
+ </itemizedlist>
+ <para>The filtering policy in the log publisher configuration specifies
+ whether to include or exclude log messages that match the criteria you
+ define. OpenDJ does not filter logs until you update the log publisher
+ configuration.</para>
+
+ <example xml:id="log-filtering-exclude-control-panel">
+ <title>Example: Exclude Control Panel-Related Messages</title>
+
+ <para>A common development troubleshooting technique consists of sending
+ client requests while tailing the access log:</para>
+ <screen>$ tail -f /path/to/opendj/logs/access</screen>
+ <para>Trouble is, when OpenDJ Control Panel is running, or when you are
+ also adapting your configuration using the <command>dsconfig</command>
+ command, OpenDJ writes access log messages related to administration.
+ These might prevent you from noticing the messages that interest
+ you.</para>
+
+ <para>This example demonstrates how to filter out access log messages
+ due to administrative connections over LDAPS on ports 1636 and 4444.</para>
+
+ <para>Create access log filtering criteria rules.</para>
+ <screen>$ dsconfig
+ create-access-log-filtering-criteria
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Access Logger"
+ --criteria-name "Exclude LDAPS on 1636 and 4444"
+ --type generic
+ --set connection-port-equal-to:1636
+ --set connection-port-equal-to:4444
+ --set connection-protocol-equal-to:ldaps
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Activate filtering to exclude messages from the default access log
+ according to the criteria you specified.</para>
+ <screen>$ dsconfig
+ set-log-publisher-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Access Logger"
+ --set filtering-policy:exclusive
+ --trustAll
+ --no-prompt</screen>
+
+ <para>At this point, OpenDJ filters out connections over LDAPS to ports
+ 1636 and 4444. While performing operations in OpenDJ Control Panel, if
+ you perform a simple <command>ldapsearch --port 1389 --baseDN
+ dc=example,dc=com uid=bjensen cn</command>, then all you see in the access
+ log is the effect of the <command>ldapsearch</command> command.</para>
+ <screen>$ tail -f /path/to/opendj/logs/access
+[19/Oct/2011:16:37:16 +0200] CONNECT conn=8 from=127.0.0.1:54165
+ to=127.0.0.1:1389 protocol=LDAP
+[19/Oct/2011:16:37:16 +0200] SEARCH REQ conn=8 op=0 msgID=1
+ base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="cn"
+[19/Oct/2011:16:37:16 +0200] SEARCH RES conn=8 op=0 msgID=1 result=0 nentries=1
+ etime=14
+[19/Oct/2011:16:37:16 +0200] UNBIND REQ conn=8 op=1 msgID=2
+[19/Oct/2011:16:37:16 +0200] DISCONNECT conn=8 reason="Client Unbind"</screen>
+ </example>
+
+ <para>In addition to the filtering policy, you can also adjust how OpenDJ
+ writes log messages. By default, OpenDJ writes one log message for a
+ request, and another for a response. You can set the log publisher
+ property <literal>log-format</literal> to <literal>combined</literal>
+ to have OpenDJ write a single message per operation. This can be helpful,
+ for example, when evaluating response times. In addition, you can change
+ the log message time stamps with <literal>log-record-time-format</literal>,
+ and specify whether to log LDAP control OIDs for operations by setting
+ <literal>log-control-oids</literal> to <literal>true</literal>.</para>
+ </section>
+ </section>
+
+ <section xml:id="alert-notifications">
+ <title>Alert Notifications</title>
+ <indexterm><primary>Alerts</primary></indexterm>
+
+ <para>OpenDJ can send alerts to provide notifications of significant server
+ events. Yet alert notifications are not enabled by default. You can use
+ the <command>dsconfig</command> command to enable alert notifications.</para>
+
+ <screen>$ dsconfig
+ set-alert-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "JMX Alert Handler"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+
+ <para>OpenDJ can also send mail over SMTP instead of JMX notifications.
+ Before you set up the SMTP-based alert handler, you must identify an SMTP
+ server to which OpenDJ sends messages.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set smtp-server:smtp.example.com
+ --trustAll
+ --no-prompt
+$ dsconfig
+ create-alert-handler
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "SMTP Alert Handler"
+ --type smtp
+ --set enabled:true
+ --set message-subject:"OpenDJ Alert, Type: %%alert-type%%, ID: %%alert-id%%"
+ --set message-body:"%%alert-message%%"
+ --set recipient-address:kvaughan@example.com
+ --set sender-address:opendj@example.com
+ --trustAll
+ --no-prompt</screen>
+
+ <variablelist xml:id="alert-types">
+ <title>Alert Types</title>
+
+ <para>OpenDJ directory server uses the following types when sending
+ alerts. For alert types that indicate server problems, check
+ <filename>OpenDJ/logs/errors</filename> for details.</para>
+
+ <varlistentry>
+ <term><literal>org.opends.server.AccessControlDisabled</literal></term>
+ <listitem>
+ <para>The access control handler has been disabled.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.AccessControlEnabled</literal></term>
+ <listitem>
+ <para>The access control handler has been enabled.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.authentiation.dseecompat.ACIParseFailed</literal></term>
+ <listitem>
+ <para>The dseecompat access control subsystem failed to correctly parse
+ one or more ACI rules when the server first started.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.BackendRunRecovery</literal></term>
+ <listitem>
+ <para>The JE backend has thrown a <literal>RunRecoveryException</literal>.
+ The directory server needs to be restarted.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotCopySchemaFiles</literal></term>
+ <listitem>
+ <para>A problem has occurred while attempting to create copies of the
+ existing schema configuration files before making a schema update, and the
+ schema configuration has been left in a potentially inconsistent
+ state.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotRenameCurrentTaskFile</literal></term>
+ <listitem>
+ <para>The directory server is unable to rename the current tasks backing
+ file in the process of trying to write an updated version.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotRenameNewTaskFile</literal></term>
+ <listitem>
+ <para>The directory server is unable to rename the new tasks backing file
+ into place.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotScheduleRecurringIteration</literal></term>
+ <listitem>
+ <para>The directory server is unable to schedule an iteration of a
+ recurring task.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotWriteConfig</literal></term>
+ <listitem>
+ <para>The directory server is unable to write its updated configuration
+ for some reason and therefore the server may not exhibit the new
+ configuration if it is restarted.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotWriteNewSchemaFiles</literal></term>
+ <listitem>
+ <para>A problem has occurred while attempting to write new versions of the
+ server schema configuration files, and the schema configuration has been
+ left in a potentially inconsistent state.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.CannotWriteTaskFile</literal></term>
+ <listitem>
+ <para>The directory server is unable to write an updated tasks backing
+ file for some reason.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.DirectoryServerShutdown</literal></term>
+ <listitem>
+ <para>The directory server has begun the process of shutting down.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.DirectoryServerStarted</literal></term>
+ <listitem>
+ <para>The directory server has completed its startup process.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.DiskFull</literal></term>
+ <listitem>
+ <para>Free disk space has reached the full threshold.</para>
+ <para>Default is 20 MB.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.DiskSpaceLow</literal></term>
+ <listitem>
+ <para>Free disk space has reached the low threshold.</para>
+ <para>Default is 100 MB.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.EnteringLockdownMode</literal></term>
+ <listitem>
+ <para>The directory server is entering lockdown mode, in which only root
+ users are allowed to perform operations and only over the loopback
+ address.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.LDAPHandlerDisabledByConsecutiveFailures</literal></term>
+ <listitem>
+ <para>Consecutive failures have occurred in the LDAP connection handler
+ and have caused it to become disabled.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.LDAPHandlerUncaughtError</literal></term>
+ <listitem>
+ <para>Uncaught errors in the LDAP connection handler that have caused it
+ to become disabled.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.LDIFBackendCannotWriteUpdate</literal></term>
+ <listitem>
+ <para>An LDIF backend was unable to store an updated copy of the LDIF file
+ after processing a write operation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.LDIFConnectionHandlerIOError</literal></term>
+ <listitem>
+ <para>The LDIF connection handler encountered an I/O error that prevented
+ it from completing its processing.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.LDIFConnectionHandlerParseError</literal></term>
+ <listitem>
+ <para>The LDIF connection handler encountered an unrecoverable error while
+ attempting to parse an LDIF file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.LeavingLockdownMode</literal></term>
+ <listitem>
+ <para>The directory server is leaving lockdown mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.ManualConfigEditHandled</literal></term>
+ <listitem>
+ <para>The directory server detects that its configuration has been
+ manually edited with the server online and those changes were overwritten
+ by another change made through the server. The manually-edited
+ configuration will be copied to another location.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.ManualConfigEditLost</literal></term>
+ <listitem>
+ <para>The directory server detects that its configuration has been
+ manually edited with the server online and those changes were overwritten
+ by another change made through the server. The manually-edited
+ configuration could not be preserved due to an unexpected error.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.replication.UnresolvedConflict</literal></term>
+ <listitem>
+ <para>Multimaster replication cannot resolve a conflict
+ automatically.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.UncaughtException</literal></term>
+ <listitem>
+ <para>A directory server thread has encountered an uncaught exception that
+ caused that thread to terminate abnormally. The impact that this problem
+ has on the server depends on which thread was impacted and the nature
+ of the exception.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.UniqueAttributeSynchronizationConflict</literal></term>
+ <listitem>
+ <para>A unique attribute conflict has been detected during synchronization
+ processing.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.opends.server.UniqueAttributeSynchronizationError</literal></term>
+ <listitem>
+ <para>An error occurred while attempting to perform unique attribute
+ conflict detection during synchronization processing.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-mv-servers.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-mv-servers.xml
new file mode 100644
index 0000000..e97e9e2
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-mv-servers.xml
@@ -0,0 +1,281 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-mv-servers'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Moving Servers</title>
+ <indexterm><primary>Moving servers</primary></indexterm>
+
+ <para>When you change where OpenDJ is deployed, you must take host names,
+ port numbers, and certificates into account. The changes can also affect
+ your replication configuration. This chapter shows what to do when moving
+ a server.</para>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Moving servers</secondary>
+ </indexterm>
+
+ <section xml:id="moving-servers-overview">
+ <title>Overview</title>
+
+ <para>From time to time you might change server hardware, file system layout,
+ or host names. At those times you move the services running on the system.
+ You can move OpenDJ data between servers and operating systems. Most of the
+ configuration is also portable.</para>
+
+ <indexterm><primary>Certificates</primary></indexterm>
+ <itemizedlist>
+ <para>Two aspects of the configuration are not portable.</para>
+ <listitem>
+ <para>Server certificates contain the host name of the system. Even if you
+ did not set up secure communications when you installed the server, the
+ server still has a certificate used for secure communications on the
+ administrative port.</para>
+ <para>To resolve the issue with server certificates, you can change the
+ server certificates during the move as described in this chapter.</para>
+ </listitem>
+ <listitem>
+ <para>Replication configuration includes the host name and administrative
+ port numbers.</para>
+ <para>You can work around the issue with replication configuration by
+ disabling replication for the server before the move, and then enabling and
+ initializing replication again after the move.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="before-moving-servers">
+ <title>Before You Move</title>
+
+ <para>Take a moment to determine whether you find it quicker and easier to
+ move your server, or instead to recreate a copy. To recreate a copy, install
+ a new server, set up the new server configuration to match the old, and then
+ copy only the data from the old server to the new server, initializing
+ replication from existing data, or even from LDIF if your database is not
+ too large.</para>
+
+ <para>After you decide to move a server, start by taking it out of
+ service. Taking it out of service means directing client applications
+ elsewhere, and then preventing updates from client applications, and finally
+ disabling replication, too. Directing client applications elsewhere depends
+ on your network configuration and possibly on your client application
+ configuration. The other two steps can be completed with the
+ <command>dsconfig</command> and <command>dsreplication</command>
+ commands.</para>
+
+ <procedure xml:id="remove-server">
+ <title>To Take the Server Out of Service</title>
+
+ <step>
+ <para>Direct client applications to other servers.</para>
+ <para>How you do this depends on your network and client application
+ configurations.</para>
+ </step>
+ <step>
+ <para>Prevent the server from accepting updates from client
+ applications.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set writability-mode:internal-only
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Disable replication for the server.</para>
+ <screen>$ dsreplication
+ disable
+ --disableAll
+ --port 4444
+ --hostname opendj2.example.com
+ --adminUID admin
+ --adminPassword password
+ --trustAll
+ --no-prompt
+Establishing connections ..... Done.
+Disabling replication on base DN dc=example,dc=com of server
+ opendj2.example.com:4444 ..... Done.
+Disabling replication on base DN cn=admin data of server
+ opendj2.example.com:4444 ..... Done.
+Disabling replication on base DN cn=schema of server
+ opendj2.example.com:4444 ..... Done.
+Disabling replication port 8989 of server opendj2.example.com:4444 ..... Done.
+Removing registration information ..... Done.
+Removing truststore information ..... Done.
+
+See
+/var/.../opends-replication-3173475478874782719.log
+for a detailed log of this operation.</screen>
+ </step>
+ <step>
+ <para>With the server no longer receiving traffic or accepting updates
+ from clients, and no longer replicating to other servers, you can shut it
+ down in preparation for the move.</para>
+ <screen>$ stop-ds
+Stopping Server...
+
+... msg=The Directory Server is now stopped</screen>
+ </step>
+ <step performance="optional">
+ <para>You might also choose to remove extra log files from the server
+ <filename>logs/</filename> directory before moving the server.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="moving-servers">
+ <title>Moving a Server</title>
+
+ <para>Now that you have decided to move your server, and prepared for the
+ move, you must not only move the files but also fix the configuration and
+ the server certificates, and then enable replication.</para>
+
+ <procedure xml:id="mv-one-server">
+ <title>To Move the Server</title>
+
+ <step>
+ <para>Move the contents of the server installation directory to the new
+ location.</para>
+ </step>
+ <step performance="optional">
+ <para>If you must change port numbers, edit the port numbers in
+ <filename>config/config.ldif</filename>, carefully avoiding changing
+ any whitespace or other lines in the file.</para>
+ </step>
+ <step>
+ <para>Change server certificates as described in the chapter on
+ <link xlink:href="admin-guide#chap-change-certs"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Changing
+ Server Certificates</citetitle></link>.</para>
+ </step>
+ <step>
+ <para>Start the server.</para>
+ <screen>$ start-ds
+... The Directory Server has started successfully</screen>
+ </step>
+ <step>
+ <para>Enable and initialize replication.</para>
+ <screen>$ dsreplication
+ enable
+ --adminUID admin
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ --host1 opendj.example.com
+ --port1 4444
+ --bindDN1 "cn=Directory Manager"
+ --bindPassword1 password
+ --replicationPort1 8989
+ --host2 opendj2.example.com
+ --port2 4444
+ --bindDN2 "cn=Directory Manager"
+ --bindPassword2 password
+ --replicationPort2 8989
+ --trustAll
+ --no-prompt
+
+Establishing connections ..... Done.
+Checking registration information ..... Done.
+Configuring Replication port on server opendj.example.com:4444 ..... Done.
+Updating remote references on server opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj2.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj2.example.com:4444 ..... Done.
+Initializing registration information on server opendj.example.com:4444 with
+ the contents of server opendj2.example.com:4444 ..... Done.
+Initializing schema on server opendj2.example.com:4444 with the contents of
+ server opendj.example.com:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to work
+ you must initialize the contents of the base DN's that are being replicated
+ (use dsreplication initialize to do so).
+
+See /tmp/opends-replication-1476402020764482023.log for a detailed log of this
+operation.
+
+$ dsreplication
+ pre-external-initialization
+ --adminUID admin
+ --bindPassword password
+ --port 4444
+ --baseDN dc=example,dc=com
+ --trustAll
+ --no-prompt
+
+Preparing base DN dc=example,dc=com to be initialized externally ..... Done.
+
+Now you can proceed to the initialization of the contents of the base DN's on
+ all the replicated servers. You can use the command import-ldif or the binary
+ copy to do so. You must use the same LDIF file or binary copy on each server.
+
+When the initialization is completed you must use the subcommand
+ 'post-external-initialization' for replication to work with the new base DN's
+ contents.
+$ dsreplication
+ post-external-initialization
+ --adminUID admin
+ --bindPassword password
+ --port 4444
+ --baseDN dc=example,dc=com
+ --trustAll
+ --no-prompt
+
+Updating replication information on base DN dc=example,dc=com ..... Done.
+
+Post initialization procedure completed successfully.</screen>
+ </step>
+ <step>
+ <para>Accept updates from client applications.</para>
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set writability-mode:enabled
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Direct client applications to the server.</para>
+ </step>
+ </procedure>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-privileges-acis.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-privileges-acis.xml
new file mode 100644
index 0000000..168b7c5
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-privileges-acis.xml
@@ -0,0 +1,1438 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-privileges-acis'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Configuring Privileges & Access Control</title>
+
+ <para>OpenDJ supports two mechanisms to protect access to the directory,
+ <firstterm>access control instructions</firstterm> and
+ <firstterm>privileges</firstterm>.</para>
+
+ <para>Access control instructions apply to directory data, providing
+ fine-grained control over what a user or group member is authorized to do in
+ terms of LDAP operations. Most access control instructions specify scopes
+ (targets) to which they apply such that an administrative user who has all
+ access to <literal>dc=example,dc=com</literal> need not have any access to
+ <literal>dc=example,dc=org</literal>.</para>
+
+ <para>Privileges control the administrative tasks that users can perform,
+ such as bypassing the access control mechanism, performing backup and restore
+ operations, making changes to the configuration, and so forth. Privileges are
+ implemented independently from access control. By default, privileges restrict
+ administrative access to directory root users, though any user can be assigned
+ a privilege. Privileges apply to a directory server, and do not have a
+ scope.</para>
+
+ <para>Some operations require both privileges and also access control
+ instructions. For example, in order to reset user's passwords, an administrator
+ needs both the <literal>password-reset</literal> privilege and also access
+ control to write <literal>userPassword</literal> values on the user entries.
+ By combining an access control instruction with a privilege, you can
+ effectively restrict the scope of that privilege to a particular branch of
+ the Directory Information Tree.</para>
+
+ <para>This chapter covers both access control instructions and privileges,
+ demonstrating how to configure both.</para>
+
+ <section xml:id="about-acis">
+ <title>About Access Control Instructions</title>
+ <indexterm><primary>Access control</primary></indexterm>
+
+ <para>OpenDJ directory server access control instructions (ACIs) exist as
+ operational <literal>aci</literal> attribute values on directory entries, and
+ as global ACIs stored in the configuration. ACIs apply to a scope defined in
+ the instruction, and set permissions that depend on what operation is
+ requested, who requested the operation, and how the client connected to the
+ server.</para>
+
+ <para>For example, the ACIs on the following entry allow anonymous read
+ access to all attributes except passwords, and allow read-write access
+ for directory administrators under <literal>dc=example,dc=com</literal>.</para>
+
+ <programlisting language="ldif">dn: dc=example,dc=com
+objectClass: domain
+objectClass: top
+dc: example
+aci: (target ="ldap:///dc=example,dc=com")(targetattr !=
+ "userPassword")(version 3.0;acl "Anonymous read-search access";
+ allow (read, search, compare)(userdn = "ldap:///anyone");)
+aci: (target="ldap:///dc=example,dc=com") (targetattr =
+ "*")(version 3.0; acl "allow all Admin group"; allow(all) groupdn =
+ "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
+ </programlisting>
+
+ <para>OpenDJ directory server's default behavior is that no access is allowed
+ unless it is specifically granted by an access control instruction. In
+ addition privileges assigned to certain users such as <literal>cn=Directory
+ Manager</literal> allow them to bypass access control checks.</para>
+
+ <para>OpenDJ directory server provides several global ACIs out of the box to
+ facilitate evaluation while maintaining a reasonable security policy. By
+ default users are allow to read the root DSE, to read the schema, to use
+ certain controls and extended operations, to modify their own entries, to
+ bind, and so forth. Global ACIs are defined on the access control handler,
+ and apply to the entire directory server. You must adjust the default global
+ ACIs to match the security policies for your organization, for example to
+ restrict anonymous access.</para>
+
+ <para>ACI attribute values use a specific language described in this section.
+ Although ACI attribute values can become difficult to read in LDIF, the
+ basic syntax is simple.</para>
+
+ <literallayout class="monospaced"><replaceable
+ >targets</replaceable>(version 3.0;acl "<replaceable
+ >name</replaceable>";<replaceable>permissions</replaceable> <replaceable
+ >subjects</replaceable>;)</literallayout>
+
+ <para>The following list briefly explains the variables in the syntax above.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable>targets</replaceable></term>
+ <listitem>
+ <para>The <replaceable>targets</replaceable> specifies entries, attributes,
+ controls, and extended operations to which the ACI applies.</para>
+ <para>To include multiple <replaceable>targets</replaceable>, enclose
+ each individual target in parentheses, (). When you specify multiple
+ targets, all targets must match for the ACI to apply
+ (<literal>AND</literal>).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>name</replaceable></term>
+ <listitem>
+ <para>Supplies a human-readable description of what the ACI does.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>permissions</replaceable></term>
+ <listitem>
+ <para>Defines which actions to allow, and which to deny. Paired with
+ <replaceable>subjects</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>subjects</replaceable></term>
+ <listitem>
+ <para>Identify clients to which the ACI applies depending on
+ who connected, and when, where, and how they connected. Paired with
+ <replaceable>permissions</replaceable>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Separate multiple pairs of <replaceable>permissions</replaceable>
+ <replaceable>subjects</replaceable> definitions with semicolons, ;. When you
+ specify multiple permissions-subjects pairs, at least one must match
+ (<literal>OR</literal>).</para>
+
+ <section xml:id="aci-targets">
+ <title>ACI Targets</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Targets</secondary>
+ </indexterm>
+
+ <para>The seven types of ACI targets identify the objects to which the ACI
+ applies.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>(target = "ldap:///<replaceable>DN</replaceable>")</literal></term>
+ <term><literal>(target != "ldap:///<replaceable>DN</replaceable>")</literal></term>
+ <listitem>
+ <para>Sets the scope to the entry with distinguished name
+ <replaceable>DN</replaceable>, and to child entries.</para>
+ <para>You can use asterisks, *, to replace attribute types, attribute
+ values, and entire DN components. In other words, the following
+ specification targets both
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> and also
+ <literal>cn=Frank Zappa,ou=Musicians,dc=example,dc=com</literal>.</para>
+ <programlisting language="aci">(target = "ldap:///*=*,*,dc=example,dc=com")</programlisting>
+ <para>The <replaceable>DN</replaceable> must be in the subtree of the
+ entry on which the ACI is defined.</para>
+ <para>If you do not specify <literal>target</literal>, then the entry
+ holding this ACI will be affected. If <literal>targetscope</literal> is
+ also omitted, then this entry and all subordinates will be affected.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>(targetattr = "<replaceable>attr-list</replaceable>")</literal></term>
+ <term><literal>(targetattr != "<replaceable>attr-list</replaceable>")</literal></term>
+ <listitem>
+ <para>Replace <replaceable>attr-list</replaceable> with a list of
+ attribute type names, such as <literal>userPassword</literal>, separating
+ multiple attribute type names with ||.</para>
+ <para>This specification affects the entry where the ACI is located, or
+ the entries specified by other targets in the ACI.</para>
+ <para>You can use an asterisk, *, to specify all non-operational
+ attributes, although you will see better performance when explicitly
+ including or excluding attribute types needed. You can use a plus, +, to
+ specify all operational attributes.</para>
+ <para>If you do not include this target specification, then by default
+ no attributes are affected by the ACI.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>(targetfilter = "<replaceable>ldap-filter</replaceable>")</literal></term>
+ <term><literal>(targetfilter != "<replaceable>ldap-filter</replaceable>")</literal></term>
+ <listitem>
+ <para>Sets the scope to match the <replaceable>ldap-filter</replaceable>
+ dynamically, as in an LDAP search. The
+ <replaceable>ldap-filter</replaceable> can be any valid LDAP filter.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>(targattrfilters = "<replaceable>expression</replaceable>")</literal></term>
+ <term><literal>(targattrfilters != "<replaceable>expression</replaceable>")</literal></term>
+ <listitem>
+ <para>Use this target specification when managing changes made to
+ particular attributes.</para>
+ <para>Here <replaceable>expression</replaceable> takes one of the
+ following forms. Separate expressions with semicolons, ;.</para>
+ <literallayout class="monospaced"><replaceable
+ >op</replaceable>=<replaceable>attr1</replaceable>:<replaceable
+ >filter1</replaceable>[&& <replaceable
+ >attr2</replaceable>:<replaceable>filter2</replaceable> …][;<replaceable
+ >op</replaceable>=<replaceable>attr3</replaceable>:<replaceable
+ >filter3</replaceable>[&& <replaceable
+ >attr4</replaceable>:<replaceable>filter4</replaceable> …] …]</literallayout>
+ <para>Here <replaceable>op</replaceable> can be either
+ <literal>add</literal> for operations creating attributes, or
+ <literal>delete</literal> for operations removing them.
+ Replace <replaceable>attr</replaceable> with an attribute type.
+ Replace <replaceable>filter</replaceable> with an LDAP filter that
+ corresponds to the <replaceable>attr</replaceable> attribute type.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>(targetscope = "base|onelevel|subtree|subordinate")</literal></term>
+ <listitem>
+ <para>Here <literal>base</literal> refers to the entry where the ACI is
+ defined, <literal>onelevel</literal> to immediate children,
+ <literal>subtree</literal> to the base entry and all children, and
+ <literal>subordinate</literal> to all children only.</para>
+ <para>If you do not specify <literal>targetscope</literal>, then the
+ default is <literal>subtree</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>(targetcontrol = "<replaceable>OID</replaceable>")</literal></term>
+ <term><literal>(targetcontrol != "<replaceable>OID</replaceable>")</literal></term>
+ <listitem>
+ <para>Replace <replaceable>OID</replaceable> with the object identifier
+ for the LDAP control to target. Separate multiple OIDs with ||.</para>
+ <para>This target cannot be restricted to a specific subtree by combining
+ it with another target.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>(extop = "<replaceable>OID</replaceable>")</literal></term>
+ <term><literal>(extop != "<replaceable>OID</replaceable>")</literal></term>
+ <listitem>
+ <para>Replace <replaceable>OID</replaceable> with the object identifier
+ for the extended operation to target. Separate multiple OIDs with ||.</para>
+ <para>This target cannot be restricted to a specific subtree by combining
+ it with another target.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="aci-permissions">
+ <title>ACI Permissions</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Permissions</secondary>
+ </indexterm>
+
+ <para>ACI permission definitions take one of the following forms.</para>
+
+ <literallayout class="monospaced">allow(<replaceable
+ >action</replaceable>[, <replaceable>action</replaceable> …])</literallayout>
+ <literallayout class="monospaced">deny(<replaceable
+ >action</replaceable>[, <replaceable>action</replaceable> …])</literallayout>
+
+ <tip>
+ <para>Although <literal>deny</literal> is supported, avoid restricting
+ permissions by using <literal>deny</literal>. Instead, explicitly
+ <literal>allow</literal> access only where needed. What looks harmless and
+ simple in your lab examples can grow difficult to maintain in a real-world
+ deployment with nested ACIs.</para>
+ </tip>
+
+ <para>Replace <replaceable>action</replaceable> with one of the following.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>add</literal></term>
+ <listitem>
+ <para>Entry creation, as for an LDAP add operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>all</literal></term>
+ <listitem>
+ <para>All permissions, except <literal>export</literal>,
+ <literal>import</literal>, <literal>proxy</literal></para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>compare</literal></term>
+ <listitem>
+ <para>Attribute value comparison, as for an LDAP compare operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>delete</literal></term>
+ <listitem>
+ <para>Entry deletion, as for an LDAP delete operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>export</literal></term>
+ <listitem>
+ <para>Entry export during a modify DN operation.</para>
+ <para>Despite the name, this action is unrelated to LDIF export
+ operations.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>import</literal></term>
+ <listitem>
+ <para>Entry import during a modify DN operation.</para>
+ <para>Despite the name, this action is unrelated to LDIF import
+ operations.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>proxy</literal></term>
+ <listitem>
+ <para>Access the ACI target using the rights of another user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>read</literal></term>
+ <listitem>
+ <para>Read entries and attributes</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>search</literal></term>
+ <listitem>
+ <para>Search the ACI targets. Needs to be combine with
+ <literal>read</literal> in order to read the search results.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>selfwrite</literal></term>
+ <listitem>
+ <para>Add or delete own DN from a group</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>write</literal></term>
+ <listitem>
+ <para>Modify attributes on ACI target entries</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section xml:id="aci-subjects">
+ <title>ACI Subjects</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Subjects</secondary>
+ </indexterm>
+
+ <para>ACI subjects match characteristics of the client connection to the
+ server. Use subjects to restrict whether the ACI applies depending on who
+ connected, and when, where, and how they connected.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>authmethod = "none|simple|ssl|sasl <replaceable
+ >mech</replaceable>"</literal></term>
+ <term><literal>authmethod != "none|simple|ssl|sasl <replaceable
+ >mech</replaceable>"</literal></term>
+ <listitem>
+ <para>Here you use <literal>none</literal> to mean do not check,
+ <literal>simple</literal> for simple authentication,
+ <literal>ssl</literal> for certificate-based authentication over LDAPS,
+ <literal>sasl <replaceable>mech</replaceable></literal> for
+ SASL where <replaceable>mech</replaceable> is DIGEST-MD5, EXTERNAL, or
+ GSSAPI.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>dayofweek = "<replaceable>day</replaceable>[, <replaceable
+ >day</replaceable> …]"</literal></term>
+ <term><literal>dayofweek != "<replaceable>day</replaceable>[, <replaceable
+ >day</replaceable> …]"</literal></term>
+ <listitem>
+ <para>Replace <replaceable>day</replaceable> with one of
+ <literal>sun</literal>, <literal>mon</literal>, <literal>tue</literal>,
+ <literal>wed</literal>, <literal>thu</literal>, <literal>fri</literal>,
+ <literal>sat</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>dns = "<replaceable>hostname</replaceable>"</literal></term>
+ <term><literal>dns != "<replaceable>hostname</replaceable>"</literal></term>
+ <listitem>
+ <para>You can use asterisks, *, to replace name components, such as
+ <literal>dns = "*.myCompany.com"</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>groupdn = "ldap:///<replaceable
+ >DN</replaceable>[|| ldap:///<replaceable>DN</replaceable> …]"</literal></term>
+ <term><literal>groupdn != "ldap:///<replaceable
+ >DN</replaceable>[|| ldap:///<replaceable>DN</replaceable> …]"</literal></term>
+ <listitem>
+ <para>Replace <replaceable>DN</replaceable> with the distinguished name
+ of a group to permit or restrict access for members.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ip = "<replaceable>addresses</replaceable>"</literal></term>
+ <term><literal>ip != "<replaceable>addresses</replaceable>"</literal></term>
+ <listitem>
+ <para>Here <replaceable>addresses</replaceable> can be specified for
+ IPv4 or IPv6. IPv6 addresses are specified in brackets as
+ <literal>ldap://[<replaceable>address</replaceable>]/<replaceable
+ >subnet-prefix</replaceable></literal>
+ where /<replaceable>subnet-prefix</replaceable> is optional.
+ You can specify individual IPv4 addresses, addresses with asterisks (*) to
+ replace subnets and host numbers, CIDR notation, and forms such as
+ <literal>192.168.0.*+255.255.255.0</literal> to specify subnet masks.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ssf = "<replaceable>strength</replaceable>"</literal></term>
+ <term><literal>ssf != "<replaceable>strength</replaceable>"</literal></term>
+ <term><literal>ssf > "<replaceable>strength</replaceable>"</literal></term>
+ <term><literal>ssf >= "<replaceable>strength</replaceable>"</literal></term>
+ <term><literal>ssf < "<replaceable>strength</replaceable>"</literal></term>
+ <term><literal>ssf <= "<replaceable>strength</replaceable>"</literal></term>
+ <listitem>
+ <para>Here the security strength factor pertains to the cipher key
+ strength for connections using DIGEST-MD5, GSSAPI, SSL, or TLS. For
+ example, to require that the connection must have at least 128 bits
+ of encryption, specify <literal>ssf >= 128</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>timeofday = "<replaceable>hhmm</replaceable>"</literal></term>
+ <term><literal>timeofday != "<replaceable>hhmm</replaceable>"</literal></term>
+ <term><literal>timeofday > "<replaceable>hhmm</replaceable>"</literal></term>
+ <term><literal>timeofday >= "<replaceable>hhmm</replaceable>"</literal></term>
+ <term><literal>timeofday < "<replaceable>hhmm</replaceable>"</literal></term>
+ <term><literal>timeofday <= "<replaceable>hhmm</replaceable>"</literal></term>
+ <listitem>
+ <para>Here <replaceable>hhmm</replaceable> is expressed as on a 24-hour
+ clock. For example, 1:15 PM is written <literal>1315</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>userattr = "<replaceable>attr</replaceable>#<replaceable
+ >value</replaceable>"</literal></term>
+ <term><literal>userattr != "<replaceable>attr</replaceable>#<replaceable
+ >value</replaceable>"</literal></term>
+ <term><literal>userattr = <replaceable
+ >ldap-url</replaceable>#LDAPURL"</literal></term>
+ <term><literal>userattr != <replaceable
+ >ldap-url</replaceable>#LDAPURL"</literal></term>
+ <term><literal>userattr = "[parent[<replaceable
+ >child-level</replaceable>]. ]<replaceable>attr</replaceable
+ >#GROUPDN|USERDN"</literal></term>
+ <term><literal>userattr != "[parent[<replaceable
+ >child-level</replaceable>]. ]<replaceable>attr</replaceable
+ >#GROUPDN|USERDN"</literal></term>
+ <listitem>
+ <para>The <literal>userattr</literal> subject specifies an attribute
+ that must match on both the bind entry and the target of the ACI.</para>
+ <para>To match when the attribute on the bind DN entry corresponds
+ directly to the attribute on the target entry, replace
+ <replaceable>attr</replaceable> with the attribute type, and
+ <replaceable>value</replaceable> with the attribute value.</para>
+ <para>To match when the target entry is identified by an LDAP URL, and
+ the bind DN is in the subtree of the DN of the LDAP URL, use
+ <replaceable>ldap-url</replaceable>#LDAPURL.</para>
+ <para>To match when the bind DN corresponds to a member of the group
+ identified by the <replaceable>attr</replaceable> value on the target
+ entry, use <replaceable>attr</replaceable>#GROUPDN.</para>
+ <para>To match when the bind DN corresponds to the
+ <replaceable>attr</replaceable> value on the target entry, use
+ <replaceable>attr</replaceable>#USERDN.</para>
+ <para>The optional inheritance specification,
+ <literal>parent[<replaceable>child-level</replaceable>].</literal>, lets
+ you specify how many levels below the target entry inherit the ACI.
+ Here <replaceable>child-level</replaceable> is a number from 0 to 9, with
+ 0 indicating the target entry only. Separate multiple
+ <replaceable>child-level</replaceable> digits with commas (,).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>userdn = "<replaceable>ldap-url++</replaceable>[|| <replaceable
+ >ldap-url++</replaceable> …]"</literal></term>
+ <term><literal>userdn != "<replaceable>ldap-url++</replaceable>[|| <replaceable
+ >ldap-url++</replaceable> …]"</literal></term>
+ <listitem>
+ <para>To match the bind DN, replace <replaceable>ldap-url++</replaceable>
+ with either a valid LDAP URL such as
+ <literal>ldap:///uid=bjensen,ou=People,dc=example,dc=com</literal>,
+ <literal>ldap:///dc=example,dc=com??sub?(uid=bjensen)</literal>,
+ or a special LDAP URL-like keyword from the following list.</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>ldap:///all</literal></term>
+ <listitem>
+ <para>Match authenticated users.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap:///anyone</literal></term>
+ <listitem>
+ <para>Match anonymous and authenticated users.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap:///parent</literal></term>
+ <listitem>
+ <para>Match when the bind DN is a parent of the ACI target.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldap:///self</literal></term>
+ <listitem>
+ <para>Match when the bind DN entry corresponds to ACI target.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="aci-evaluation">
+ <title>How ACI is Evaluated</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Evaluation</secondary>
+ </indexterm>
+
+ <para>Understanding how OpenDJ evaluates the aci values is critical when
+ implementing an access control policy. The rules the server follows are
+ simple.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>To determine if an operation is allowed or denied, the OpenDJ server
+ looks in the directory for the target of the operation. It collects any aci
+ values from that entry, and then walks up the directory tree to the suffix,
+ collecting all aci values en route. Global aci values are then collected.</para>
+ </listitem>
+ <listitem>
+ <para>It then separates the aci values into two lists; one list contains
+ all the aci values that matches the target and denies the required access,
+ and the other list contains all the aci values that matches the target and
+ allows the required access.</para>
+ </listitem>
+ <listitem>
+ <para>If the deny list contains any aci values after this procedure, access
+ will be immediately denied.</para>
+ </listitem>
+ <listitem>
+ <para>If the deny list is empty, then the allow list is processed. If the
+ allow list contains any aci values, access will be allowed.</para>
+ </listitem>
+ <listitem>
+ <para>If both lists are empty, access will be denied.</para>
+ </listitem>
+ </orderedlist>
+
+ <note>
+ <para>Some operations require multiple permissions and involve multiple
+ targets. Evaluation will therefore take place multiple times. For example a
+ search operation requires the <literal>search</literal> permission for each
+ attribute in the search filter. If all those are allowed, the
+ <literal>read</literal> permission is used to decide what attributes and
+ values can be returned.</para>
+ </note>
+ </section>
+
+ <section xml:id="aci-required">
+ <title>ACI Required For LDAP Operations</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Operations</secondary>
+ </indexterm>
+
+ <para>The minimal access control information required for specific LDAP
+ operations is described here.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Add</term>
+ <listitem>
+ <para>The ACI must allow the <literal>add</literal> permission to entries
+ in the target. This implicitly allows the attributes and values to be set.
+ Use <literal>targetattrfilters</literal> to explicitly deny access to any
+ values if required.</para>
+ <para>For example, the ACI required to allow
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> to add an entry
+ is:</para>
+ <programlisting language="ldif">aci: (version 3.0;acl "Add entry"; allow (add)(userdn =
+ "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Bind</term>
+ <listitem>
+ <para>Because this is used to establish the user's identity and derived
+ authorizations, ACI is irrelevant for this operation and is not checked.
+ To prevent authentication,
+ disable the account instead. For more information see <link
+ xlink:href="admin-guide#manage-accounts"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Managing
+ Accounts Manually</citetitle></link>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Compare</term>
+ <listitem>
+ <para>The ACI must allow the <literal>compare</literal> permission to the
+ attribute in the target entry.</para>
+ <para>For example, the ACI required to allow
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> to compare
+ values against the <literal>sn</literal> attribute is:</para>
+ <programlisting language="ldif">aci: (targetattr = "sn")(version 3.0;acl "Compare surname";
+ allow (compare)(userdn =
+ "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Delete</term>
+ <listitem>
+ <para>The ACI must allow the <literal>delete</literal> permission to the
+ target entry. This implicitly allows the attributes and values in the
+ target to be deleted. Use <literal>targetattrfilters</literal> to
+ explicitly deny access to the values if required.</para>
+ <para>For example, the ACI required to allow
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> to delete an
+ entry is:</para>
+ <programlisting language="ldif">aci: (version 3.0;acl "Delete entry"; allow (delete)
+ (userdn = "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Modify</term>
+ <listitem>
+ <para>The ACI must allow the <literal>write</literal> permission to
+ attributes in the target entries. This implicitly allows all
+ values in the target attribute to be modified. Use
+ <literal>targetattrfilters</literal> to explicitly deny access to specific
+ values if required.</para>
+ <para>For example, the ACI required to allow
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> to modify the
+ <literal>description</literal> attribute in an entry is:</para>
+ <programlisting language="ldif">aci: (targetattr = "description")(version 3.0;
+ acl "Modify description"; allow (write)(userdn =
+ "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ModifyDN</term>
+ <listitem>
+ <para>If the entry is being moved to a <literal>newSuperior</literal>, the
+ <literal>export</literal> permission must be allowed on the target, and
+ the <literal>import</literal> permission must be allowed on the
+ <literal>newSuperior</literal> entry.</para>
+ <para>The ACI must allow <literal>write</literal> permission to the
+ attributes in the old RDN and the new RDN. All values of the old RDN and
+ new RDN can be written implicitly; use
+ <literal>targetattrfilters</literal> to explicitly deny access to values
+ used if required.</para>
+ <para>For example, the ACI required to allow
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> to rename
+ entries named with the <literal>uid</literal> attribute to new
+ locations:</para>
+ <programlisting language="ldif">aci: (targetattr = "uid")(version 3.0;acl "Rename uid= entries";
+ allow (write, import, export)(userdn =
+ "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Search</term>
+ <listitem>
+ <para>ACI is required to process the search filter, and to determine what
+ attributes and values may be returned in the results. The
+ <literal>search</literal> permission is used to allow particular
+ attributes in the search filter. The <literal>read</literal> permission is
+ used to allow particular attributes to be returned. If
+ <literal>read</literal> permission is allowed to any attribute, the
+ server will automatically allow the <literal>objectClass</literal>
+ attribute to also be read. All values of readable attributes can be
+ implicitly read; to restrict this use
+ <literal>targetattrfilters</literal>.</para>
+ <para>For example, the ACI required to allow
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> to search for
+ <literal>uid</literal> attributes, and also to read that attribute in
+ matching entries is:</para>
+ <programlisting language="ldif">aci: (targetattr = "uid")(version 3.0;acl "Search and read uid";
+ allow (search, read)(userdn =
+ "ldap:///uid=bjensen,ou=People,dc=example,dc=com");)
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ </section>
+
+ <section xml:id="about-privileges">
+ <title>About Privileges</title>
+ <indexterm><primary>Privileges</primary></indexterm>
+
+ <para>Privileges provide access control for server administration
+ independently from access control instructions.</para>
+
+ <para>Directory root users, such as <literal>cn=Directory Manager</literal>,
+ are granted privileges in the following list and marked with an asterisk (*)
+ by default. Other administrator users can be assigned privileges, too.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>backend-backup</literal>*</term>
+ <listitem>
+ <para>Request a task to backup data</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>backend-restore</literal>*</term>
+ <listitem>
+ <para>Request a task to restore data from backup</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>bypass-acl</literal>*</term>
+ <listitem>
+ <para>Perform operations without regard to ACIs</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>bypass-lockdown</literal>*</term>
+ <listitem>
+ <para>Perform operations without regard to lockdown mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>cancel-request</literal>*</term>
+ <listitem>
+ <para>Cancel any client request</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>config-read</literal>*</term>
+ <listitem>
+ <para>Read the server configuration</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>config-write</literal>*</term>
+ <listitem>
+ <para>Change the server configuration</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>data-sync</literal></term>
+ <listitem>
+ <para>Perform data synchronization</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>disconnect-client</literal>*</term>
+ <listitem>
+ <para>Close any client connection</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>jmx-notify</literal></term>
+ <listitem>
+ <para>Subscribe to JMX notifications</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>jmx-read</literal></term>
+ <listitem>
+ <para>Read JMX attribute values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>jmx-write</literal></term>
+ <listitem>
+ <para>Write JMX attribute values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldif-export</literal>*</term>
+ <listitem>
+ <para>Export data to LDIF</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ldif-import</literal>*</term>
+ <listitem>
+ <para>Import data from LDIF</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>modify-acl</literal>*</term>
+ <listitem>
+ <para>Change ACIs</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>password-reset</literal>*</term>
+ <listitem>
+ <para>Reset other users' passwords</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>privilege-change</literal>*</term>
+ <listitem>
+ <para>Change the privileges assigned to users</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>proxied-auth</literal></term>
+ <listitem>
+ <para>Use the Proxied Authorization control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>server-lockdown</literal>*</term>
+ <listitem>
+ <para>Put OpenDJ into, and take OpenDJ out of, lockdown mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>server-restart</literal>*</term>
+ <listitem>
+ <para>Request a task to restart the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>server-shutdown</literal>*</term>
+ <listitem>
+ <para>Request a task to stop the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>subentry-write</literal>*</term>
+ <listitem>
+ <para>Perform LDAP subentry write operations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>unindexed-search</literal>*</term>
+ <listitem>
+ <para>Search using a filter with no correponding index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>update-schema</literal>*</term>
+ <listitem>
+ <para>Change OpenDJ schema definitions</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>* = default directory root user privileges</para>
+ </section>
+
+ <section xml:id="configure-privileges">
+ <title>Configuring Privileges</title>
+
+ <para>For root directory administrators, by default <literal>cn=Directory
+ Manager</literal>, you configure privileges using the
+ <command>dsconfig</command> command.</para>
+
+ <para>For non-root directory administrators, you add privileges with
+ the <command>ldapmodify</command> command.</para>
+
+ <procedure xml:id="change-root-dn-privileges">
+ <title>To Change Root DN Privileges</title>
+
+ <step>
+ <para>Start <command>dsconfig</command> in interactive mode.</para>
+ <screen>$ dsconfig
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password</screen>
+ </step>
+ <step>
+ <para>Select the Root DN menu.</para>
+ </step>
+ <step>
+ <para>Select View and edit the Root DN.</para>
+ </step>
+ <step>
+ <para>Edit the <literal>default-root-privilege-name</literal>.</para>
+ </step>
+ <step>
+ <para>Make sure you apply the changes when finished.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="change-individual-privileges">
+ <title>To Add Privileges on an Individual Entry</title>
+
+ <para>Privileges are specified using the <literal>ds-privilege-name</literal>
+ operational attribute, which you can change on the command-line using
+ <command>ldapmodify</command>.</para>
+
+ <step>
+ <para>Determine the privileges to add.</para>
+ <screen>$ cat privilege.ldif
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+changetype: modify
+add: ds-privilege-name
+ds-privilege-name: config-read
+ds-privilege-name: password-reset
+</screen>
+ <para>This example lets the user read the server configuration, and reset
+ user passwords. In order for the user to be able to change a user password,
+ you must also allow the modification using ACIs. For this example, Kirsten
+ Vaughan is a member of the Directory Administrators group for Example.com,
+ and already has access to modify user entries.</para>
+ <para>Prior to having the privileges, Kirsten gets messages about
+ insufficent access when trying to read the server configuration, or
+ reset a user password.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --baseDN cn=config
+ "(objectclass=*)"
+SEARCH operation failed
+Result Code: 50 (Insufficient Access Rights)
+Additional Information: You do not have sufficient privileges to perform
+ search operations in the Directory Server configuration
+$ ldappasswordmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
+ --newPassword changeit
+The LDAP password modify operation failed with result code 50
+Error Message: You do not have sufficient privileges to perform password
+reset operations</screen>
+ </step>
+ <step>
+ <para>Apply the change as a user with the
+ <literal>privilege-change</literal> privilege.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename privilege.ldif
+Processing MODIFY request for uid=kvaughan,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=kvaughan,ou=People,dc=example,dc=com</screen>
+ <para>At this point, Kirsten can perform the operations requiring
+ privileges.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --baseDN cn=config
+ "(objectclass=*)"
+dn: cn=config
+ds-cfg-return-bind-error-messages: false
+ds-cfg-default-password-policy: cn=Default Password Policy,cn=Password Policies,
+ cn=config
+…
+$ ldappasswordmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
+ --newPassword changeit
+The LDAP password modify operation was successful</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="change-group-privileges">
+ <title>To Add Privileges For a Group of Administrators</title>
+
+ <para>For deployments with more than one administrator, you no doubt use
+ a group to define adminstrative rights. You can use a collective attribute
+ subentry to specify privileges for the administrator group.</para>
+
+ <para>Collective attributes provide a standard mechanism for defining
+ attributes that appear on all the entries in a particular subtree. OpenDJ
+ extends collective attributes to give you fine-grained control over the
+ which entries in the subtree are targetted. Also, OpenDJ lets you use
+ virtual attributes, such as <literal>isMemberOf</literal> to construct the
+ filter for targetting entries to which the collective attributes apply. This
+ allows you, for example, to define administrative privileges that apply to
+ all users who belong to an administrator group.</para>
+
+ <step>
+ <para>Create an LDAP subentry that specifies the collective attributes.</para>
+ <screen>$ cat collective.ldif
+dn: cn=Administrator Privileges,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: Administrator Privileges
+ds-privilege-name;collective: config-read
+ds-privilege-name;collective: config-write
+ds-privilege-name;collective: ldif-export
+ds-privilege-name;collective: modify-acl
+ds-privilege-name;collective: password-reset
+ds-privilege-name;collective: proxied-auth
+subtreeSpecification: {base "ou=people", specificationFilter
+ "(isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)" }
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename collective.ldif
+Processing ADD request for cn=Administrator Privileges,dc=example,dc=com
+ADD operation successful for DN cn=Administrator Privileges,dc=example,dc=com</screen>
+ <para>The Directory Administrators group for Example.com includes members
+ like Kirsten Vaughan.</para>
+ </step>
+ <step>
+ <para>Observe that the change takes effect immediately.</para>
+ <screen>$ ldappasswordmodify
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword bribery
+ --authzID "dn:uid=scarter,ou=People,dc=example,dc=com"
+ --newPassword changeit
+The LDAP password modify operation was successful</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="configure-acis">
+ <title>Configuring Access Control</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Examples</secondary>
+ </indexterm>
+
+ <para>Access control instructions are defined in the data, as values for
+ <literal>aci</literal> attributes. They can be imported in LDIF. They can
+ be modified over LDAP. Yet in order to make changes to ACIs users first
+ need the <literal>modify-acl</literal> privilege described previously.
+ By default, only the root DN user has the <literal>modify-acl</literal>
+ privilege.</para>
+
+ <para>Global ACIs on <literal>cn=Access Control Handler,cn=config</literal>
+ can be set using the <command>dsconfig</command> command. Global ACIs have
+ attribute type <literal>ds-cfg-global-aci</literal>. Modify global ACIs from
+ the Access Control Handler menu in <command>dsconfig</command>.</para>
+
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Data access</secondary>
+ </indexterm>
+
+ <itemizedlist>
+ <para>Default global ACIs set up the following access rules.</para>
+ <listitem>
+ <para>Users can employ LDAP controls and perform extended operations.</para>
+ </listitem>
+ <listitem>
+ <para>Anonymous read access is allowed for most user data attributes.</para>
+ </listitem>
+ <listitem>
+ <para>Users can read password values on their own entries after binding.
+ (Also by default, password values are hashed.)</para>
+ </listitem>
+ <listitem>
+ <para>Anonymous read access is allowed for schema-related operational
+ attributes.</para>
+ </listitem>
+ <listitem>
+ <para>Anonymous read access is allowed for root DSE attributes describing
+ what the server supports.</para>
+ </listitem>
+ <listitem>
+ <para>Anonymous read access is allowed for operational attributes related
+ to entry updates and entry identification.</para>
+ </listitem>
+ <listitem>
+ <para>Access to replication data is denied.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Users with write access to add ACIs and with the
+ <literal>modify-acl</literal> privilege can use the
+ <command>ldapmodify</command> command to change ACIs located in user
+ data.</para>
+
+ <para>This section therefore focuses on ACI examples, rather than
+ demonstrating how to update the directory for each example. To update ACIs,
+ either change them using the <command>ldapmodify</command> command, or
+ using OpenDJ Control Panel.</para>
+
+ <para>If you use OpenDJ Control Panel, find the entry to modify in the Manage
+ Entries window. Then try View > LDIF View to edit the entry. Control Panel
+ checks your syntax and lets you know if you made an error before it saves any
+ changes.</para>
+
+ <para>For hints on updating directory entries with
+ <command>ldapmodify</command>, see the section on <link
+ xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#modify-ldap"><citetitle>Modifying Entry
+ Attributes</citetitle></link>, keeping in mind that the name of the ACI
+ attribute is <literal>aci</literal> as shown in the examples that
+ follow.</para>
+
+ <example xml:id="access-control-anonymous-reads">
+ <title>ACI: Anonymous Reads & Searches</title>
+
+ <para>This works when the only attributes you do not want world-readable
+ are password attributes.</para>
+ <programlisting language="ldif">aci: (target ="ldap:///dc=example,dc=com")(targetattr !=
+ "authPassword || userPassword")(version 3.0;acl "Anonymous read-search access";
+ allow (read, search, compare)(userdn = "ldap:///anyone");)
+ </programlisting>
+ </example>
+
+ <example xml:id="access-control-disable-anonymous"><?dbfo keep-together="auto"?>
+ <title>ACI: Disable Anonymous Access</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Disabling anonymous access</secondary>
+ </indexterm>
+
+ <para>By default OpenDJ denies access unless an access control explicitly
+ allows access.<footnote><para>This does not apply to the directory root
+ user, such as <literal>cn=Directory Manager</literal>, who bypasses
+ ACIs.</para></footnote> However, OpenDJ also allows anonymous access by
+ default to use some controls, to perform certain extended operations, to
+ view root DSE operational attributes, to view directory schema definitions,
+ to view some other operational attibutes, and to perform compare and search
+ operations.</para>
+
+ <para>These default capabilities are defined on the
+ <literal>global-aci</literal> property of the access control handler, which
+ you can read by using the
+ <command>dsconfig get-access-control-handler-prop</command> command.</para>
+
+ <screen>$ dsconfig
+ get-access-control-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --property global-aci</screen>
+
+ <para>To disable anonymous read access for example, use the
+ <command>dsconfig set-access-control-handler-prop</command> command.</para>
+
+ <para>First, remove the <literal>global-aci</literal> attribute value that
+ allows anonymous read access. Do not wrap the lines in the following
+ example if you use it as the basis for your script.</para>
+
+ <screen>$ dsconfig \
+ set-access-control-handler-prop \
+ --remove global-aci:\(targetattr!=\"userPassword\|\|authPassword\|\|changes\|\
+\|changeNumber\|\|changeType\|\|changeTime\|\|targetDN\|\|newRDN\|\
+\|newSuperior\|\|deleteOldRDN\|\|targetEntryUUID\|\|changeInitiatorsName\|\
+\|changeLogCookie\|\|includedAttributes\"\)\(version\ 3.0\;\ acl\ \"Anonymous\
+\ read\ access\"\;\ allow\ \(read,search,compare\)\
+\ userdn=\"ldap:///anyone\"\;\)\
+ --hostname opendj.example.com \
+ --port 4444 \
+ --bindDN cn=Directory\ Manager \
+ --bindPassword password \
+ --trustAll \
+ --no-prompt</screen>
+
+ <para>If the <literal>global-aci</literal> does not match the ACI exactly
+ then the command fails to remove the value. An alternative approach is to
+ use the <command>dsconfig</command> command interactively, adding the
+ <option>--commandFilePath</option> option. You can then use the command
+ you capture to remove the property value on other servers for example.
+ To use the <command>dsconfig</command> command this way, start the
+ command as follows.</para>
+
+ <screen>$ dsconfig
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --commandFilePath /tmp/captured-command.sh</screen>
+
+ <para>Next, add a global ACI value that allows authenticated users to
+ perform read operations. You can use <command>dsconfig</command>
+ interactively to add the ACI value as shown below
+ <literal>(targetattr!= … userdn="ldap:///all";)</literal>.</para>
+
+ <programlisting language="ldif">global-aci: (targetattr!="userPassword||
+ authPassword||changes||changeNumber||changeType||changeTime||targetDN||newRDN||
+ newSuperior||deleteOldRDN||targetEntryUUID||changeInitiatorsName||
+ changeLogCookie||includedAttributes")(version 3.0; acl "Authenticated users
+ read access"; allow (read,search,compare) userdn="ldap:///all";)</programlisting>
+
+ <para>Notice that these changes are made to the OpenDJ directory server
+ configuration, and so are not replicated to other servers. You must instead
+ apply the changes separately to each server.</para>
+ </example>
+
+ <example xml:id="access-control-full-access">
+ <title>ACI: Full Access for Administrators</title>
+
+ <para>Directory Administrators need privileges as well for full access to
+ administrative operations.</para>
+ <programlisting language="ldif">aci: (target="ldap:///dc=example,dc=com") (targetattr =
+ "* || +")(version 3.0;acl "Admins can run amok"; allow(
+ all, proxy, import, export) groupdn =
+ "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)
+ </programlisting>
+ <para>Notice both <literal>targetattr = "* || +"</literal>, which permits
+ access to both all user attributes and all operational attributes, and
+ <literal>allow(all, proxy, import, export)</literal>, which permits not
+ only all user operations, but also proxy authorization as well as data
+ import and export operations.</para>
+ </example>
+
+ <example xml:id="access-control-selfwrite-password">
+ <title>ACI: Change Own Password</title>
+
+ <para>By default this capability is set in a global ACI.</para>
+ <programlisting language="ldif">aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr =
+ "authPassword || userPassword")(version 3.0;acl "Allow users to change pass
+ words"; allow (write)(userdn = "ldap:///self");)</programlisting>
+ </example>
+
+ <example xml:id="access-control-selfwrite-group">
+ <title>ACI: Manage Own Group Membership</title>
+
+ <para>For some static groups such as carpoolers and social club members,
+ you might choose to let users manage their own memberships.</para>
+ <programlisting language="ldif">aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")(
+ targetattr = "member")(version 3.0;acl "Self registration"; allow(selfwrite)(
+ userdn = "ldap:///uid=*,ou=People,dc=example,dc=com");)</programlisting>
+ </example>
+
+ <example xml:id="access-control-self-service-group">
+ <title>ACI: Manage Self Service Groups</title>
+
+ <para>Let users create and delete self-managed groups.</para>
+ <programlisting language="ldif">aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")(
+ targattrfilters="add=objectClass:(objectClass=groupOfNames)")(version 3.0;
+ acl "All can create self service groups"; allow (add)(userdn= "
+ ldap:///uid=*,ou=People,dc=example,dc=com");)
+aci: (target ="ldap:///ou=Self Service,ou=Groups,dc=example,dc=com")(version 3
+ .0; acl "Owner can delete self service groups"; allow (delete)(userattr= "
+ owner#USERDN");)</programlisting>
+ </example>
+
+ <example xml:id="access-control-loopback-only">
+ <title>ACI: Permit Clear Text Access Over Loopback Only</title>
+
+ <para>This ACI uses IP address and Security Strength Factor subjects.</para>
+ <programlisting language="ldif">aci: (target = "ldap:///dc=example,dc=com")(targetattr =
+ "*")(version 3.0;acl "Use loopback only for LDAP in the clear"; deny (all)(
+ ip != "127.0.0.1" and ssf <= "1");)</programlisting>
+ <para>The <literal>ssf</literal> is one for example when using SSL but you
+ have not configured a cipher, so the packets are checksummed for integrity
+ checking by all content is nevertheless sent in clear text.</para>
+ </example>
+ </section>
+
+ <section xml:id="get-effective-rights">
+ <title>Viewing Effective Rights</title>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Debugging</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Access control</primary>
+ <secondary>Effective rights</secondary>
+ </indexterm>
+
+ <para>Once you set up a number of ACIs, you might find it difficult to
+ understand by inspection what rights a user actually has to a given entry.
+ The Get Effective Rights control can help.</para>
+
+ <note>
+ <para>The control OID, <literal>1.3.6.1.4.1.42.2.27.9.5.2</literal>, is
+ not allowed by the default global ACIs.</para>
+ </note>
+
+ <para>In this example, Babs Jensen is the owner of a small group of people
+ who are willing to carpool.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword hifalutin
+ --baseDN "ou=Self Service,ou=Groups,dc=example,dc=com"
+ "cn=*"
+dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
+objectClass: groupOfNames
+objectClass: top
+member: uid=bjensen,ou=People,dc=example,dc=com
+description: People who are willing to carpool
+owner: uid=bjensen,ou=People,dc=example,dc=com
+cn: Carpoolers
+</screen>
+
+ <para>Performing the same search with the get effective rights control, and
+ asking for the <literal>aclRights</literal> attribute, shows what rights
+ Babs has on the entry.</para>
+
+ <screen>$ ldapsearch
+ --control effectiverights
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword hifalutin
+ --baseDN "ou=Self Service,ou=Groups,dc=example,dc=com"
+ "cn=*"
+ aclRights
+dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
+aclRights;entryLevel: add:0,delete:1,read:1,write:0,proxy:0
+</screen>
+
+ <para>Requesting the <literal>aclRightsInfo</literal> attribute results in
+ information about the ACIs applied to arrive at the results.</para>
+
+ <screen>$ ldapsearch
+ --control effectiverights
+ --port 1389
+ --bindDN "uid=bjensen,ou=people,dc=example,dc=com"
+ --bindPassword hifalutin
+ --baseDN "ou=Self Service,ou=Groups,dc=example,dc=com"
+ "cn=*"
+ aclRights
+ aclRightsInfo
+dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
+aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read) on e
+ ntry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, objectClas
+ s) to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: evaluat
+ ed allow , deciding_aci: Anonymous read-search access)
+aclRightsInfo;logs;entryLevel;write: acl_summary(main): access not allowed(write
+ ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
+ ) to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis
+ matched the subject )
+aclRightsInfo;logs;entryLevel;add: acl_summary(main): access not allowed(add) on
+ entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL) to
+ (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis matc
+ hed the subject )
+aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access allowed(delete)
+ on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL)
+ to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: evaluated
+ allow , deciding_aci: Owner can delete self service groups)
+aclRights;entryLevel: add:0,delete:1,read:1,write:0,proxy:0
+aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(proxy
+ ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
+ ) to (uid=bjensen,ou=People,dc=example,dc=com) (not proxied) ( reason: no acis
+ matched the subject )
+</screen>
+
+ <para>You can also request the effective rights for another user by using the
+ <option>--getEffectiveRightsAuthzid</option> (short form: <option>-g</option>)
+ option, which takes the authorization identity of the other user as an
+ argument. The following example shows Directory Manager checking anonymous
+ user rights to the same entry. Notice that the authorization identity for an
+ anonymous user is expressed as <literal>"dn:"</literal>.</para>
+
+ <screen>$ ldapsearch
+ --getEffectiveRightsAuthzid "dn:"
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN "ou=Self Service,ou=groups,dc=example,dc=com"
+ "cn=*" aclRightsInfo
+dn: cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com
+aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read) on e
+ ntry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, objectClas
+ s) to (anonymous) (not proxied) ( reason: evaluated allow , deciding_aci: Anony
+ mous read-search access)
+aclRightsInfo;logs;entryLevel;write: acl_summary(main): access not allowed(write
+ ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
+ ) to (anonymous) (not proxied) ( reason: no acis matched the subject )
+aclRightsInfo;logs;entryLevel;add: acl_summary(main): access not allowed(add) on
+ entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL) to
+ (anonymous) (not proxied) ( reason: no acis matched the subject )
+aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access not allowed(dele
+ te) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NU
+ LL) to (anonymous) (not proxied) ( reason: no acis matched the subject )
+aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(proxy
+ ) on entry/attr(cn=Carpoolers,ou=Self Service,ou=Groups,dc=example,dc=com, NULL
+ ) to (anonymous) (not proxied) ( reason: no acis matched the subject )</screen>
+
+ <para>When you need to check access to an attribute that might not yet exist
+ on the entry, you can further use the
+ <option>--getEffectiveRightsAttribute</option> (short form:
+ <option>-e</option>) option, which takes an attribute list as an argument.
+ The following example shows Directory Manager checking anonymous user
+ access to the description attribute for the Self Service groups organizational
+ unit entry. The description attribute is not present on the entry, yet.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN "ou=Self Service,ou=groups,dc=example,dc=com"
+ "ou=Self Service" description
+dn: ou=Self Service,ou=Groups,dc=example,dc=com
+
+$ ldapsearch
+ --getEffectiveRightsAuthzid "dn:"
+ --getEffectiveRightsAttribute description
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN "ou=Self Service,ou=groups,dc=example,dc=com"
+ "ou=Self Service" aclRights
+dn: ou=Self Service,ou=Groups,dc=example,dc=com
+aclRights;attributeLevel;description: search:1,read:1,compare:1,write:0,selfwrit
+ e_add:0,selfwrite_delete:0,proxy:0
+aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0</screen>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pta.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pta.xml
new file mode 100644
index 0000000..dc38847
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pta.xml
@@ -0,0 +1,587 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-pta'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Configuring Pass Through Authentication</title>
+ <indexterm><primary>Pass through authentication</primary></indexterm>
+
+ <para>This chapter focuses on pass through authentication (PTA), whereby you
+ configure another server to determine the response to an authentication
+ request. A typical use case for pass through authentication involves
+ passing authentication through to Active Directory for users coming
+ from Microsoft Windows systems.</para>
+
+ <section xml:id="about-pta">
+ <title>About Pass Through Authentication</title>
+
+ <para>You use <firstterm>LDAP pass through authentication</firstterm> when
+ the credentials for authenticating are stored not in OpenDJ, but instead
+ in a remote directory service. In effect OpenDJ redirects the bind operation
+ against a remote LDAP server.</para>
+
+ <para>Exactly how OpenDJ redirects the bind depends on how the user entry
+ in OpenDJ maps to the corresponding user entry in the remote directory.</para>
+
+ <itemizedlist>
+ <para>OpenDJ provides you several choices to set up the mapping.</para>
+ <listitem>
+ <para>When both the local entry in OpenDJ and the remote entry in the
+ other server have the same DN, you do not have to set up the mapping at
+ all. By default, OpenDJ redirects the bind with the original DN and
+ password from the client application.</para>
+ </listitem>
+ <listitem>
+ <para>When the local entry in OpenDJ has been provisioned with an attribute
+ holding the DN of the remote entry, you can specify which attribute holds
+ the DN, and OpenDJ redirects the bind on the remote server using the DN
+ value.</para>
+ </listitem>
+ <listitem>
+ <para>When you cannot get the remote bind DN directly, you need an
+ attribute and value on the OpenDJ entry that corresponds to an identical
+ attribute and value on the remote server in order to map the local entry
+ to the remote entry. In this case you also need the bind credentials for
+ a user who can search for the entry on the remote server. OpenDJ performs
+ a search for the entry using the matching attribute and value, and then
+ redirects the bind with the DN from the remote entry.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You configure pass through authentication as an authentication policy
+ that you associate with a user's entry in the same way that you associate
+ a password policy with a user's entry. Either a user has an authentication
+ policy for pass through authentication, or the user has a local password
+ policy.</para>
+ </section>
+
+ <section xml:id="configure-pta">
+ <title>Setting Up Pass Through Authentication</title>
+
+ <para>When setting up pass through authentication, you need to know to which
+ remote server or servers to redirect binds, and you need to know how you map
+ user entries in OpenDJ to user entries in the remote directory.</para>
+
+ <procedure xml:id="configure-ssl-to-test-pta">
+ <title>To Set Up SSL Communication For Testing</title>
+
+ <para>When performing pass through authentication, you no doubt protect
+ communications between OpenDJ and the server providing authentication. If
+ you test using SSL with self-signed certificates, and you do not want
+ the client blindly to trust the server, follow these steps to import
+ the authentication server's certificate into the OpenDJ key store.</para>
+
+ <step>
+ <para>Export the server certificate from the authentication server.</para>
+ <para>How you perform this step depends on the authentication directory
+ server. With OpenDJ, you can export the certificate as shown here.</para>
+ <screen>$ cd /path/to/PTA-Server/config
+$ keytool
+ -exportcert
+ -rfc
+ -alias server-cert
+ -keystore keystore
+ -storepass `cat keystore.pin`
+ > /tmp/pta-srv-cert.pem</screen>
+ </step>
+ <step>
+ <para>Make note of the host name used in the certificate.</para>
+ <para>You use the host name when configuring the SSL connection. With
+ OpenDJ, you can view the certificate details as shown here.</para>
+ <screen>$ keytool
+ -list
+ -v
+ -alias server-cert
+ -keystore keystore
+ -storepass `cat keystore.pin`
+Alias name: server-cert
+Creation date: Sep 12, 2011
+Entry type: PrivateKeyEntry
+Certificate chain length: 1
+Certificate[1]:
+Owner: CN=<emphasis role="strong">pta-server.example.com</emphasis>, O=OpenDJ Self-Signed Certificate
+Issuer: CN=<emphasis role="strong">pta-server.example.com</emphasis>, O=OpenDJ Self-Signed Certificate
+Serial number: 4e6dc429
+Valid from: Mon Sep 12 10:34:49 CEST 2011 until: Wed Sep 11 10:34:49 CEST 2013
+Certificate fingerprints:
+ MD5: B6:EE:1C:A0:71:12:EF:6F:21:24:B9:50:EF:8B:4E:6A
+ SHA1: 7E:A1:C9:07:D2:86:56:31:24:14:F7:07:A8:6B:3E:A1:39:63:F4:0E
+ Signature algorithm name: SHA1withRSA
+ Version: 3</screen>
+ </step>
+ <step>
+ <para>Import the authentication server certificate into OpenDJ's
+ key store.</para>
+ <screen>$ cd /path/to/opendj/config
+$ keytool
+ -importcert
+ -alias pta-cert
+ -keystore truststore
+ -storepass `cat keystore.pin`
+ -file /tmp/pta-srv-cert.pem
+Owner: CN=pta-server.example.com, O=OpenDJ Self-Signed Certificate
+Issuer: CN=pta-server.example.com, O=OpenDJ Self-Signed Certificate
+Serial number: 4e6dc429
+Valid from: Mon Sep 12 10:34:49 CEST 2011 until: Wed Sep 11 10:34:49 CEST 2013
+Certificate fingerprints:
+ MD5: B6:EE:1C:A0:71:12:EF:6F:21:24:B9:50:EF:8B:4E:6A
+ SHA1: 7E:A1:C9:07:D2:86:56:31:24:14:F7:07:A8:6B:3E:A1:39:63:F4:0E
+ Signature algorithm name: SHA1withRSA
+ Version: 3
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="configure-pta-policy">
+ <title>To Configure an LDAP Pass Through Authentication Policy</title>
+
+ <para>You configure authentication policies with the
+ <command>dsconfig</command> command. Notice that authentication policies
+ are part of the server configuration, and therefore not replicated.</para>
+
+ <step>
+ <para>Set up an authentication policy for pass through
+ authentication to the authentication server.</para>
+ <screen>$ dsconfig
+ create-password-policy
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --type ldap-pass-through
+ --policy-name "PTA Policy"
+ --set primary-remote-ldap-server:pta-server.example.com:636
+ --set mapped-attribute:uid
+ --set mapped-search-base-dn:"dc=PTA Server,dc=com"
+ --set mapping-policy:mapped-search
+ --set use-ssl:true
+ --set trust-manager-provider:JKS
+ --trustAll
+ --no-prompt</screen>
+ <para>The policy shown here maps identities having this password policy
+ to identities under <literal>dc=PTA Server,dc=com</literal>. Users must
+ have the same <literal>uid</literal> values on both servers. The policy
+ here also uses SSL between OpenDJ and the authentication server.</para>
+ </step>
+ <step>
+ <para>Check that your policy has been added to the list.</para>
+ <screen>$ dsconfig
+ list-password-policies
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --property use-ssl
+
+Password Policy : Type : use-ssl
+------------------------:-------------------:--------
+Default Password Policy : password-policy : -
+PTA Policy : ldap-pass-through : true
+Root Password Policy : password-policy : -</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="configure-pta-to-ad">
+ <title>To Configure Pass Through Authentication To Active Directory</title>
+ <indexterm>
+ <primary>Active Directory</primary>
+ <see>Pass through authentication</see>
+ </indexterm>
+
+ <para>The steps below demonstrate setting up pass through authentication
+ to Active Directory. Here is some background to help you make sense of the
+ steps.</para>
+
+ <para>Entries on the OpenDJ side use <literal>uid</literal> as the naming
+ attribute, and entries also have <literal>cn</literal> attributes. Active
+ Directory entries use <literal>cn</literal> as the naming attribute.
+ User entries on both sides share the same <literal>cn</literal> values. The
+ mapping between entries therefore uses <literal>cn</literal>.</para>
+
+ <para>Consider the example where an OpenDJ account with <literal>cn=LDAP
+ PTA User</literal> and DN
+ <literal>uid=ldapptauser,ou=People,dc=example,dc=com</literal> corresponds
+ to an Active Directory account with DN <literal>CN=LDAP PTA
+ User,CN=Users,DC=internal,DC=forgerock,DC=com</literal>. The steps below
+ enable the user with <literal>cn=LDAP PTA User</literal> on OpenDJ
+ authenticate through to Active Directory.</para>
+
+ <screen>$ ldapsearch
+ --hostname opendj.example.com
+ --baseDN dc=example,dc=com
+ uid=ldapptauser
+ cn
+dn: uid=ldapptauser,ou=People,dc=example,dc=com
+cn: LDAP PTA User
+
+$ ldapsearch
+ --hostname ad.example.com
+ --baseDN "CN=Users,DC=internal,DC=forgerock,DC=com"
+ --bindDN "cn=administrator,cn=Users,DC=internal,DC=forgerock,DC=com"
+ --bindPassword password
+ "(cn=LDAP PTA User)"
+ cn
+dn: CN=LDAP PTA User,CN=Users,DC=internal,DC=forgerock,DC=com
+cn: LDAP PTA User</screen>
+
+ <para>OpenDJ must map its
+ <literal>uid=ldapptauser,ou=People,dc=example,dc=com</literal> entry to the
+ Active Directory entry, <literal>CN=LDAP PTA
+ User,CN=Users,DC=internal,DC=forgerock,DC=com</literal>. In order to do the
+ mapping, OpenDJ has to perform a search for the user in Active Directory
+ using the <literal>cn</literal> value it recovers from its own entry for the
+ user. Active Directory does not allow anonymous searches, so part of the
+ authentication policy configuration consists of the administrator DN and
+ password OpenDJ uses to bind to Active Directory to be able to search.</para>
+
+ <para>Finally, before setting up the pass through authentication policy,
+ make sure OpenDJ can connect to Active Directory over a secure connection
+ to avoid sending passwords in the clear.</para>
+
+ <step>
+ <para>Export the certificate from the Windows server.</para>
+ <substeps>
+ <step>
+ <para>Click start > All Programs > Administrative Tools >
+ Certification Authority, then right-click the CA and select
+ Properties.</para>
+ </step>
+ <step>
+ <para>In the General tab, select the certificate and click View
+ Certificate.</para>
+ </step>
+ <step>
+ <para>In the Certificate dialog, click the Details tab, then click
+ Copy to File...</para>
+ </step>
+ <step>
+ <para>Use the Certificate Export Wizard to export the certificate into
+ a file, such as <filename>windows.cer</filename>.</para>
+ </step>
+ </substeps>
+ </step>
+ <step>
+ <para>Copy the exported certificate to the system running OpenDJ.</para>
+ </step>
+ <step>
+ <para>Import the server certificate into OpenDJ's key store.</para>
+ <screen>$ cd /path/to/opendj/config
+$ keytool
+ -importcert
+ -alias ad-cert
+ -keystore truststore
+ -storepass `cat keystore.pin`
+ -file ~/Downloads/windows.cer
+Owner: CN=internal-ACTIVEDIRECTORY-CA, DC=internal, DC=forgerock, DC=com
+Issuer: CN=internal-ACTIVEDIRECTORY-CA, DC=internal, DC=forgerock, DC=com
+Serial number: 587465257200a7b14a6976cb47916b32
+Valid from: Tue Sep 20 11:14:24 CEST 2011 until: Tue Sep 20 11:24:23 CEST 2016
+Certificate fingerprints:
+ MD5: A3:D6:F1:8D:0D:F9:9C:76:00:BC:84:8A:14:55:28:38
+ SHA1: 0F:BD:45:E6:21:DF:BD:6A:CA:8A:7C:1D:F9:DA:A1:8E:8A:0D:A4:BF
+ Signature algorithm name: SHA1withRSA
+ Version: 3
+
+Extensions:
+
+#1: ObjectId: 2.5.29.19 Criticality=true
+BasicConstraints:[
+ CA:true
+ PathLen:2147483647
+]
+
+#2: ObjectId: 2.5.29.15 Criticality=false
+KeyUsage [
+ DigitalSignature
+ Key_CertSign
+ Crl_Sign
+]
+
+#3: ObjectId: 2.5.29.14 Criticality=false
+SubjectKeyIdentifier [
+KeyIdentifier [
+0000: A3 3E C0 E3 B2 76 15 DC 97 D0 B3 C0 2E 77 8A 11 .>...v.......w..
+0010: 24 62 70 0A $bp.
+]
+]
+
+#4: ObjectId: 1.3.6.1.4.1.311.21.1 Criticality=false
+
+Trust this certificate? [no]: yes
+Certificate was added to keystore</screen>
+ <para>At this point OpenDJ can connect to Active Directory over SSL.</para>
+ </step>
+ <step>
+ <para>Set up an authentication policy for OpenDJ users to authenticate
+ to Active Directory.</para>
+ <screen>$ dsconfig
+ create-password-policy
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --type ldap-pass-through
+ --policy-name "AD PTA Policy"
+ --set primary-remote-ldap-server:ad.example.com:636
+ --set mapped-attribute:cn
+ --set mapped-search-base-dn:"CN=Users,DC=internal,DC=forgerock,DC=com"
+ --set mapped-search-bind-dn:"cn=administrator,cn=Users,DC=internal,DC=forgerock
+ ,DC=com"
+ --set mapped-search-bind-password:password
+ --set mapping-policy:mapped-search
+ --set trust-manager-provider:JKS
+ --set use-ssl:true
+ --trustAll --no-prompt</screen>
+ </step>
+ <step>
+ <para>Assign the authentication policy to a test user.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: uid=ldapptauser,ou=People,dc=example,dc=com
+changetype: modify
+add: ds-pwp-password-policy-dn
+ds-pwp-password-policy-dn: cn=AD PTA Policy,cn=Password Policies,cn=config
+
+Processing MODIFY request for uid=ldapptauser,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=ldapptauser,ou=People,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check that the user can bind using pass through authentication to
+ Active Directory.</para>
+ <screen>$ ldapsearch
+ --hostname opendj.example.com
+ --port 1389
+ --baseDN dc=example,dc=com
+ --bindDN uid=ldapptauser,ou=People,dc=example,dc=com
+ --bindPassword password
+ "(cn=LDAP PTA User)"
+ userpassword cn
+dn: uid=ldapptauser,ou=People,dc=example,dc=com
+cn: LDAP PTA User</screen>
+ <para>Notice that to complete the search, the user authenticated with a
+ password to Active Directory, though no <literal>userpassword</literal>
+ value is present on the entry on the OpenDJ side.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="assigning-pta">
+ <title>Assigning Pass Through Authentication Policies</title>
+
+ <para>You assign authentication policies in the same way as you
+ assign password policies, by using the
+ <literal>ds-pwp-password-policy-dn</literal> attribute.</para>
+
+ <note>
+ <para>Although you assign the pass through authentication policy using
+ the same attribute as for password policy, the authentication policy is
+ not in fact a password policy. Therefore, the user with a pass through
+ authentication policy does not have a value for the operational attribute
+ <literal>pwdPolicySubentry</literal>.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=user.0
+ pwdPolicySubentry
+dn: uid=user.0,ou=People,dc=example,dc=com
+</screen>
+ </note>
+
+ <procedure xml:id="assign-pta-to-user">
+ <title>To Assign a Pass Through Authentication Policy To a User</title>
+
+ <para>Users depending on pass through authentication no longer need a local
+ password policy, as they no longer authenticate locally.</para>
+
+ <para>Examples in the following procedure work for this user, whose
+ entry on OpenDJ is as shown. Notice that the user has no password set. The
+ user's password on the authentication server is
+ <literal>password</literal>.</para>
+
+ <programlisting language="ldif">dn: uid=user.0,ou=People,dc=example,dc=com
+cn: Aaccf Amar
+description: This is the description for Aaccf Amar.
+employeeNumber: 0
+givenName: Aaccf
+homePhone: +1 225 216 5900
+initials: ASA
+l: Panama City
+mail: user.0@maildomain.net
+mobile: +1 010 154 3228
+objectClass: person
+objectClass: inetorgperson
+objectClass: organizationalperson
+objectClass: top
+pager: +1 779 041 6341
+postalAddress: Aaccf Amar$01251 Chestnut Street$Panama City, DE 50369
+postalCode: 50369
+sn: Amar
+st: DE
+street: 01251 Chestnut Street
+telephoneNumber: +1 685 622 6202
+uid: user.0
+</programlisting>
+
+ <para>This user's entry on the authentication server also has
+ <literal>uid=user.0</literal>, and the pass through authentication policy
+ performs the mapping to find the user entry in the authentication
+ server.</para>
+
+ <step>
+ <para>Prevent users from changing their own password policies.</para>
+ <screen>$ cat protect-pta.ldif
+dn: ou=People,dc=example,dc=com
+changetype: modify
+add: aci
+aci: (target ="ldap:///uid=*,ou=People,dc=example,dc=com")(targetattr =
+ "ds-pwp-password-policy-dn")(version 3.0;acl "Cannot choose own pass
+ word policy";deny (write)(userdn = "ldap:///self");)
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename protect-pta.ldif
+Processing MODIFY request for ou=People,dc=example,dc=com
+MODIFY operation successful for DN ou=People,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Update the user's <literal>ds-pwp-password-policy-dn</literal>
+ attribute.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: uid=user.0,ou=People,dc=example,dc=com
+changetype: modify
+add: ds-pwp-password-policy-dn
+ds-pwp-password-policy-dn: cn=PTA Policy,cn=Password Policies,cn=config
+
+Processing MODIFY request for uid=user.0,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=user.0,ou=People,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check that the user can authenticate through to the authentication
+ server.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ --bindDN uid=user.0,ou=People,dc=example,dc=com
+ --bindPassword password
+ uid=user.0
+ cn sn
+dn: uid=user.0,ou=People,dc=example,dc=com
+cn: Aaccf Amar
+sn: Amar
+</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="assign-pta-to-group">
+ <title>To Assign a Pass Through Authentication Policy To a Group</title>
+
+ <para>Examples in the following steps use the pass through authentication
+ policy as defined above. Kirsten Vaughan's entry has been reproduced on
+ the authentication server under <literal>dc=PTA
+ Server,dc=com</literal>.</para>
+
+ <step>
+ <para>Create a subentry to assign a collective attribute that sets the
+ <literal>ds-pwp-password-policy-dn</literal> attribute for group
+ members' entries.</para>
+
+ <screen>$ cat pta-coll.ldif
+dn: cn=PTA Policy for Dir Admins,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: PTA Policy for Dir Admins
+ds-pwp-password-policy-dn;collective: cn=PTA Policy,cn=Password Policies,
+ cn=config
+subtreeSpecification: { base "ou=People", specificationFilter "(isMemberOf=
+ cn=Directory Administrators,ou=Groups,dc=example,dc=com)"}
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename pta-coll.ldif
+Processing ADD request for cn=PTA Policy for Dir Admins,dc=example,dc=com
+ADD operation successful for DN cn=PTA Policy for Dir Admins,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check that OpenDJ has applied the policy.</para>
+ <substeps>
+ <step>
+ <para>Make sure you can bind as the user on the authentication
+ server.</para>
+ <screen>$ ldapsearch
+ --port 2389
+ --bindDN "uid=kvaughan,ou=People,dc=PTA Server,dc=com"
+ --bindPassword password
+ --baseDN "dc=PTA Server,dc=com"
+ uid=kvaughan
+dn: uid=kvaughan,ou=People,dc=PTA Server,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+givenName: Kirsten
+uid: kvaughan
+cn: Kirsten Vaughan
+sn: Vaughan
+userPassword: {SSHA}x1BdtrJyRTw63kBSJFDvgvd4guzk66CV8L+t8w==
+ou: People
+mail: jvaughan@example.com
+</screen>
+ </step>
+ <step>
+ <para>Check that the user can authenticate through to the authentication
+ server from OpenDJ.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "uid=kvaughan,ou=people,dc=example,dc=com"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ uid=kvaughan
+ cn sn
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+cn: Kirsten Vaughan
+sn: Vaughan</screen>
+ </step>
+ </substeps>
+ </step>
+ </procedure>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pwd-policy.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pwd-policy.xml
new file mode 100644
index 0000000..a5be6e5
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-pwd-policy.xml
@@ -0,0 +1,983 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-pwd-policy'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Configuring Password Policy</title>
+ <indexterm><primary>Password policy</primary></indexterm>
+
+ <para>If you want to synchronize password policy across your organization
+ and your applications go to the directory for authentication, then the
+ directory can be a good place to enforce your password policy uniformly.
+ Even if you do not depend on the directory for all your password policy,
+ you no doubt still want to consider directory password policy if only to
+ choose the appropriate password storage scheme.</para>
+
+ <para>This chapter covers password policy, including examples of how
+ to configure password policies for common use cases.</para>
+
+ <section xml:id="pwp-overview">
+ <title>About OpenDJ Password Policies</title>
+
+ <para>OpenDJ password policies govern not only passwords, but also account
+ lockout, and how OpenDJ provides notification about account status.</para>
+
+ <para>OpenDJ supports password policies as part of the server configuration,
+ and also subentry password policies as part of the (replicated) user
+ data.</para>
+
+ <section xml:id="pwp-per-server">
+ <title>Server Based Password Policies</title>
+
+ <para>You manage server based password policies in the OpenDJ configuration
+ by using the <command>dsconfig</command> command. As they are part of the
+ server configuration, such password policies are not replicated. You must
+ instead apply password policy configuration updates to each replica in your
+ deployment.</para>
+
+ <para>By default, OpenDJ includes two password policy configurations, one
+ default for all users, and another for directory root DN users, such as
+ <literal>cn=Directory Manager</literal>. You can see all the default password
+ policy settings using the <command>dsconfig</command> command as
+ follows.</para>
+
+ <screen>$ dsconfig
+ get-password-policy-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --advanced
+Property : Value(s)
+------------------------------------------:--------------------------
+account-status-notification-handler : -
+allow-expired-password-changes : false
+allow-multiple-password-values : false
+allow-pre-encoded-passwords : false
+allow-user-password-changes : true
+default-password-storage-scheme : Salted SHA-1
+deprecated-password-storage-scheme : -
+expire-passwords-without-warning : false
+force-change-on-add : false
+force-change-on-reset : false
+grace-login-count : 0
+idle-lockout-interval : 0 s
+last-login-time-attribute : -
+last-login-time-format : -
+lockout-duration : 0 s
+lockout-failure-count : 0
+lockout-failure-expiration-interval : 0 s
+max-password-age : 0 s
+max-password-reset-age : 0 s
+min-password-age : 0 s
+password-attribute : userpassword
+password-change-requires-current-password : false
+password-expiration-warning-interval : 5 d
+password-generator : Random Password Generator
+password-history-count : 0
+password-history-duration : 0 s
+password-validator : -
+previous-last-login-time-format : -
+require-change-by-time : -
+require-secure-authentication : false
+require-secure-password-changes : false
+skip-validation-for-administrators : false
+state-update-failure-policy : reactive</screen>
+
+ <para>See the <citetitle>OpenDJ Configuration Reference</citetitle> page
+ on <link xlink:show="new"
+ xlink:href="${configRefBase}password-policy.html"
+ ><citetitle>Password Policy</citetitle></link> for detailed descriptions of
+ each property.</para>
+
+ <para>Here you notice that many capabilities are not set by default: no
+ lockout, no password expiration, no multiple passwords, no password validator
+ to check that passwords contain the appropriate mix of characters. This means
+ that if you decide to use the directory to enforce password policy, you
+ must configure at least the default password policy to meet your
+ needs.</para>
+
+ <para>Yet a few basic protections are configured by default. When you import
+ LDIF with <literal>userPassword</literal> values, OpenDJ hashes the values
+ before storing them. When a user provides a password value during a bind for
+ example, the server hashes the value provided to compared it with the stored
+ value. Even the directory manager cannot see the plain text value of a user's
+ password.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ userpassword
+dn: uid=bjensen,ou=People,dc=example,dc=com
+userpassword: {SSHA}QWAtw8ch/9850HNFRRqLNMIQc1YhxCnOoGmk1g==</screen>
+
+ <para>In addition, users can change their passwords provided you have
+ granted them access to do so. OpenDJ uses the <literal>userPassword</literal>
+ attribute to store passwords by default, rather than the
+ <literal>authPassword</literal> attribute, which is designed to store
+ passwords hashed by the client application.</para>
+ </section>
+
+ <section xml:id="pwp-replicated">
+ <title>Subentry Based Password Policies</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+
+ <para>You manage subentry password policies by adding the subentries
+ alongside the user data. Thus OpenDJ can replicate subentry password
+ policies across servers.</para>
+
+ <indexterm>
+ <primary>Password policy</primary>
+ <secondary>Behera Internet-Draft</secondary>
+ </indexterm>
+ <para>Subentry password policies support the Internet-Draft <link
+ xlink:href="http://tools.ietf.org/html/draft-behera-ldap-password-policy-09"
+ >Password Policy for LDAP Directories</link> (version 09). A subentry
+ password policy effectively overrides settings in the default password
+ policy defined in the OpenDJ configuration. Settings not supported or not
+ included in the subentry password policy are thus inherited from the default
+ password policy.</para>
+
+ <para>As a result, the following Internet-Draft password policy attributes
+ override the default password policy when you set them in the
+ subentry.</para>
+ <itemizedlist>
+ <listitem><para><literal>pwdAllowUserChange</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>allow-user-password-changes</literal></para></listitem>
+ <listitem><para><literal>pwdMustChange</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>force-change-on-reset</literal></para></listitem>
+ <listitem><para><literal>pwdGraceAuthNLimit</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>grace-login-count</literal></para></listitem>
+ <listitem><para><literal>pwdLockoutDuration</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>lockout-duration</literal></para></listitem>
+ <listitem><para><literal>pwdMaxFailure</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>lockout-failure-count</literal></para></listitem>
+ <listitem><para><literal>pwdFailureCountInterval</literal>, corresponding
+ to the OpenDJ password policy property
+ <literal>lockout-failure-expiration-interval</literal></para></listitem>
+ <listitem><para><literal>pwdMaxAge</literal>, corresponding to the OpenDJ
+ password policy property
+ <literal>max-password-age</literal></para></listitem>
+ <listitem><para><literal>pwdMinAge</literal>, corresponding to the OpenDJ
+ password policy property
+ <literal>min-password-age</literal></para></listitem>
+ <listitem><para><literal>pwdAttribute</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>password-attribute</literal></para></listitem>
+ <listitem><para><literal>pwdSafeModify</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>password-change-requires-current-password</literal></para></listitem>
+ <listitem><para><literal>pwdExpireWarning</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>password-expiration-warning-interval</literal></para></listitem>
+ <listitem><para><literal>pwdInHistory</literal>, corresponding to the
+ OpenDJ password policy property
+ <literal>password-history-count</literal></para></listitem>
+ </itemizedlist>
+
+ <para>The following Internet-Draft password policy attributes are not
+ taken into account by OpenDJ.</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>pwdCheckQuality</literal>, as OpenDJ has password
+ validators. You can set password validators to use in the default
+ password policy.</para>
+ </listitem>
+ <listitem>
+ <para><literal>pwdMinLength</literal>, as this is handled by the Length
+ Based Password Validator. You can configure this as part of the
+ default password policy.</para>
+ </listitem>
+ <listitem>
+ <para><literal>pwdLockout</literal>, as OpenDJ can deduce whether
+ lockout is configured based on the values of other lockout-related
+ password policy attributes.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Values of the following properties are inherited from the default
+ password policy for Internet-Draft based password policies.</para>
+ <itemizedlist>
+ <listitem><para><literal>account-status-notification-handlers</literal></para></listitem>
+ <listitem><para><literal>allow-expired-password-changes</literal></para></listitem>
+ <listitem><para><literal>allow-multiple-password-values</literal></para></listitem>
+ <listitem><para><literal>allow-pre-encoded-passwords</literal></para></listitem>
+ <listitem><para><literal>default-password-storage-schemes</literal></para></listitem>
+ <listitem><para><literal>deprecated-password-storage-schemes</literal></para></listitem>
+ <listitem><para><literal>expire-passwords-without-warning</literal></para></listitem>
+ <listitem><para><literal>force-change-on-add</literal></para></listitem>
+ <listitem><para><literal>idle-lockout-interval</literal></para></listitem>
+ <listitem><para><literal>last-login-time-attribute</literal></para></listitem>
+ <listitem><para><literal>last-login-time-format</literal></para></listitem>
+ <listitem><para><literal>max-password-reset-age</literal></para></listitem>
+ <listitem><para><literal>password-generator</literal></para></listitem>
+ <listitem><para><literal>password-history-duration</literal></para></listitem>
+ <listitem><para><literal>password-validators</literal></para></listitem>
+ <listitem><para><literal>previous-last-login-time-formats</literal></para></listitem>
+ <listitem><para><literal>require-change-by-time</literal></para></listitem>
+ <listitem><para><literal>require-secure-authentication</literal></para></listitem>
+ <listitem><para><literal>require-secure-password-changes</literal></para></listitem>
+ <listitem><para><literal>skip-validation-for-administrators</literal></para></listitem>
+ <listitem><para><literal>state-update-failure-policy</literal></para></listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="pwp-application">
+ <title>Which Password Policy Applies</title>
+
+ <para>The password policy that applies to a user is identified by the
+ operational attribute, <literal>pwdPolicySubentry</literal>.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen pwdPolicySubentry
+dn: uid=bjensen,ou=People,dc=example,dc=com
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config</screen>
+ </section>
+ </section>
+
+ <section xml:id="configure-pwp">
+ <title>Configuring Password Policies</title>
+
+ <para>You configure server based password policies using the
+ <command>dsconfig</command> command. Notice that server based password
+ policies are part of the server configuration, and therefore not replicated.
+ Alternatively, you can configure a subset of password policy features using
+ subentry based password policies that are stored with the replicated
+ server data. This section covers both server based and subentry based
+ password policies.</para>
+
+ <procedure xml:id="default-pwp">
+ <title>To Adjust the Default Password Policy</title>
+ <indexterm>
+ <primary>Password policy</primary>
+ <secondary>Default</secondary>
+ </indexterm>
+
+ <para>You can reconfigure the default password policy for example to
+ enforce password expiration, check that passwords do not match dictionary
+ words, and prevent password reuse. This default policy is a server based
+ password policy.</para>
+ <step>
+ <para>Enable the appropriate password validator.</para>
+ <screen>$ dsconfig
+ set-password-validator-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --validator-name Dictionary
+ --set enabled:true
+ --set check-substrings:true
+ --set min-substring-length:4
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Apply the changes to the default password policy.</para>
+ <screen>$ dsconfig
+ set-password-policy-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set max-password-age:90d
+ --set min-password-age:4w
+ --set password-history-count:7
+ --set password-validator:Dictionary
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Check your work.</para>
+ <screen>$ dsconfig
+ get-password-policy-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+Property : Value(s)
+------------------------------------------:--------------------------
+account-status-notification-handler : -
+allow-expired-password-changes : false
+allow-user-password-changes : true
+default-password-storage-scheme : Salted SHA-1
+deprecated-password-storage-scheme : -
+expire-passwords-without-warning : false
+force-change-on-add : false
+force-change-on-reset : false
+grace-login-count : 0
+idle-lockout-interval : 0 s
+last-login-time-attribute : -
+last-login-time-format : -
+lockout-duration : 0 s
+lockout-failure-count : 0
+lockout-failure-expiration-interval : 0 s
+max-password-age : 12 w 6 d
+max-password-reset-age : 0 s
+min-password-age : 4 w
+password-attribute : userpassword
+password-change-requires-current-password : false
+password-expiration-warning-interval : 5 d
+password-generator : Random Password Generator
+password-history-count : 7
+password-history-duration : 0 s
+password-validator : Dictionary
+previous-last-login-time-format : -
+require-change-by-time : -
+require-secure-authentication : false
+require-secure-password-changes : false</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="create-per-server-pwp">
+ <title>To Create a Server Based Password Policy</title>
+
+ <para>You can add a password policy for example for new users who have not
+ yet used their credentials to bind.</para>
+ <step>
+ <para>Create the new password policy.</para>
+ <screen>$ dsconfig
+ create-password-policy
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "New Account Password Policy"
+ --set default-password-storage-scheme:"Salted SHA-1"
+ --set force-change-on-add:true
+ --set password-attribute:userPassword
+ --type password-policy
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Check your work.</para>
+ <screen>$ dsconfig
+ get-password-policy-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "New Account Password Policy"
+Property : Value(s)
+------------------------------------------:-------------
+account-status-notification-handler : -
+allow-expired-password-changes : false
+allow-user-password-changes : true
+default-password-storage-scheme : Salted SHA-1
+deprecated-password-storage-scheme : -
+expire-passwords-without-warning : false
+force-change-on-add : true
+force-change-on-reset : false
+grace-login-count : 0
+idle-lockout-interval : 0 s
+last-login-time-attribute : -
+last-login-time-format : -
+lockout-duration : 0 s
+lockout-failure-count : 0
+lockout-failure-expiration-interval : 0 s
+max-password-age : 0 s
+max-password-reset-age : 0 s
+min-password-age : 0 s
+password-attribute : userpassword
+password-change-requires-current-password : false
+password-expiration-warning-interval : 5 d
+password-generator : -
+password-history-count : 0
+password-history-duration : 0 s
+password-validator : -
+previous-last-login-time-format : -
+require-change-by-time : -
+require-secure-authentication : false
+require-secure-password-changes : false</screen>
+
+ <para>If you use a password policy like this, you might want to change the
+ user's policy again when the new user successfully updates the
+ password.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="create-repl-pwp">
+ <title>To Create a Subentry Based Password Policy</title>
+ <para>You can add a subentry to configure a password policy that
+ applies to Directory Administrators.</para>
+
+ <step>
+ <para>Create the entry that specifies the password policy.</para>
+ <screen>$ cat /path/to/subentry-pwp.ldif
+dn: cn=Subentry Password Policy,dc=example,dc=com
+objectClass: top
+objectClass: subentry
+objectClass: pwdPolicy
+cn: Subentry Password Policy
+pwdAttribute: userPassword
+pwdLockout: TRUE
+pwdMaxFailure: 3
+pwdFailureCountInterval: 300
+pwdLockoutDuration: 300
+pwdAllowUserChange: TRUE
+pwdSafeModify: TRUE
+subtreeSpecification: {base "ou=people", specificationFilter
+ "(isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)" }</screen>
+ </step>
+ <step>
+ <para>Add the policy to the directory.</para>
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename /path/to/subentry-pwp.ldif
+Processing ADD request for cn=Subentry Password Policy,dc=example,dc=com
+ADD operation successful for DN cn=Subentry Password Policy,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check that the policy applies as specified.</para>
+ <para>In the example, the policy should apply to a Directory Administrator,
+ while a normal user has the default password policy. Here, Kirsten Vaughan
+ is a member of the Directory Administrators group, and Babs Jensen is not
+ a member.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=kvaughan
+ pwdPolicySubentry
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+pwdPolicySubentry: cn=Subentry Password Policy,dc=example,dc=com
+
+$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ pwdPolicySubentry
+dn: uid=bjensen,ou=People,dc=example,dc=com
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="assign-pwp">
+ <title>Assigning Password Policies</title>
+
+ <para>You assign subentry based password policies for a subtree of the DIT by
+ adding the policy to an LDAP subentry whose immediate superior is the root of
+ the subtree. In other words you can add the subtree based password policy
+ under <literal>ou=People,dc=example,dc=com</literal>, to have it apply to all
+ entries under <literal>ou=People,dc=example,dc=com</literal>. You can further
+ use the capabilities of LDAP <link
+ xlink:href="http://tools.ietf.org/html/rfc3672">subentries</link> to refine
+ the scope of application.</para>
+
+ <para>You assign server based password policies by using the
+ <literal>ds-pwp-password-policy-dn</literal> attribute.</para>
+
+ <procedure xml:id="assign-pwp-to-individual">
+ <title>To Assign a Password Policy to a User</title>
+
+ <step>
+ <para>Prevent users from selecting their own password policy.</para>
+
+ <screen>$ cat protectpwp.ldif
+dn: ou=People,dc=example,dc=com
+changetype: modify
+add: aci
+aci: (target ="ldap:///uid=*,ou=People,dc=example,dc=com")(targetattr =
+ "ds-pwp-password-policy-dn")(version 3.0;acl "Cannot choose own pass
+ word policy";deny (write)(userdn = "ldap:///self");)
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename protectpwp.ldif
+Processing MODIFY request for ou=People,dc=example,dc=com
+MODIFY operation successful for DN ou=People,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Update the user's <literal>ds-pwp-password-policy-dn</literal>
+ attribute.</para>
+
+ <screen>$ cat newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: changeme
+ds-pwp-password-policy-dn: cn=New Account Password Policy,cn=Password Policies,
+ cn=config
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename newuser.ldif
+Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
+ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check your work.</para>
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN dc=example,dc=com
+ uid=newuser
+ pwdPolicySubentry
+dn: uid=newuser,ou=People,dc=example,dc=com
+pwdPolicySubentry: cn=New Account Password Policy,cn=Password Policies,cn=config</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="assign-pwp-to-group">
+ <title>To Assign a Password Policy to a Group</title>
+
+ <step>
+ <para>Create a subentry defining the collective attribute that sets the
+ <literal>ds-pwp-password-policy-dn</literal> attribute for group
+ members' entries.</para>
+
+ <screen>$ cat pwp-coll.ldif
+dn: cn=Password Policy for Dir Admins,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: Password Policy for Dir Admins
+ds-pwp-password-policy-dn;collective: cn=Root Password Policy,cn=Pass
+ word Policies,cn=config
+subtreeSpecification: { base "ou=People", specificationFilter "(isMemberOf=
+ cn=Directory Administrators,ou=Groups,dc=example,dc=com)"}
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename pwp-coll.ldif
+Processing ADD request for cn=Password Policy for Dir Admins,dc=example,dc=com
+ADD operation successful for DN cn=Password Policy for Dir
+ Admins,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check your work.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=kvaughan
+ pwdPolicySubentry
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+pwdPolicySubentry: cn=Root Password Policy,cn=Password Policies,cn=config</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="configure-pwd-generation">
+ <title>Configuring Password Generation</title>
+ <indexterm>
+ <primary>Passwords</primary>
+ <secondary>Generating</secondary>
+ </indexterm>
+
+ <para>Password generators are used by OpenDJ during the LDAP password modify
+ extended operation to construct a new password for the user. In other words,
+ a directory administrator resetting a user's password can have OpenDJ
+ directory server generate the new password.</para>
+
+ <screen>$ ldappasswordmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --authzID "u:bjensen"
+The LDAP password modify operation was successful
+Generated Password: eak77qdi</screen>
+
+ <para>The default password policy shown in <xref linkend="default-pwp" /> uses
+ the Random Password Generator.</para>
+
+ <screen>$ dsconfig
+ get-password-policy-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --property password-generator
+Property : Value(s)
+-------------------:--------------------------
+password-generator : Random Password Generator
+$ dsconfig
+ get-password-generator-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --generator-name "Random Password Generator"
+ --property password-generator
+ Property : Value(s)
+-----------------------:-----------------------------------------------------
+enabled : true
+password-character-set : alpha:abcdefghijklmnopqrstuvwxyz, numeric:0123456789
+password-format : "alpha:3,numeric:2,alpha:3"</screen>
+
+ <para>Notice that the default configuration for the Random Password Generator
+ defines two <literal>password-character-set</literal> values, and then uses
+ those definitions in the <literal>password-format</literal> so that generated
+ passwords have eight characters: three from the <literal>alpha</literal> set,
+ followed by two from the <literal>numeric</literal> set, followed by three
+ from the <literal>alpha</literal> set. The
+ <literal>password-character-set</literal> name must be ASCII.</para>
+
+ <para>To set the password generator that OpenDJ employs when constructing a
+ new password for a user, set the <literal>password-generator</literal>
+ property for the password policy that applies to the user.</para>
+
+ <para>The following example does not change the password policy, but instead
+ changes the Random Password Generator configuration, and then demonstrates a
+ password being generated upon reset.</para>
+
+ <screen>$ dsconfig
+ set-password-generator-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --generator-name "Random Password Generator"
+ --remove password-character-set:alpha:abcdefghijklmnopqrstuvwxyz
+ --add
+ password-character-set:alpha:ABCDEFGHIJKLMNOPQRSTUVWabcdefghijklmnopqrstuvwxyz
+ --add password-character-set:punct:,./\`!@#\$%^&*:\;[]\"\'\(\)+=-_~\\
+ --set
+ password-format:alpha:3,punct:1,numeric:2,punct:2,numeric:3,alpha:3,punct:2
+ --no-prompt
+$ ldappasswordmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --authzID "u:bjensen"
+The LDAP password modify operation was successful
+Generated Password: pld^06:)529HTq$'</screen>
+
+ <para>If you also set up a password validator in the password policy as
+ shown in <xref linkend="default-pwp" /> and further described in
+ <xref linkend="configure-pwd-validation" />, make sure the generated
+ passwords are acceptable to the validator.</para>
+ </section>
+
+ <section xml:id="configure-pwd-storage">
+ <title>Configuring Password Storage</title>
+ <indexterm>
+ <primary>Passwords</primary>
+ <secondary>Storage schemes</secondary>
+ </indexterm>
+
+ <para>Password storage schemes encode new passwords provided by users so that
+ they are stored in an encoded manner. This makes it difficult or impossible
+ for someone to determine the clear-text passwords from the encoded
+ values. Password storage schemes also determine whether a clear-text password
+ provided by a client matches the encoded value stored in the server.</para>
+
+ <para>OpenDJ offers a variety of both reversible and one-way password storage
+ schemes. Some schemes make it easy to recover the clear-text password,
+ whereas others aim to make it computationally hard to do so.</para>
+
+ <screen>$ dsconfig
+ list-password-storage-schemes
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+
+Password Storage Scheme : Type : enabled
+------------------------:---------------:--------
+3DES : triple-des : true
+AES : aes : true
+Base64 : base64 : true
+Blowfish : blowfish : true
+Clear : clear : true
+CRYPT : crypt : true
+MD5 : md5 : true
+PBKDF2 : pbkdf2 : true
+RC4 : rc4 : true
+Salted MD5 : salted-md5 : true
+Salted SHA-1 : salted-sha1 : true
+Salted SHA-256 : salted-sha256 : true
+Salted SHA-384 : salted-sha384 : true
+Salted SHA-512 : salted-sha512 : true
+SHA-1 : sha1 : true</screen>
+
+ <para>As shown in <xref linkend="default-pwp" />, the default password storage
+ scheme for users in Salted SHA-1. When you add users or import user entries
+ with <literal>userPassword</literal> values in clear text, OpenDJ hashes them
+ with the default password storage scheme. Root DN users have a different
+ password policy by default, shown in <xref linkend="assign-pwp-to-group" />.
+ The Root Password Policy uses Salted SHA-512 by default.</para>
+
+ <para>You change the default password policy storage scheme for users by
+ changing the applicable password policy, as shown in the following
+ example.</para>
+
+ <screen>$ dsconfig
+ set-password-policy-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set default-password-storage-scheme:pbkdf2
+ --no-prompt</screen>
+
+ <para>Notice that the change in default password storage scheme does not
+ cause OpenDJ to update any stored password values. By default, OpenDJ only
+ stores a password with the new storage scheme the next time that the password
+ is changed.</para>
+
+ <para>OpenDJ prefixes passwords with the scheme used to encode them, which
+ means it is straightforward to see which password storage scheme is in use.
+ After the default password storage scheme is changed to PBKDF2, old user
+ passwords remain encoded with Salted SHA-1.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN uid=bjensen,ou=people,dc=example,dc=com
+ --bindPassword hifalutin
+ --baseDN dc=example,dc=com
+ "(uid=bjensen)" userPassword
+dn: uid=bjensen,ou=People,dc=example,dc=com
+userPassword: {SSHA}Rc3tkAj1qP5zGiRkwDIWDFxrxpGgO8Fwh3aibg==</screen>
+
+ <para>When the password is changed, the new default password storage scheme
+ takes effect, as shown in the following example.</para>
+
+ <screen>$ ldappasswordmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --authzID "u:bjensen"
+ --newPassword changeit
+The LDAP password modify operation was successful
+$ ldapsearch
+ --port 1389
+ --bindDN uid=bjensen,ou=people,dc=example,dc=com
+ --bindPassword changeit
+ --baseDN dc=example,dc=com
+ "(uid=bjensen)" userPassword
+dn: uid=bjensen,ou=People,dc=example,dc=com
+userPassword: {PBKDF2}10000:O3V6G7y7n7AefOkRGNKQ5ukrMuO5uf+iEQ9ZLg==</screen>
+
+ <para>When you change the password storage scheme for users, realize that
+ the user passwords must change in order for OpenDJ to encode them with
+ the chosen storage scheme. If you are changing the storage scheme because
+ the old scheme was too weak, then you no doubt want users to change their
+ passwords anyway.</para>
+
+ <para>If however the storage scheme change is not related to vulnerability,
+ you can use the <literal>deprecated-password-storage-scheme</literal>
+ property of the password policy to have OpenDJ store the password in the new
+ format after successful authentication. This makes it possible to do password
+ migration for active users without forcing users to change their
+ passwords.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN uid=kvaughan,ou=people,dc=example,dc=com
+ --bindPassword bribery
+ --baseDN dc=example,dc=com
+ "(uid=kvaughan)" userPassword
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+userPassword: {SSHA}hDgK44F2GhIIZj913b+29Ak7phb9oU3Lz4ogkg==
+
+$ dsconfig
+ set-password-policy-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set deprecated-password-storage-scheme:"Salted SHA-1"
+ --no-prompt
+$ ldapsearch
+ --port 1389
+ --bindDN uid=kvaughan,ou=people,dc=example,dc=com
+ --bindPassword bribery
+ --baseDN dc=example,dc=com
+ "(uid=kvaughan)" userPassword
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+userPassword: {PBKDF2}10000:L4dCYqSsNnf47YZ3a6aC8K2E3DChhHHhpcoUzg==</screen>
+
+ <para>Notice that with <literal>deprecated-password-storage-scheme</literal>
+ set appropriately, Kirsten Vaughan's password was hashed again after she
+ authenticated successfully.</para>
+ </section>
+
+ <section xml:id="configure-pwd-validation">
+ <title>Configuring Password Validation</title>
+ <indexterm>
+ <primary>Passwords</primary>
+ <secondary>Validating</secondary>
+ </indexterm>
+
+ <para>Password validators are responsible for determining whether a proposed
+ password is acceptable for use and can run checks like ensuring the password
+ meets minimum length requirements, that it has an appropriate range of
+ characters, or that it is not in the history. OpenDJ directory server
+ provides a variety of password validators.</para>
+
+ <screen>$ dsconfig
+ list-password-validators
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+
+
+Password Validator : Type : enabled
+------------------------------------:---------------------:--------
+Attribute Value : attribute-value : true
+Character Set : character-set : true
+Dictionary : dictionary : false
+Length-Based Password Validator : length-based : true
+Repeated Characters : repeated-characters : true
+Similarity-Based Password Validator : similarity-based : true
+Unique Characters : unique-characters : true</screen>
+
+ <para>The password policy for a user specifies the set of password validators
+ that should be used whenever that user provides a new password. By default
+ no password validators are configured. You can see an example setting the
+ Default Password Policy to use the Dictionary validator in
+ <xref linkend="default-pwp" />. The following example shows how to set up
+ a custom password validator and assign it to the default password
+ policy.</para>
+
+ <itemizedlist>
+ <para>The custom password validator ensures passwords meet at least three of
+ the following four criteria. Passwords are composed of:</para>
+
+ <listitem>
+ <para>English lowercase characters (a through z)</para>
+ </listitem>
+
+ <listitem>
+ <para>English uppercase characters (A through Z)</para>
+ </listitem>
+
+ <listitem>
+ <para>Base 10 digits (0 through 9)</para>
+ </listitem>
+
+ <listitem>
+ <para>Non-alphabetic characters (for example, !, $, #, %)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Notice how the <literal>character-set</literal> values are constructed.
+ The initial <literal>0:</literal> means the set is optional, whereas
+ <literal>1:</literal> would mean the set is required.</para>
+
+ <screen>$ dsconfig
+ create-password-validator
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --validator-name "Custom Character Set Password Validator"
+ --set allow-unclassified-characters:true
+ --set enabled:true
+ --set character-set:0:abcdefghijklmnopqrstuvwxyz
+ --set character-set:0:ABCDEFGHIJKLMNOPQRSTUVWXYZ
+ --set character-set:0:0123456789
+ --set character-set:0:!\"#\$%&\'\(\)*+,-./:\;\\<=\>?@[\\]^_\`{\|}~
+ --set min-character-sets:3
+ --type character-set
+ --no-prompt
+
+$ dsconfig
+ set-password-policy-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --policy-name "Default Password Policy"
+ --set password-validator:"Custom Character Set Password Validator"
+ --no-prompt
+
+$ ldappasswordmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --authzID "u:bjensen"
+ --newPassword '!ABcd$%^'</screen>
+
+ <para>In the preceding example, the character set of ASCII punctuation,
+ <literal>!\"#\$%&\'\(\)*+,-./:\;\\<=\>?@[\\]^_\`{\|}~</literal>,
+ is hard to read because of all the escape characters. In practice it can
+ be easier to enter sequences like that by using <command>dsconfig</command>
+ in interactive mode, and letting it do the escaping for you. You can also
+ use the <option>--commandFilePath {path}</option> option to save the result
+ of your interactive session to a file for use in scripts later.</para>
+
+ <para>An attempt to set an invalid password fails as shown in the following
+ example.</para>
+
+ <screen>$ ldappasswordmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --authzID "u:bjensen"
+ --newPassword hifalutin
+ The LDAP password modify operation failed with result code 19
+Error Message: The provided new password failed the validation checks defined
+in the server: The provided password did not contain characters from at least
+3 of the following character sets or ranges: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+'!"#$%&'()*+,-./:;<=\>?@[\]^_`{|}~', '0123456789', 'abcdefghijklmnopqrstuvwxyz'</screen>
+
+ <para>Validation does not affect existing passwords, but only takes effect
+ when the password is updated.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-referrals.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-referrals.xml
new file mode 100644
index 0000000..a42044b
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-referrals.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-referrals'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Working With Referrals</title>
+ <indexterm><primary>Referrals</primary></indexterm>
+
+ <para><firstterm>Referrals</firstterm> point directory clients to another
+ directory container, which can be another directory server running elsewhere,
+ or another container on the same server. The client receiving a referral must
+ then connect to the other container to complete the request.</para>
+
+ <note>
+ <para>Some clients follow referrals on your behalf by default. The OpenDJ
+ <command>ldapsearch</command> command does not follow referrals.</para>
+ </note>
+
+ <para>Referrals are used for example when a some directory data are temporarily
+ unavailable due to maintenance. Referrals can also be used when a container
+ holds only some of the directory data for a suffix and points to other
+ containers for branches whose data is not available locally.</para>
+
+ <para>This chapter demonstrates how to add and remove referrals with the
+ <command>ldapmodify</command> command. You can also use the Manage Entries
+ window of the Control Panel to handle referrals.</para>
+
+ <section xml:id="referrals-overview">
+ <title>About Referrals</title>
+
+ <para>Referrals are implemented as entries with <link
+ xlink:href="http://tools.ietf.org/html/rfc4516">LDAP URL</link>
+ <literal>ref</literal> attribute values that point elsewhere. The
+ <literal>ref</literal> attribute type is required by the
+ <literal>referral</literal> object class. The <literal>referral</literal>
+ object class is structural, however, and therefore cannot by default be added
+ to an entry that already has a structural object class defined. When adding
+ a <literal>ref</literal> attribute type to an existing entry, you can use
+ the <literal>extensibleObject</literal> auxiliary object class.</para>
+
+ <para>When a referral is set, OpenDJ returns the referral to client
+ applications requesting the entry or child entries affected. Client
+ applications must be capable of following the referral returned. When the
+ directory server responds for example to your search with referrals to one
+ or more LDAP URLs, your client then constructs new searches from the LDAP
+ URLs returned, and tries again.</para>
+ </section>
+
+ <section xml:id="managing-referrals">
+ <title>Managing Referrals</title>
+
+ <para>To create an LDAP referral either you create a referral entry, or
+ you add the <literal>extensibleObject</literal> object class and the
+ <literal>ref</literal> attribute with an LDAP URL to an existing entry.
+ This section demonstrates use of the latter approach.</para>
+
+ <screen>$ cat referral.ldif
+dn: ou=People,dc=example,dc=com
+changetype: modify
+add: objectClass
+objectClass: extensibleObject
+-
+add: ref
+ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename referral.ldif
+Processing MODIFY request for ou=People,dc=example,dc=com
+MODIFY operation successful for DN ou=People,dc=example,dc=com</screen>
+
+ <para>The example above adds a referral to
+ <literal>ou=People,dc=example,dc=com</literal>. OpenDJ can now return
+ a referral for operations under the People organizational unit.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description
+
+SearchReference(referralURLs=
+ {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})
+
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people
+
+SearchReference(referralURLs=
+ {ldap://opendj.example.com:2389/ou=People,dc=example,dc=com??sub?})</screen>
+
+ <para>To access the entry instead of the referral, use the Manage DSAIT
+ control.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ --control ManageDSAIT:true
+ ou=people
+ ref
+dn: ou=People,dc=example,dc=com
+ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com
+
+$ cat people.ldif
+dn: ou=People,dc=example,dc=com
+changetype: modify
+delete: ref
+ref: ldap://opendj.example.com:2389/ou=People,dc=example,dc=com
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename people.ldif
+Processing MODIFY request for ou=People,dc=example,dc=com
+MODIFY operation successful for DN ou=People,dc=example,dc=com
+A referral entry ou=People,dc=example,dc=com indicates that the operation must
+ be processed at a different server
+[ldap://opendj.example.com:2389/ou=People,dc=example,dc=com]
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --control ManageDSAIT
+ --filename people.ldif
+Processing MODIFY request for ou=People,dc=example,dc=com
+MODIFY operation successful for DN ou=People,dc=example,dc=com
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com ou=people
+dn: ou=People,dc=example,dc=com
+ou: People
+objectClass: organizationalunit
+objectClass: extensibleObject
+objectClass: top</screen>
+
+ <para>The example above shows how to remove the referral using the Manage
+ DSAIT control with the <command>ldapmodify</command> command.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-replication.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-replication.xml
new file mode 100644
index 0000000..c4e23e3
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-replication.xml
@@ -0,0 +1,1520 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-replication'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Managing Data Replication</title>
+
+ <para>OpenDJ uses advanced data replication with automated conflict
+ resolution to help ensure your directory services remain available in the
+ event a server crashes or a network goes down, and also as you backup or
+ upgrade your directory service. You can configure data replication as part
+ of OpenDJ installation, and in many cases let replication do its work in
+ the background.</para>
+
+ <section xml:id="repl-quick-setup">
+ <title>Replication Quick Setup</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Quick setup</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>High availability</primary>
+ <see>Replication</see>
+ </indexterm>
+
+ <para>You can set up replication during installation by choosing to
+ configure replication through the setup wizard.</para>
+
+ <para>In the Topology Options screen for the first server you set up, select
+ This server will be part of a replication topology. If you also choose
+ Configure as Secure, then replication traffic is protected by SSL.</para>
+
+ <mediaobject xml:id="figure-repla-setup">
+ <imageobject>
+ <imagedata fileref="images/replA-setup.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>QuickSetup makes it easy to configure replication.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>In the Topology Options screen for subsequent servers, also select
+ There is already a server in the topology, providing the Host Name,
+ Administration Connector Port number, Admin User, and Admin Password for
+ the first replica you set up.</para>
+
+ <mediaobject xml:id="figure-replb-setup">
+ <imageobject>
+ <imagedata fileref="images/replB-setup.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>Subsequent servers can point to the first server at setup time.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>You also set up a global administrator account, stored under
+ <literal>cn=admin data</literal> across replicas, used to manage replication
+ in the topology.</para>
+
+ <mediaobject xml:id="figure-replb-global-admin">
+ <imageobject>
+ <imagedata fileref="images/replB-global-admin.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>The global administrator account exists on all servers in the
+ replication topology.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>You further set up what to replicate.</para>
+
+ <mediaobject xml:id="figure-replb-data-repl">
+ <imageobject>
+ <imagedata fileref="images/replB-data-repl.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>You choose the user data to replicate. OpenDJ automatically replicates
+ administrative data and directory schema.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>Once replication is set up, it works for all the replicas. You can
+ monitor the replication connection and status through the OpenDJ Control
+ Panel.</para>
+
+ <mediaobject xml:id="figure-repla-monitor-repl">
+ <imageobject>
+ <imagedata fileref="images/replA-monitor-repl.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>OpenDJ Control Panel indicates the status of data being
+ replicated.</para>
+ </textobject>
+ </mediaobject>
+
+ </section>
+
+ <section xml:id="about-repl">
+ <title>About Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Overview</secondary>
+ </indexterm>
+
+ <para>Before you take replication further than setting up replication
+ in the setup wizard, read this section to learn more about how OpenDJ
+ replication works.</para>
+
+ <section xml:id="repl-what-it-is">
+ <title>What Replication Is</title>
+
+ <para>Replication is the process of copying updates between OpenDJ
+ directory servers such that all servers converge on identical copies of
+ directory data. Replication is designed to let convergence happen over
+ time by default. <footnote><para>Assured replication can require, however,
+ that the convergence happen before the client application is notified that
+ the operation was successful.</para></footnote> Letting convergence
+ happen over time means that different replicas can be momentarily out of
+ sync, but it also means that if you lose an individual server or even an
+ entire data center, your directory service can keep on running, and then
+ get back in sync when the servers are restarted or the network is
+ repaired.</para>
+
+ <para>Replication is specific to the OpenDJ directory service. Replication
+ uses a specific protocol that replays update operations quickly, storing
+ enough historical information about the updates to resolve most conflicts
+ automatically. For example, if two client applications separately update
+ a user entry to change the phone number, replication can work out which
+ was the latest change, and apply that change across servers. The historical
+ information needed to resolve these issues is periodically purged to avoid
+ growing larger and larger forever. As a directory administrator, you must
+ ensure that you do not purge the historical information more often than you
+ backup your directory data.</para>
+
+ <para>Keep server clocks synchronized for your topology. You can use NTP for
+ example. Keeping server clocks synchronized helps prevent issues with SSL
+ connections and with replication itself. Keeping server clocks synchronized
+ also makes it easier to compare timestamps from multiple servers.</para>
+ </section>
+
+ <section xml:id="repl-per-suffix">
+ <title>Replication Per Suffix</title>
+
+ <para>The primary unit of replication is the suffix, specified by a
+ base DN such as <literal>dc=example,dc=com</literal>.<footnote><para>When
+ you configure partial and fractional replication, however, you can replicate
+ only part of a suffix, or only certain attributes on entries. Also,
+ if you split your suffix across multiple backends, then you need to set up
+ replication separately for each part of suffix in a different backend.</para>
+ </footnote> Replication also depends on the directory schema, defined on
+ <literal>cn=schema</literal>, and the <literal>cn=admin data</literal>
+ suffix with administrative identities and certificates for protecting
+ communications. Thus that content gets replicated as well.</para>
+
+ <para>The set of OpenDJ servers replicating data for a given suffix is
+ called a replication topology. You can have more than one replication
+ topology. For example, one topology could be devoted to
+ <literal>dc=example,dc=com</literal>, and another to
+ <literal>dc=example,dc=org</literal>. OpenDJ servers are capable of
+ serving more than one suffix. They are also capable of participating in
+ more than one replication topology.</para>
+
+ <mediaobject xml:id="figure-replication-topologies-right">
+ <alt>Three replication topologies set up correctly</alt>
+ <imageobject>
+ <imagedata fileref="images/repl-topologies-right.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>In this figure, all OpenDJ servers serve the replicated suffix
+ <literal>dc=example,dc=com</literal>. Only servers A and B serve
+ <literal>dc=example,dc=org</literal>. Only server C and D serve
+ <literal>dc=example,dc=net</literal>.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>Within a replication topology, the suffixes being replicated are
+ identified to the replication servers by their DN. As all the replication
+ servers are fully connected in a topology, a consequence is that it is
+ impossible to have multiple "sub-topologies" within the overall set of
+ servers as illustrated in the following diagram.</para>
+
+ <mediaobject xml:id="figure-replication-topologies-wrong">
+ <alt>Two replication topologies, one of which does not work</alt>
+ <imageobject>
+ <imagedata fileref="images/repl-topologies-wrong.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>You cannot have all servers replicating both
+ <literal>dc=example,dc=com</literal> and also
+ <literal>dc=example,dc=org</literal>, but with all servers connected for
+ <literal>dc=example,dc=com</literal> and only some of the servers
+ connected for <literal>dc=example,dc=org</literal>.</para>
+ </textobject>
+ </mediaobject>
+ </section>
+
+ <section xml:id="repl-connection-selection">
+ <title>Replication Connection Selection</title>
+
+ <para>In order to understand what happens when individual servers stop
+ responding due to a network partition or a crash, know that OpenDJ can
+ offer both directory service and also replication service, and the two
+ services are not the same, even if they can run alongside each other in
+ the same OpenDJ server in the same Java Virtual Machine.</para>
+
+ <para>Replication relies on the replication service provided by OpenDJ
+ replication servers, where OpenDJ directory servers publish changes made
+ to their data, and subscribe to changes published by other OpenDJ directory
+ servers. A replication server manages replication data only, handling
+ replication traffic with directory servers and with other replication
+ servers, receiving, sending, and storing only changes to directory data
+ rather than directory data itself. Once a replication server is connected
+ to a replication topology, it maintains connections to all other
+ replication servers in that topology.</para>
+
+ <para>A directory server handles directory data. It responds to requests,
+ stores directory data and historical information. For each replicated
+ suffix, such as <literal>dc=example,dc=com</literal>,
+ <literal>cn=schema</literal> and <literal>cn=admin data</literal>, the
+ directory server publishes changes to a replication server, and subscribes
+ to changes from that replication server. (Directory servers do not publish
+ changes to other directory servers.) A directory server also resolves any
+ conflicts that arise when reconciling changes from other directory servers,
+ using the historical information about changes to resolve the conflicts.
+ (Conflict resolution is the responsibility of the directory server rather
+ than the replication server.)</para>
+
+ <para>Once a directory server is connected to a replication topology for a
+ particular suffix, it connects to one replication server at a time for that
+ suffix. The replication server provides the directory server with a list of
+ all replication servers for that suffix. Given the list of possible
+ replication servers to which it can connect, the directory server can
+ determine which replication server to connect to when starting up, or when
+ the current connection is lost or becomes unresponsive.</para>
+
+ <orderedlist>
+ <para>For each replicated suffix, a directory server prefers to connect to
+ a replication server:</para>
+
+ <listitem>
+ <para>In the same group as the directory server</para>
+ </listitem>
+
+ <listitem>
+ <para>Having the same initial data for the suffix as the directory
+ server</para>
+ </listitem>
+
+ <listitem>
+ <para>If initial data were the same, having all the latest changes from
+ the directory server</para>
+ </listitem>
+
+ <listitem>
+ <para>Running in the same Java Virtual Machine as the directory
+ server</para>
+ </listitem>
+
+ <listitem>
+ <para>Having the most available capacity relative to other eligible
+ replication servers</para>
+
+ <para>Available capacity depends on how many directory servers in the
+ topology are already connected to a replication server, and what
+ proportion of all directory servers in the topology ought to be connected
+ to the replication server.</para>
+
+ <para>To determine what proportion of the total number of directory
+ servers should be connected to a replication server, OpenDJ uses
+ replication server weight. When configuring a replication server, you
+ can assign it a weight (default: 1). The weight property takes an integer
+ that indicates capacity to provide replication service relative to other
+ servers. For example, a weight of 2 would indicate a replication server
+ that can handle twice as many connected servers as a replication server
+ with weight 1.</para>
+
+ <para>The proportion of directory servers in a topology that should be
+ connected to a given replication server is equal to (replication server
+ weight)/(sum of replication server weights). In other words, if there are
+ 4 replication servers in a topology each with default weights, the
+ proportion for each replication server is 1/4.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Consider a situation where 7 directory servers are connected to
+ replication servers A, B, C, and D for <literal>dc=example,dc=com</literal>
+ data. Suppose 2 directory servers each are connected to A, B, and C, and 1
+ directory server is connected to replication server D. Replication server D
+ is therefore the server with the most available capacity relative to other
+ replication servers in the topology. All other criteria being equal,
+ replication server D is the server to connect to when an 8th directory
+ server joins the topology.</para>
+
+ <para>The directory server regularly updates the list of replication servers
+ in case it must reconnect. As available capacity of replication servers for
+ each replication topology can change dynamically, a directory server can
+ potentially reconnect to another replication server to balance the
+ replication load in the topology. For this reason the server can also end
+ up connected to different replication servers for different suffixes.</para>
+ </section>
+ </section>
+
+ <section xml:id="configure-repl">
+ <title>Configuring Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Configuring</secondary>
+ </indexterm>
+
+ <para>This section shows how to configure replication with command-line
+ tools.</para>
+
+ <section xml:id="enable-repl">
+ <title>Enabling Replication</title>
+
+ <para>You can start the replication process by using the
+ <command>dsreplication enable</command> command.</para>
+
+ <screen>$ dsreplication
+ enable
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --host1 opendj.example.com
+ --port1 4444
+ --bindDN1 "cn=Directory Manager"
+ --bindPassword1 password
+ --replicationPort1 8989
+ --host2 opendj2.example.com
+ --port2 4444
+ --bindDN2 "cn=Directory Manager"
+ --bindPassword2 password
+ --replicationPort2 8989
+ --trustAll
+ --no-prompt
+
+Establishing connections ..... Done.
+Checking registration information ..... Done.
+Updating remote references on server opendj.example.com:4444 ..... Done.
+Configuring Replication port on server opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj2.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj2.example.com:4444 ..... Done.
+Initializing registration information on server opendj2.example.com:4444 with
+ the contents of server opendj.example.com:4444 ..... Done.
+Initializing schema on server opendj2.example.com:4444 with the contents of
+ server opendj.example.com:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to
+ work you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-7958637258600693490.log
+for a detailed log of this operation.</screen>
+
+ <para>To enable secure connections for replication use the
+ <option>--secureReplication1</option> and
+ <option>--secureReplication2</option> options, which are equivalent to
+ selecting Configure as Secure in the replication topology options screen of
+ the setup wizard.</para>
+
+ <para>As you see in the command output, replication is set up to function
+ once enabled. You must however initialize replication in order to start
+ the process.</para>
+
+ <tip>
+ <para>When scripting the configuration to set up multiple replicas in quick
+ succession, use the same initial replication server each time you run the
+ command. In other words, pass the same <option>--host1</option>,
+ <option>--port1</option>, <option>--bindDN1</option>,
+ <option>--bindPassword1</option>, and <option>--replicationPort1</option>
+ options for each of the other replicas that you set up in your
+ script.</para>
+ </tip>
+
+ <para>If you need to add another OpenDJ directory server to participate
+ in replication, use the <command>dsreplication enable</command> with
+ the new server as the second server.</para>
+ </section>
+
+ <section xml:id="init-repl">
+ <title>Initializing Replicas</title>
+
+ <para>You can initialize replication between servers by performing
+ initialization over the network after you have enabled replication, or by
+ importing the same LDIF data on all servers and then enabling replication.
+ You can also add a new server by restoring a backup from an existing replica
+ onto the new server and then enabling replication with an existing
+ replica.</para>
+
+ <itemizedlist>
+ <para>The alternatives are described step-by-step in the following
+ procedures.</para>
+
+ <listitem><para><xref linkend="init-repl-online" /></para></listitem>
+ <listitem><para><xref linkend="init-repl-ldif" /></para></listitem>
+ <listitem><para><xref linkend="init-repl-backup" /></para></listitem>
+ </itemizedlist>
+
+ <procedure xml:id="init-repl-online">
+ <title>To Initialize Replication Over the Network</title>
+
+ <para>Initialization over the network while the server is online works well
+ when you have no initial data, or when your network bandwidth is large
+ compared to the initial amount of data to replicate.</para>
+
+ <step>
+ <para>Enable replication on all servers.</para>
+
+ <para>See <xref linkend="enable-repl" /> for instructions.</para>
+ </step>
+
+ <step>
+ <para>Start replication with the <command>dsreplication
+ initialize-all</command> command.</para>
+
+ <screen>$ dsreplication
+ initialize-all
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --hostname opendj.example.com
+ --port 4444
+ --trustAll
+ --no-prompt
+
+Initializing base DN dc=example,dc=com with the contents from
+ opendj.example.com:4444: 160 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-5020375834904394170.log
+for a detailed log of this operation.</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="init-repl-ldif">
+ <title>To Initialize All Servers From the Same LDIF</title>
+
+ <para>This procedure can be useful when you are starting with a large amount
+ of directory data that is available locally to all directory servers.</para>
+
+ <step>
+ <para>Import the same LDIF on all servers as described in the procedure,
+ <link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#import-ldif"><citetitle>To Import LDIF
+ Data</citetitle></link>.</para>
+
+ <para>Do not yet accept updates to the directory data.
+ <xref linkend="read-only-repl" /> shows how to prevent replicas from
+ accepting updates from clients.</para>
+ </step>
+
+ <step>
+ <para>Enable replication for all servers.</para>
+
+ <para>See <xref linkend="enable-repl" /> for instructions.</para>
+ </step>
+
+ <step>
+ <para>Allow updates to the directory data by setting
+ <literal>writability-mode:enabled</literal> using a command like the
+ one you found in <xref linkend="read-only-repl" />.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="init-repl-backup">
+ <title>To Create a New Replica From Existing Backup</title>
+
+ <para>You can create a new replica from a backup of a server in the existing
+ topology.</para>
+
+ <step>
+ <para>Install a new server to use as the new replica.</para>
+ </step>
+
+ <step>
+ <para>Backup the database on an existing server as described in
+ <link xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#backup"><citetitle>Backing Up Directory
+ Data</citetitle></link>.</para>
+
+ <para>At this point, other servers in the topology can continue to process
+ updates.</para>
+ </step>
+
+ <step>
+ <para>Enable replication on the new replica.</para>
+
+ <screen>$ dsreplication
+ enable
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --host1 opendj.example.com
+ --port1 4444
+ --bindDN1 "cn=Directory Manager"
+ --bindPassword1 password
+ --replicationPort1 8989
+ --host2 opendj3.example.com
+ --port2 4444
+ --bindDN2 "cn=Directory Manager"
+ --bindPassword2 password
+ --replicationPort2 8989
+ --trustAll
+ --no-prompt
+
+Establishing connections ..... Done.
+Checking registration information ..... Done.
+Updating remote references on server opendj.example.com:4444 ..... Done.
+Configuring Replication port on server opendj3.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj3.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj2.example.com:4444 ..... Done.
+Updating remote references on server opendj2.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj3.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj3.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj2.example.com:4444 ..... Done.
+Initializing registration information on server opendj3.example.com:4444 with
+ the contents of server opendj.example.com:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to
+ work you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-1672058070147419978.log
+for a detailed log of this operation.</screen>
+
+ <para>Contrary to the message from the command, you do not need to use
+ the <command>dsreplication initialize</command> command at this
+ point.</para>
+ </step>
+
+ <step>
+ <para>On the new server, restore the database from the backup
+ archive as described in the procedure, <link xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#restore-replica"><citetitle>To Restore a
+ Replica</citetitle></link>.</para>
+
+ <para>As long as you restore the database on the new replica before the
+ replication purge delay runs out, updates processed by other servers after
+ you created the backup are replicated to the new server after you restore
+ the data.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="stop-repl">
+ <title>Stopping Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Stopping</secondary>
+ </indexterm>
+
+ <para>How you stop replication depends on whether the change is meant to
+ be temporary or permanent.</para>
+
+ <procedure xml:id="stop-repl-tmp">
+ <title>To Stop Replication Temporarily For a Replica</title>
+
+ <para>If you need to stop a server from replicating temporarily, you can
+ do so using <command>dsconfig</command> command.</para>
+
+ <warning>
+ <para>Do not allow modifications on the replica for which replication is
+ disabled, as no record of such changes is kept, and the changes cause
+ replication to diverge.</para>
+ </warning>
+
+ <step>
+ <para>Disable the multimaster synchronization provider.</para>
+ <screen>$ dsconfig
+ set-synchronization-provider-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --set enabled:false
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step performance="optional">
+ <para>When you are ready to resume replication, enable the multimaster
+ synchronization provider.</para>
+ <screen>$ dsconfig
+ set-synchronization-provider-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="stop-repl-permanent">
+ <title>To Stop Replication Permanently For a Replica</title>
+
+ <para>If you need to stop a server from replicating permanently, for
+ example in preparation to remove a server, you can do so with the
+ <command>dsreplication disable</command> command.</para>
+
+ <step>
+ <para>Stop replication using the <command>dsreplication disable</command>
+ command.</para>
+ <screen>$ dsreplication
+ disable
+ --disableAll
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --adminPassword password
+ --trustAll
+ --no-prompt
+Establishing connections ..... Done.
+Disabling replication on base DN cn=admin data of server
+ opendj2.example.com:4444 ..... Done.
+Disabling replication on base DN dc=example,dc=com of server
+ opendj2.example.com:4444 ..... Done.
+Disabling replication on base DN cn=schema of server
+ opendj2.example.com:4444 ..... Done.
+Disabling replication port 8989 of server
+ opendj2.example.com:4444 ..... Done.
+Removing registration information ..... Done.
+Removing truststore information ..... Done.
+
+See
+/var/.../opends-replication-125248191132797765.log
+for a detailed log of this operation.</screen>
+ <para>The <command>dsreplication disable</command> as shown completely
+ removes the replication configuration information from the server.</para>
+ </step>
+ <step performance="optional">
+ <para>If you want to restart replication for the server, you need to run
+ the <command>dsreplication enable</command> and <command>dsreplication
+ initialize</command> commands again.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="repl-dedicated-servers">
+ <title>Stand-alone Replication Servers</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Dedicated servers</secondary>
+ </indexterm>
+
+ <para>Replication in OpenDJ is designed to be both easy to implement in
+ environments with a few servers, and also scalable in environments with
+ many servers. You can enable the replication service on each OpenDJ
+ directory server in your deployment, for example, to limit the number
+ of servers you deploy. Yet in a large deployment, you can use stand-alone
+ replication servers — OpenDJ servers that do nothing but relay
+ replication messages — to configure (and troubleshoot) the replication
+ service separately from the directory service. You only need a few
+ stand-alone replication servers publishing changes to serve many directory
+ servers subscribed to the changes. Furthermore, replication is designed
+ such that you need only connect a directory server to the nearest
+ replication server for the directory server to replicate with all others
+ in your topology. Yet only the stand-alone replication servers participate
+ in fully-meshed replication.</para>
+
+
+ <para>All replication servers in a topology are connected to all other
+ replication servers. Directory servers are connected only to one replication
+ server at a time, and their connections should be to replication servers on
+ the same LAN. Therefore the total number of replication connections,
+ Total<subscript>conn</subscript> is expressed as follows.</para>
+
+ <equation>
+ <mathphrase>Total<subscript>conn</subscript> = (N<subscript>RS</subscript> *
+ N<subscript>RS</subscript>-1)/2 + N<subscript>DS</subscript></mathphrase>
+ </equation>
+
+ <para>Here, N<subscript>RS</subscript> is the number of replication servers,
+ and N<subscript>DS</subscript> is the number of stand-alone directory
+ servers. In other words, if you have only 3 servers, then
+ Total<subscript>conn</subscript> is 3 with no stand-alone servers.
+ However, if you have two data centers, and need 12 directory servers, then
+ with no stand-alone directory servers Total<subscript>conn</subscript> is
+ (12 * 11)/2 or 66. Yet, with 4 stand-alone replication servers, and 12
+ stand-alone directory servers, Total<subscript>conn</subscript> is
+ (4 * 3)/2 + 12, or 18, with only four of those connections needing to go
+ over the WAN. (By running four directory servers that also run replication
+ servers and eight stand-alone directory servers, you reduce the number of
+ replication connections to 14 for 12 replicas.)</para>
+
+ <mediaobject xml:id="figure-standalone-repl">
+ <alt>Dedicated servers versus consolidated instances</alt>
+ <imageobject>
+ <imagedata fileref="images/standalone-repl.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <para>Dedicated servers are suited to environments with large numbers
+ of replicas.</para>
+ </textobject>
+ </mediaobject>
+
+ <tip>
+ <para>If you set up OpenDJ directory server to replicate by using the
+ Quick Setup wizard, then the wizard activated the replication service for
+ that server. You can turn off the replication service on OpenDJ directory
+ server, and then configure the server to work with a separate, stand-alone
+ replication server instead. Start by using the <command>dsreplication
+ disable --disableReplicationServer</command> command to turn off the
+ replication service on the server.</para>
+ </tip>
+
+ <procedure xml:id="repl-setup-dedicated-server">
+ <title>To Set Up a Stand-alone Replication Server</title>
+
+ <para>This example sets up a stand-alone replication server to handle
+ the replication traffic between two directory servers that do not
+ handle replication themselves.</para>
+
+ <para>Here the replication server is <literal>rs.example.com</literal>. The
+ directory servers are <literal>opendj.example.com</literal> and
+ <literal>opendj2.example.com</literal>.</para>
+
+ <para>In a real deployment, you would have more replication servers
+ to avoid a single point of failure.</para>
+
+ <step>
+ <para>Setup the replication server as a directory server that has
+ no database.</para>
+ </step>
+ <step>
+ <para>Setup the directory servers as stand-alone directory servers.</para>
+ </step>
+ <step>
+ <para>Enable replication with the appropriate
+ <option>--noReplicationServer</option> and
+ <option>--onlyReplicationServer</option> options.</para>
+ <screen>$ dsreplication
+ enable
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --host1 opendj.example.com
+ --port1 4444
+ --bindDN1 "cn=Directory Manager"
+ --bindPassword1 password
+ --noReplicationServer1
+ --host2 rs.example.com
+ --port2 4444
+ --bindDN2 "cn=Directory Manager"
+ --bindPassword2 password
+ --replicationPort2 8989
+ --onlyReplicationServer2
+ --trustAll
+ --no-prompt
+Establishing connections ..... Done.
+Only one replication server will be defined for the following base DN's:
+dc=example,dc=com
+It is recommended to have at least two replication servers (two changelogs) to
+avoid a single point of failure in the replication topology.
+
+Checking registration information ..... Done.
+Configuring Replication port on server rs.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ rs.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj.example.com:4444 ..... Done.
+Initializing registration information on server rs.example.com:4444 with
+ the contents of server opendj.example.com:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to work
+ you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-1720959352638609971.log
+for a detailed log of this operation.
+
+$ dsreplication
+ enable
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --host1 opendj2.example.com
+ --port1 4444
+ --bindDN1 "cn=Directory Manager"
+ --bindPassword1 password
+ --noReplicationServer1
+ --host2 rs.example.com
+ --port2 4444
+ --bindDN2 "cn=Directory Manager"
+ --bindPassword2 password
+ --replicationPort2 8989
+ --onlyReplicationServer2
+ --trustAll
+ --no-prompt
+
+Establishing connections ..... Done.
+Only one replication server will be defined for the following base DN's:
+dc=example,dc=com
+It is recommended to have at least two replication servers (two changelogs) to
+avoid a single point of failure in the replication topology.
+
+Checking registration information ..... Done.
+Updating remote references on server rs.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj2.example.com:4444 ..... Done.
+Updating registration configuration on server
+ rs.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj.example.com:4444 ..... Done.
+Initializing registration information on server opendj2.example.com:4444 with
+ the contents of server rs.example.com:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to work
+ you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/folders/.../opends-replication-5893037538856033562.log
+for a detailed log of this operation.</screen>
+ </step>
+ <step>
+ <para>Initialize replication from one of the directory servers.</para>
+ <screen>$ dsreplication
+ initialize-all
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --hostname opendj.example.com
+ --port 4444
+ --trustAll
+ --no-prompt
+
+Initializing base DN dc=example,dc=com with the contents from
+ opendj.example.com:4444: 160 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-7677303986403997574.log
+for a detailed log of this operation.</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="repl-groups">
+ <title>Replication Groups</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Grouping servers</secondary>
+ </indexterm>
+
+ <para>Replication lets you define groups so that replicas communicate
+ first with replication servers in the group before going to replication
+ servers outside the group. Groups are identified with unique numeric
+ group IDs.</para>
+
+ <para>Replication groups are designed for deployments across multiple data
+ centers, where you aim to focus replication traffic on the LAN rather than
+ the WAN. In multi-data center deployments, group nearby servers
+ together.</para>
+
+ <procedure xml:id="define-repl-groups">
+ <title>To Set Up Replication Groups</title>
+
+ <para>For each group, set the appropriate group ID for the topology
+ on both the replication servers and the directory servers.</para>
+
+ <para>The example commands in this procedure set up two replication
+ groups, each with a replication server and a directory server. The
+ directory servers are <literal>opendj.example.com</literal> and
+ <literal>opendj2.example.com</literal>. The replication servers
+ are <literal>rs.example.com</literal> and
+ <literal>rs2.example.com</literal>. In a full-scale deployment, you would
+ have multiple servers of each type in each group, such as all the replicas
+ and replication servers in each data center being in the same group.</para>
+
+ <step>
+ <para>Pick a group ID for each group.</para>
+ <para>The default group ID is 1.</para>
+ </step>
+ <step>
+ <para>Set the group ID for each group by replication domain on the
+ directory servers.</para>
+ <screen>$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set group-id:1
+ --trustAll
+ --no-prompt
+
+$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set group-id:2
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Set the group ID for each group on the replication servers.</para>
+ <screen>$ dsconfig
+ set-replication-server-prop
+ --port 4444
+ --hostname rs.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --set group-id:1
+ --trustAll
+ --no-prompt
+$ dsconfig
+ set-replication-server-prop
+ --port 4444
+ --hostname rs2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --set group-id:2
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="read-only-repl">
+ <title>Read-Only Replicas</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Read-only servers</secondary>
+ </indexterm>
+
+ <para>By default all directory servers in a replication topology are
+ read-write. You can however choose to make replicas take updates only
+ from the replication protocol, and refuse updates from client
+ applications.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set writability-mode:internal-only
+ --trustAll
+ --no-prompt</screen>
+ </section>
+
+ <section xml:id="repl-assured">
+ <title>Assured Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Assured</secondary>
+ </indexterm>
+
+ <para>In standard replication, when a client requests an update operation
+ the directory server performs the update and, if the update is successful,
+ sends information about the update to the replication service, and sends
+ a result code to the client application right away. As a result, the
+ client application can conclude that the update was successful,
+ <emphasis>but only on the replica that handled the update</emphasis>.</para>
+
+ <para>Assured replication lets you force the replica performing the initial
+ update to wait for confirmation that the update has been received elsewhere
+ in the topology before sending a result code to the client application.
+ You can configure assured replication either to wait for one or more
+ replication servers to acknowledge having received the update, or to wait
+ for all directory servers to have replayed the update.</para>
+
+ <para>As you might imagine, assured replication is theoretically safer than
+ standard replication, yet it is also slower, potentially waiting for a
+ timeout before failing when the network or other servers are down.</para>
+
+ <procedure xml:id="repl-safe-data">
+ <title>To Ensure Updates Reach Replication Servers</title>
+
+ <para>Safe data mode requires the update be sent to
+ <literal>assured-sd-level</literal> replication servers before
+ acknowledgement is returned to the client application.</para>
+
+ <step>
+ <para>For each directory server, set safe data mode for the replication
+ domain, and also set the safe data level.</para>
+
+ <screen>$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set assured-type:safe-data
+ --set assured-sd-level:1
+ --trustAll
+ --no-prompt
+
+$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set assured-type:safe-data
+ --set assured-sd-level:1
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="repl-safe-read">
+ <title>To Ensure Updates Are Replayed Everywhere</title>
+
+ <para>Safe read mode requires the update be replayed on all directory
+ servers before acknowledgement is returned to the client application.</para>
+
+ <step>
+ <para>For each directory server, set safe read mode for the replication
+ domain.</para>
+
+ <screen>$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set assured-type:safe-read
+ --trustAll
+ --no-prompt
+
+$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj2.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set assured-type:safe-read
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <para>When working with assured replication, the replication server property
+ <literal>degraded-status-threshold</literal> (default: 5000), sets the
+ number of operations allowed to build up in the replication queue before
+ the server is assigned degraded status. When a replication server has
+ degraded status, assured replication ceases to have an effect.</para>
+ </section>
+
+ <section xml:id="repl-subtree">
+ <title>Subtree Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Subtree</secondary>
+ </indexterm>
+
+ <para>OpenDJ can perform subtree replication, for example replicating
+ <literal>ou=People,dc=example,dc=com</literal>, but not the rest of
+ <literal>dc=example,dc=com</literal>, by putting the subtree in a separate
+ backend from the rest of the suffix.</para>
+
+ <para>For example, in this case you might have a <literal>userRoot</literal>
+ backend containing everything in <literal>dc=example,dc=com</literal>
+ except <literal>ou=People,dc=example,dc=com</literal>, and a separate
+ <literal>peopleRoot</literal> backend for
+ <literal>ou=People,dc=example,dc=com</literal>. Then you replicate
+ <literal>ou=People,dc=example,dc=com</literal> in its own topology.</para>
+ </section>
+
+ <section xml:id="repl-fractional">
+ <title>Fractional Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Fractional</secondary>
+ </indexterm>
+
+ <para>OpenDJ can perform fractional replication, whereby you specify
+ the attributes to include in or to exclude from the replication
+ process.</para>
+
+ <para>You set fractional replication configuration as
+ <literal>fractional-include</literal> or
+ <literal>fractional-exclude</literal> properties for a replication
+ domain. When you include attributes, the attributes that are required on
+ the relevant object classes are also included, whether you specify them
+ or not. When you exclude attributes, the excluded attributes must be
+ optional attributes for the relevant object classes. Fractional
+ replicas still respect schema definitions.</para>
+
+ <para>Fractional replication works by filtering objects at the replication
+ server. Initialize replication as you would normally. Of course you cannot
+ create a full replica from a replica with only a subset of the data. If you
+ must prevent data from being replicated across a national boundary, split
+ the replication server handling the updates from the directory servers
+ receiving the updates as described in
+ <xref linkend="repl-setup-dedicated-server" />.</para>
+
+ <para>For example, you might configure an externally facing
+ fractional replica to include only some <literal>inetOrgPerson</literal>
+ attributes.</para>
+
+ <screen>$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --trustAll
+ --no-prompt
+ --set
+ fractional-include:inetorgperson:cn,givenname,mail,mobile,sn,telephonenumber</screen>
+
+ <para>As another example, you might exclude a custom attribute called
+ <literal>sessionToken</literal> from being replicated.</para>
+
+ <screen>$ dsconfig
+ set-replication-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name "dc=example,dc=com"
+ --set fractional-exclude:*:sessionToken
+ --trustAll
+ --no-prompt</screen>
+
+ <para>This last example only works if you first define a
+ <literal>sessionToken</literal> attribute in the directory server
+ schema.</para>
+ </section>
+ </section>
+
+ <section xml:id="repl-change-notification">
+ <title>Change Notification For Your Applications</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Change notification</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>External change log</primary>
+ </indexterm>
+
+ <para>Some applications require notification when directory data updates
+ occur. For example, an application might need to sync directory data with
+ another database, or the application might need to kick off other processing
+ when certain updates occur.</para>
+
+ <para>In addition to supporting persistent search operations, OpenDJ
+ provides an external change log mechanism to allow applications to be
+ notified of changes to directory data.</para>
+
+ <procedure xml:id="enable-ecl">
+ <title>To Enable the External Change Log</title>
+
+ <para>OpenDJ directory servers without replication cannot expose an
+ external change log. The OpenDJ server that exposes the change log must
+ function both as a directory server, and also as a replication server for
+ the suffix whose changes you want logged.</para>
+
+ <step>
+ <para>Enable replication without using the
+ <option>--noReplicationServer</option> or
+ <option>--onlyReplicationServer</option> options.</para>
+
+ <para>With replication enabled, the changelog data can be accessed under
+ <literal>cn=changelog</literal>. For example, the following search shows
+ the publicly visible data available before any changes have been
+ made.</para>
+
+ <screen>$ ldapsearch --baseDN cn=changelog --port 1389 "(objectclass=*)" \* +
+dn: cn=changelog
+cn: changelog
+objectClass: top
+objectClass: container
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: cn=changelog
+</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="use-ecl">
+ <title>To Use the External Change Log</title>
+
+ <para>You read the external change log over LDAP. In addition, when you
+ poll the change log periodically, you can get the list of updates that
+ happened since your last request.</para>
+
+ <para>The external change log mechanism uses an LDAP control with
+ OID <literal>1.3.6.1.4.1.26027.1.5.4</literal> to allow the exchange
+ of cookies for the client application to bookmark the last changes seen,
+ and then start reading the next set of changes from where it left off on
+ the previous request.</para>
+
+ <para>This procedure shows the client reading the change log as
+ <literal>cn=Directory Manager</literal>. Make sure your client application
+ reads the changes with sufficient access to view all the changes it
+ needs to see.</para>
+
+ <step>
+ <para>Send an initial search request using the LDAP control with no
+ cookie value.</para>
+
+ <para>Notice the value of the <literal>changeLogCookie</literal> attribute
+ for the last of the two changes.</para>
+
+ <screen>$ ldapsearch
+ --baseDN cn=changelog
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --control "1.3.6.1.4.1.26027.1.5.4:false"
+ "(objectclass=*)"
+ \* +
+dn: cn=changelog
+cn: changelog
+objectClass: top
+objectClass: container
+subschemaSubentry: cn=schema
+hasSubordinates: true
+entryDN: cn=changelog
+
+# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
+ dc=example,dc=com:0000013087cbc28212d100000001;
+dn: replicationCSN=0000013087cbc28212d100000001,dc=example,dc=com,cn=changelog
+targetDN: cn=arsene lupin,ou=special users,dc=example,dc=com
+changeNumber: 0
+changes:: b2JqZWN0Q2xhc3M6IHBlcnNvbgpvYmplY3RDbGFzczogdG9wCmNuOiBBcnNlbmUgTHVwaW
+ 4KdGVsZXBob25lTnVtYmVyOiArMzMgMSAyMyA0NSA2NyA4OQpzbjogTHVwaW4KZW50cnlVVUlEOiA5M
+ GM3MTRmNy00ODZiLTRkNDctOTQwOS1iNDRkMTlkZWEzMWUKY3JlYXRlVGltZXN0YW1wOiAyMDExMDYx
+ MzA2NTg1NVoKY3JlYXRvcnNOYW1lOiBjbj1EaXJlY3RvcnkgTWFuYWdlcixjbj1Sb290IEROcyxjbj1
+ jb25maWcK
+changeType: add
+changeTime: 20110613065855Z
+objectClass: top
+objectClass: changeLogEntry
+targetEntryUUID: 90c714f7-486b-4d47-9409-b44d19dea31e
+replicationCSN: 0000013087cbc28212d100000001
+numSubordinates: 0
+replicaIdentifier: 4817
+changeLogCookie: dc=example,dc=com:0000013087cbc28212d100000001;
+changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: replicationCSN=0000013087cbc28212d100000001,dc=example,dc=com,cn=change
+ log
+
+# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
+ dc=example,dc=com:0000013087cbc34a12d100000002;
+dn: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=changelog
+targetDN: cn=horace velmont,ou=special users,dc=example,dc=com
+changeNumber: 0
+changes:: b2JqZWN0Q2xhc3M6IHBlcnNvbgpvYmplY3RDbGFzczogdG9wCmNuOiBIb3JhY2UgVmVsbW
+ 9udAp0ZWxlcGhvbmVOdW1iZXI6ICszMyAxIDEyIDIzIDM0IDQ1CnNuOiBWZWxtb250CmVudHJ5VVVJR
+ DogNmIyMjQ0MGEtNzZkMC00MDMxLTk0YjctMzViMWQ4NmYwNjdlCmNyZWF0ZVRpbWVzdGFtcDogMjAx
+ MTA2MTMwNjU4NTVaCmNyZWF0b3JzTmFtZTogY249RGlyZWN0b3J5IE1hbmFnZXIsY249Um9vdCBETnM
+ sY249Y29uZmlnCg==
+changeType: add
+changeTime: 20110613065855Z
+objectClass: top
+objectClass: changeLogEntry
+targetEntryUUID: 6b22440a-76d0-4031-94b7-35b1d86f067e
+replicationCSN: 0000013087cbc34a12d100000002
+numSubordinates: 0
+replicaIdentifier: 4817
+<emphasis>changeLogCookie: dc=example,dc=com:0000013087cbc34a12d100000002;</emphasis>
+changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: replicationCSN=0000013087cbc34a12d100000002,dc=example,dc=com,cn=change
+ log
+</screen>
+
+ <para>In this example, two new users were added to another replica
+ before the change log request was made.</para>
+
+ <para>Here the changes are base64 encoded, so you can decode them using
+ the <command>base64</command> command.</para>
+
+ <screen>$ base64 decode --encodedData b2JqZW...ZmlnCg==
+objectClass: person
+objectClass: top
+cn: Horace Velmont
+telephoneNumber: +33 1 12 23 34 45
+sn: Velmont
+entryUUID: 6b22440a-76d0-4031-94b7-35b1d86f067e
+createTimestamp: 20110613065855Z
+creatorsName: cn=Directory Manager,cn=Root DNs,cn=config
+ </screen>
+ </step>
+
+ <step>
+ <para>For the next search, provide the cookie to start reading where
+ you left off last time.</para>
+
+ <para>In this example, a description was added to Babs Jensen's entry.</para>
+
+ <screen>$ ldapsearch
+ --baseDN cn=changelog
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --control "1.3.6.1.4.1.26027.1.5.4:false:
+ dc=example,dc=com:0000013087cbc34a12d100000002;"
+ "(objectclass=*)"
+ \* +
+dn: cn=changelog
+cn: changelog
+objectClass: top
+objectClass: container
+subschemaSubentry: cn=schema
+hasSubordinates: true
+entryDN: cn=changelog
+
+# Public changelog exchange control(1.3.6.1.4.1.26027.1.5.4):
+ dc=example,dc=com:0000013087d7e27f12d100000003;
+dn: replicationCSN=0000013087d7e27f12d100000003,dc=example,dc=com,cn=changelog
+targetDN: uid=bjensen,ou=people,dc=example,dc=com
+changeNumber: 0
+changes:: YWRkOiBkZXNjcmlwdGlvbgpkZXNjcmlwdGlvbjogQSB0aGlyZCBjaGFuZ2UKLQpyZXBsYW
+ NlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IGNuPURpcmVjdG9yeSBNYW5hZ2VyLGNuPVJvb
+ 3QgRE5zLGNuPWNvbmZpZwotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW1lc3RhbXA6
+ IDIwMTEwNjEzMDcxMjEwWgotCg==
+changeType: modify
+changeTime: 20110613071210Z
+objectClass: top
+objectClass: changeLogEntry
+targetEntryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c
+replicationCSN: 0000013087d7e27f12d100000003
+numSubordinates: 0
+replicaIdentifier: 4817
+changeLogCookie: dc=example,dc=com:0000013087d7e27f12d100000003;
+changeInitiatorsName: cn=Directory Manager,cn=Root DNs,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: replicationCSN=0000013087d7e27f12d100000003,dc=example,dc=com,cn=change
+ log
+ </screen>
+
+ <para>If we base64-decode the changes, we see the following.</para>
+
+ <screen>$ base64 decode --encodedData YWRkO...gotCg==
+add: description
+description: A third change
+-
+replace: modifiersName
+modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
+-
+replace: modifyTimestamp
+modifyTimestamp: 20110613071210Z
+-
+</screen>
+ </step>
+ <step>
+ <para>If for some reason you lose the cookie, you can start over from
+ the earliest available change by sending a search request with no
+ value for the cookie.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="ecl-add-attributes">
+ <title>To Include Unchanged Attributes in the External Change Log</title>
+
+ <para>As shown above, the changes returned from a search on the external
+ change log include only what was actually changed. If you have applications
+ that need additional attributes published with every change log entry,
+ regardless of whether or not the attribute itself has changed, then specify
+ those using <literal>ecl-include</literal> and
+ <literal>ecl-include-for-deletes</literal>.</para>
+
+ <step>
+ <para>Set the attributes to include for all update operations with
+ <literal>ecl-include</literal>.</para>
+ <screen>$ dsconfig
+ set-external-changelog-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name dc=example,dc=com
+ --set ecl-include:"@person"
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ <step>
+ <para>Set the attributes to include for deletes with
+ <literal>ecl-include-for-deletes</literal>.</para>
+ <screen>$ dsconfig
+ set-external-changelog-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name dc=example,dc=com
+ --add ecl-include-for-deletes:"*"
+ --add ecl-include-for-deletes:"+"
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="ecl-limit-content">
+ <title>To Limit External Change Log Content</title>
+
+ <para>You can limit external change log content by disabling the domain
+ for a base DN. By default, <literal>cn=schema</literal> and
+ <literal>cn=admin data</literal> are not enabled.</para>
+
+ <step>
+ <para>Prevent OpenDJ from logging changes by disabling the domain.</para>
+ <screen>$ dsconfig
+ set-external-changelog-domain-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --provider-name "Multimaster Synchronization"
+ --domain-name dc=example,dc=com
+ --set enabled:false
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+
+ <para xml:id="ecl-legacy-format">The external change log can also work for
+ applications that follow the <link
+ xlink:href="http://tools.ietf.org/html/draft-good-ldap-changelog-04"
+ >Internet-Draft: Definition of an Object Class to Hold LDAP Change
+ Records</link>. Nothing special is required to get the objects specified for
+ this legacy format. Such applications cannot however use the change log
+ cookies that are shared across the replication topology, and therefore
+ can continue to be used after failover to another replica in a multi-master
+ replication environment.</para>
+ <indexterm>
+ <primary>External change log</primary>
+ <secondary>Legacy format</secondary>
+ </indexterm>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-resource-limits.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-resource-limits.xml
new file mode 100644
index 0000000..058ff15
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-resource-limits.xml
@@ -0,0 +1,211 @@
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-resource-limits'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Setting Resource Limits</title>
+ <indexterm><primary>Resource limits</primary></indexterm>
+
+ <para>This chapter shows you how to set resource limits that prevent
+ directory clients from using an unfair share of system resources.</para>
+
+ <section xml:id="limit-search-resources">
+ <title>Limiting Search Resources</title>
+
+ <para>Well-written directory client applications limit the scope of their
+ searches with filters that narrow the number of results returned. By default,
+ OpenDJ also only allows users with appropriate privileges to perform
+ unindexed searches.</para>
+
+ <para>You can further adjust additional limits on search operations, such
+ as the following.</para>
+ <itemizedlist>
+ <listitem>
+ <para>The <firstterm>lookthrough limit</firstterm> defines the maximum
+ number of candidate entries OpenDJ considers when processing a
+ search.</para>
+ <para>The default lookthrough limit, set by using the global server
+ property <literal>lookthrough-limit</literal>, is 5000.</para>
+ <para>You can override the limit for a particular user by changing the
+ operational attribute, <literal>ds-rlim-lookthrough-limit</literal>, on
+ the user's entry.</para>
+ </listitem>
+ <listitem>
+ <para>The <firstterm>size limit</firstterm> sets the maximum number of
+ entries returned for a search.</para>
+ <para>The default size limit, set by using the global server property
+ <literal>size-limit</literal>, is 1000.</para>
+ <para>You can override the limit for a particular user by changing the
+ operational attribute, <literal>ds-rlim-size-limit</literal>, on
+ the user's entry.</para>
+ </listitem>
+ <listitem>
+ <para>The <firstterm>time limit</firstterm> defines the maximum processing
+ time OpenDJ devotes to a search operation.</para>
+ <para>The default time limit, set by using the global server property
+ <literal>time-limit</literal>, is 1 minute.</para>
+ <para>You can override the limit for a particular user by changing the
+ operational attribute, <literal>ds-rlim-time-limit</literal>, on
+ the user's entry. Times for <literal>ds-rlim-time-limit</literal> are
+ expressed in seconds.</para>
+ </listitem>
+ <listitem>
+ <para>The <firstterm>idle time limit</firstterm> defines how long OpenDJ
+ allows idle connections to remain open.</para>
+ <para>No default idle time limit is set. You can set an idle time limit
+ by using the global server property
+ <literal>idle-time-limit</literal>.</para>
+ <para>You can override the limit for a particular user by changing the
+ operational attribute, <literal>ds-rlim-idle-time-limit</literal>, on
+ the user's entry. Times for <literal>ds-rlim-idle-time-limit</literal>
+ are expressed in seconds.</para>
+ </listitem>
+ <listitem>
+ <para>The maximum number of persistent searches can be set using the
+ global server property <literal>max-psearches</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure xml:id="set-search-limits-per-user">
+ <title>To Set Search Limits For a User</title>
+ <step>
+ <para>Change the user entry to set the limits to override.</para>
+ <screen>$ cat limit.ldif
+dn: uid=bjensen,ou=People,dc=example,dc=com
+changetype: modify
+add: ds-rlim-size-limit
+ds-rlim-size-limit: 10
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename limit.ldif
+Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com</screen>
+
+ <para>Now when Babs Jensen performs a search returning more than 10
+ entries, she sees the following message.</para>
+
+ <screen>Result Code: 4 (Size Limit Exceeded)
+Additional Information: This search operation has sent the maximum of
+ 10 entries to the client</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="set-search-limits-per-group">
+ <title>To Set Search Limits For a Group</title>
+ <step>
+ <para>Create an LDAP subentry to specify the limits using collective
+ attributes.</para>
+ <screen>$ cat grouplim.ldif
+dn: cn=Remove Administrator Search Limits,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: Remove Administrator Search Limits
+ds-rlim-lookthrough-limit;collective: 0
+ds-rlim-size-limit;collective: 0
+ds-rlim-time-limit;collective: 0
+subtreeSpecification: {base "ou=people", specificationFilter "
+ (isMemberOf=cn=Directory Administrators,ou=Groups,dc=example,dc=com)" }
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename grouplim.ldif
+Processing ADD request for
+ cn=Remove Administrator Search Limits,dc=example,dc=com
+ADD operation successful for DN
+ cn=Remove Administrator Search Limits,dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Check the results.</para>
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=kvaughan +|grep ds-rlim
+ds-rlim-lookthrough-limit: 0
+ds-rlim-time-limit: 0
+ds-rlim-size-limit: 0</screen>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="limit-idle-time">
+ <title>Limiting Idle Time</title>
+
+ <para>If you have applications that leave connections open for long
+ periods, OpenDJ can end up devoting resources to maintaining connections
+ that are no longer used. If your network does not drop such connections
+ eventually, you can configure OpenDJ to drop them by setting the
+ global configuration property, <literal>idle-time-limit</literal>. By
+ default, no idle time limit is set.</para>
+
+ <note>
+ <para>OpenDJ does not enforce idle timeout for persistent searches.</para>
+ </note>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set idle-time-limit:24h
+ --trustAll
+ --no-prompt</screen>
+
+ <para>The example shown sets the idle time limit to 24 hours.</para>
+ </section>
+
+ <section xml:id="limit-max-request-size">
+ <title>Limiting Maximum Request Size</title>
+
+ <para>The default maximum request size of 5 MB, set using the advanced
+ connection handler property <literal>max-request-size</literal>, is
+ sufficient to satisfy most client requests. Yet, there are some cases where
+ you might need to raise the request size limit. For example, if clients
+ add groups with large numbers of members, those add requests can go beyond
+ the 5 MB limit.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "LDAP Connection Handler"
+ --set max-request-size:20mb
+ --trustAll
+ --no-prompt</screen>
+
+ <para>The example shown sets the maximum request size on the LDAP connection
+ handler to 20 MB.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-rest-operations.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-rest-operations.xml
new file mode 100644
index 0000000..d219328
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-rest-operations.xml
@@ -0,0 +1,1273 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-rest-operations'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Performing RESTful Operations</title>
+ <indexterm><primary>HTTP</primary></indexterm>
+ <indexterm><primary>JSON</primary></indexterm>
+ <indexterm><primary>REST</primary></indexterm>
+
+ <para>OpenDJ lets you access directory data as JSON resources over HTTP.
+ This chapter demonstrates basic RESTful client operations using the
+ default configuration and sample directory data imported into OpenDJ from
+ <link xlink:show="new" xlink:href="http://opendj.forgerock.org/Example.ldif"
+ >Example.ldif</link>. Before trying the examples, enable HTTP access to
+ OpenDJ directory server as described in procedure, <link xlink:show="new"
+ xlink:href="admin-guide#setup-rest2ldap-connection-handler"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Set Up REST
+ Access to OpenDJ Directory Server</citetitle></link>.</para>
+
+ <para>Interface stability: <link xlink:href="admin-guide#interface-stability"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ >Evolving</link></para>
+
+ <section xml:id="understand-rest">
+ <title>Understanding the OpenDJ REST API</title>
+
+ <para>The OpenDJ REST API is built on a common ForgeRock HTTP-based REST API
+ for interacting with JSON Resources. APIs built on this common layer all let
+ you perform the following operations.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><link linkend="create-rest">Create</link></term>
+ <listitem>
+ <para>Add a resource that does not yet exist</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link linkend="read-rest">Read</link></term>
+ <listitem>
+ <para>Retrieve a single resource</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link linkend="update-rest">Update</link></term>
+ <listitem>
+ <para>Replace an existing resource</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link linkend="delete-rest">Delete</link></term>
+ <listitem>
+ <para>Remove an existing resource</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link linkend="patch-rest">Patch</link></term>
+ <listitem>
+ <para>Modify part of an existing resource</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link linkend="action-rest">Action</link></term>
+ <listitem>
+ <para>Perform a predefined action</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><link linkend="query-rest">Query</link></term>
+ <listitem>
+ <para>List a set of resources</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The present implementation in OpenDJ maps JSON resources onto LDAP
+ entries, meaning REST clients can in principle do just about anything an
+ LDAP client can do with directory data.</para>
+
+ <variablelist>
+ <para>In addition to query string parameters that depend on the operation,
+ the examples in this chapter make use of the following parameters that
+ apply to the JSON resource returned for all operations.</para>
+ <varlistentry>
+ <term><literal>_fields=<replaceable>field</replaceable>[,…]</literal></term>
+ <listitem>
+ <para>Retain only the specified fields in the JSON resource returned.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>_prettyPrint=true|false</literal></term>
+ <listitem>
+ <para>Make the JSON resource returned easy for humans to read.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="authenticate-rest">
+ <title>Authenticating Over REST</title>
+
+ <para>When you first try to get a resource that you can read as an LDAP
+ entry with an anonymous search, you might be surprised that you must
+ authenticate.</para>
+
+ <screen>$ curl http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
+{
+ "code" : 401,
+ "reason" : "Unauthorized",
+ "message" : "Unauthorized"
+}</screen>
+
+ <para>HTTP status code 401 tells your HTTP client that the request requires
+ user authentication. You can change this behavior by setting the HTTP
+ connection handler property, <literal>authentication-required</literal>,
+ to <literal>false</literal>.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ --set authentication-required:false
+ --no-prompt
+ --trustAll</screen>
+
+ <para>Out of the box both the HTTP Connection Handler and also the REST LDAP
+ gateway are configured to allow HTTP Basic authentication and HTTP header
+ based authentication in the style of OpenIDM. The authentication mechanisms
+ translate HTTP authentication to LDAP authentication on the directory server
+ side.</para>
+
+ <para>When you install OpenDJ either with generated sample user entries or
+ with data from <link xlink:href="http://opendj.forgerock.org/Example.ldif"
+ xlink:show="new">Example.ldif</link>, the relative distinguished name
+ attribute for the sample user entries is the user ID (<literal>uid</literal>)
+ attribute. For example, the DN and user ID for Babs Jensen are as
+ follows.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+uid: bjensen</programlisting>
+
+ <para>Given this pattern in the user entries, the default REST to LDAP
+ configuration assumes that the user name on the HTTP side is the value of
+ the user ID, and that user entries can be found under
+ <literal>ou=People,dc=example,dc=com</literal>. In other words, Babs Jensen
+ authenticates as <literal>bjensen</literal> (password:
+ <literal>hifalutin</literal>) over HTTP. This is mapped for an LDAP bind
+ to the bind DN <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.</para>
+
+ <para>With HTTP Basic authentication, it looks like this.</para>
+
+ <screen>$ curl
+ --user bjensen:hifalutin
+ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
+{
+ "_rev" : "0000000016cbb68c",
+ ...
+}</screen>
+
+ <para>Or, using the HTTP Basic
+ <replaceable>username</replaceable>:<replaceable>password</replaceable>@ form
+ in the URL, it looks like this.</para>
+
+ <screen>$ curl
+http://bjensen:hifalutin@opendj.example.com:8080/users/bjensen?_prettyPrint=true
+{
+ "_rev" : "0000000016cbb68c",
+ ...
+}</screen>
+
+ <para>With HTTP header based authentication, it looks like this.</para>
+
+ <screen>$ curl
+ --header "X-OpenIDM-Username: bjensen"
+ --header "X-OpenIDM-Password: hifalutin"
+ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
+{
+ "_rev" : "0000000016cbb68c",
+ ...
+}</screen>
+
+ <para>If your directory data are laid out differently, or if your user names
+ are email addresses rather than user IDs for example, then you must update
+ the configuration in order for authentication to work.</para>
+
+ <para>The REST LDAP gateway can also translate HTTP user name and password
+ authentication to PLAIN SASL authentication on the LDAP side. Moreover, the
+ gateway can fall back to proxied authorization as necessary, using a root DN
+ authenticated connection to LDAP servers. See <link xlink:show="new"
+ xlink:href="admin-guide#appendix-rest2ldap"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
+ Configuration</citetitle></link> for details on all configuration
+ choices.</para>
+ </section>
+
+ <section xml:id="create-rest">
+ <title>Creating Resources</title>
+
+ <para>There are two ways to create resources.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>To create a resource using an ID that you specify, perform an HTTP PUT
+ request with headers <literal>Content-Type: application/json</literal> and
+ <literal>If-None-Match: *</literal>, and the JSON content of your
+ resource.</para>
+
+ <para>The following example creates a new user entry with ID
+ <literal>newuser</literal>.</para>
+
+ <screen>$ curl
+ --request PUT
+ --user kvaughan:bribery
+ --header "Content-Type: application/json"
+ --header "If-None-Match: *"
+ --data '{
+ "_id": "newuser",
+ "contactInformation": {
+ "telephoneNumber": "+1 408 555 1212",
+ "emailAddress": "newuser@example.com"
+ },
+ "name": {
+ "familyName": "New",
+ "givenName": "User"
+ },
+ "displayName": "New User",
+ "manager": [
+ {
+ "_id": "kvaughan",
+ "displayName": "Kirsten Vaughan"
+ }
+ ]
+ }'
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
+{
+ "_rev" : "000000005b337348",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "newuser@example.com"
+ },
+ "_id" : "newuser",
+ "name" : {
+ "familyName" : "New",
+ "givenName" : "User"
+ },
+ "userName" : "newuser@example.com",
+ "displayName" : "New User",
+ "meta" : {
+ "created" : "2013-04-11T09:58:27Z"
+ },
+ "manager" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ } ]
+}</screen>
+ </listitem>
+
+ <listitem>
+ <para>To create a resource letting the server choose the ID, perform an HTTP
+ POST with <literal>_action=create</literal> as described in
+ <xref linkend="action-rest" />.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="read-rest">
+ <title>Reading a Resource</title>
+
+ <para>To read a resource, perform an HTTP GET.</para>
+
+ <screen>$ curl
+ --request GET
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
+{
+ "_rev" : "000000005b337348",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "newuser@example.com"
+ },
+ "_id" : "newuser",
+ "name" : {
+ "familyName" : "New",
+ "givenName" : "User"
+ },
+ "userName" : "newuser@example.com",
+ "displayName" : "New User",
+ "meta" : {
+ "created" : "2013-04-11T09:58:27Z"
+ },
+ "manager" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ } ]
+}</screen>
+ </section>
+
+ <section xml:id="update-rest">
+ <title>Updating Resources</title>
+
+ <para>To update a resource, perform an HTTP PUT with the changes to the
+ resource. For read-only fields, either include unmodified versions, or omit
+ them from your updated version.</para>
+
+ <para>The following example adds a manager for Sam Carter.</para>
+
+ <screen>$ curl
+ --request PUT
+ --user kvaughan:bribery
+ --header "Content-Type: application/json"
+ --data '{
+ "contactInformation": {
+ "telephoneNumber": "+1 408 555 4798",
+ "emailAddress": "scarter@example.com"
+ },
+ "name": {
+ "familyName": "Carter",
+ "givenName": "Sam"
+ },
+ "userName": "scarter@example.com",
+ "displayName": "Sam Carter",
+ "groups": [
+ {
+ "_id": "Accounting Managers"
+ }
+ ],
+ "manager": [
+ {
+ "_id": "trigden",
+ "displayName": "Torrey Rigden"
+ }
+ ]
+ }'
+ http://opendj.example.com:8080/users/scarter?_prettyPrint=true
+{
+ "_rev" : "00000000a1923db2",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 4798",
+ "emailAddress" : "scarter@example.com"
+ },
+ "_id" : "scarter",
+ "name" : {
+ "familyName" : "Carter",
+ "givenName" : "Sam"
+ },
+ "userName" : "scarter@example.com",
+ "displayName" : "Sam Carter",
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ],
+ "meta" : {
+ "lastModified" : "2013-04-12T07:42:34Z"
+ },
+ "groups" : [ {
+ "_id" : "Accounting Managers"
+ } ]
+}</screen>
+
+ <para>To update a resource only if the resource matches a particular version,
+ use an <literal>If-Match: <replaceable>revision</replaceable></literal>
+ header.</para>
+
+ <screen> $ curl
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/scarter?_fields=_rev
+<emphasis>{"_rev":"00000000b017c5b8"}</emphasis>
+$ curl
+ --request PUT
+ --user kvaughan:bribery
+ <emphasis>--header "If-Match: 00000000b017c5b8"</emphasis>
+ --header "Content-Type: application/json"
+ --data '{
+ "contactInformation": {
+ "telephoneNumber": "+1 408 555 1212",
+ "emailAddress": "scarter@example.com"
+ },
+ "name": {
+ "familyName": "Carter",
+ "givenName": "Sam"
+ },
+ "userName": "scarter@example.com",
+ "displayName": "Sam Carter",
+ "groups": [
+ {
+ "_id": "Accounting Managers"
+ }
+ ],
+ "manager": [
+ {
+ "_id": "trigden",
+ "displayName": "Torrey Rigden"
+ }
+ ]
+ }'
+ http://opendj.example.com:8080/users/scarter?_prettyPrint=true
+{
+ "_rev" : "00000000a1ee3da3",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "scarter@example.com"
+ },
+ "_id" : "scarter",
+ "name" : {
+ "familyName" : "Carter",
+ "givenName" : "Sam"
+ },
+ "userName" : "scarter@example.com",
+ "displayName" : "Sam Carter",
+ "meta" : {
+ "lastModified" : "2013-04-12T07:47:45Z"
+ },
+ "groups" : [ {
+ "_id" : "Accounting Managers"
+ } ],
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ]
+}</screen>
+ </section>
+
+ <section xml:id="delete-rest">
+ <title>Deleting Resources</title>
+
+ <para>To delete a resource, perform an HTTP DELETE on the resource URL.
+ On success, the operation returns the resource you deleted.</para>
+
+ <screen>$ curl
+ --request DELETE
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
+{
+ "_rev" : "000000003a5f3cb2",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "newuser@example.com"
+ },
+ "_id" : "newuser",
+ "name" : {
+ "familyName" : "New",
+ "givenName" : "User"
+ },
+ "userName" : "newuser@example.com",
+ "displayName" : "New User",
+ "meta" : {
+ "created" : "2013-04-11T09:58:27Z"
+ },
+ "manager" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ } ]
+}</screen>
+
+ <para>To delete a resource only if the resource matches a particular version,
+ use an <literal>If-Match: <replaceable>revision</replaceable></literal>
+ header.</para>
+
+ <screen>$ curl
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/newuser?_fields=_rev
+{"_rev":"000000006d8d7358"}
+$ curl
+ --request DELETE
+ --user kvaughan:bribery
+ --header "If-Match: 000000006d8d7358"
+ http://opendj.example.com:8080/users/newuser?_prettyPrint=true
+{
+ "_rev" : "00000000383f3cae",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "newuser@example.com"
+ },
+ "_id" : "newuser",
+ "name" : {
+ "familyName" : "New",
+ "givenName" : "User"
+ },
+ "userName" : "newuser@example.com",
+ "displayName" : "New User",
+ "meta" : {
+ "created" : "2013-04-11T12:48:48Z"
+ },
+ "manager" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ } ]
+}</screen>
+
+ <orderedlist>
+ <para>To delete a resource and all its children, you must change the
+ configuration, get the REST LDAP gateway or HTTP Connection Handler to
+ reload its configuration, and perform the operation as a user who has the
+ access rights required. The following steps show one way to do this with
+ the HTTP Connection Handler.</para>
+
+ <para>In this case the LDAP view of the user to delete shows two child
+ entries.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&)" dn
+dn: uid=nbohr,ou=People,dc=example,dc=com
+
+dn: cn=quantum dot,uid=nbohr,ou=People,dc=example,dc=com
+
+dn: cn=qubit generator,uid=nbohr,ou=People,dc=example,dc=com</screen>
+
+ <listitem>
+ <para>In the configuration file for the HTTP Connection Handler, by default
+ <filename>/path/to/opendj/config/http-config.json</filename>, set
+ <literal>"useSubtreeDelete" : true</literal>.</para>
+
+ <note>
+ <para>After this change, only users who have access to request a tree
+ delete can delete resources.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>Force the HTTP Connection Handler to reread its configuration.</para>
+
+ <screen>$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ <emphasis>--set enabled:false</emphasis>
+ --no-prompt
+$ dsconfig
+ set-connection-handler-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --handler-name "HTTP Connection Handler"
+ <emphasis>--set enabled:true</emphasis>
+ --no-prompt</screen>
+ </listitem>
+
+ <listitem>
+ <para>Delete as a user who has rights to perform a subtree delete on
+ the resource.</para>
+
+ <screen>$ curl
+ --request DELETE
+ --user kvaughan:bribery
+ http://opendj.example.com:8080/users/nbohr?_prettyPrint=true
+{
+ "_rev" : "000000003d912113",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "nbohr@example.com"
+ },
+ "_id" : "nbohr",
+ "name" : {
+ "familyName" : "Bohr",
+ "givenName" : "Niels"
+ },
+ "userName" : "nbohr@example.com",
+ "displayName" : "Niels Bohr"
+}</screen>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="patch-rest">
+ <title>Patching Resources</title>
+
+ <para>OpenDJ lets you patch JSON resources, updating part of the resource
+ rather than replacing it. For example, you could change Babs Jensen's
+ email address by issuing an HTTP PATCH request, as in the example that
+ follows.</para>
+
+ <para>Notice that the data sent specifies the type of patch operation, the
+ field to change, and a value that depends on the field you change and on the
+ operation. A single-valued field takes an object, boolean, string, or number
+ depending on its type, whereas a multi-valued field takes an array of values.
+ Getting the type wrong results in an error. Also notice that the patch data is
+ itself an array, since you could patch more than one part of the resource by
+ using a set of patch operations in the same request.</para>
+
+ <screen>$ curl
+ --user kvaughan:bribery
+ --request PATCH
+ --header "Content-Type: application/json"
+ --data '[
+ {
+ "operation": "replace",
+ "field": "/contactInformation/emailAddress",
+ "value": "babs@example.com"
+ }
+ ]'
+ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
+{
+ "_rev" : "00000000f3fdd370",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1862",
+ "emailAddress" : "babs@example.com"
+ },
+ "_id" : "bjensen",
+ "name" : {
+ "familyName" : "Jensen",
+ "givenName" : "Barbara"
+ },
+ "userName" : "babs@example.com",
+ "displayName" : "Barbara Jensen",
+ "meta" : {
+ "lastModified" : "2013-05-13T14:35:31Z"
+ },
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ]
+}</screen>
+
+ <variablelist>
+ <para>OpenDJ supports four types of patch operation.</para>
+
+ <varlistentry>
+ <term>"add"</term>
+ <listitem>
+ <para>The add operation ensures that the target field contains the value
+ provided, creating parent fields as necessary.</para>
+
+ <para>If the target field is single-valued and a value already exists, then
+ that value is replaced with the value you provide. <emphasis
+ role="strong">Note that you do not get an error when adding a value to a
+ single-valued field that already has a value.</emphasis> A single-valued
+ field is one whose value is not an array (an object, string, boolean, or
+ number).</para>
+
+ <para>If the target field is multi-valued, then the array of values you
+ provide is merged with the set of values already in the resource. New
+ values are added, and duplicate values are ignored. A multi-valued field
+ takes an array value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"remove"</term>
+ <listitem>
+ <para>The remove operation ensures that the target field does not contain
+ the value provided. If you do not provide a value, the entire field is
+ removed if it already exists.</para>
+
+ <para>If the target field is single-valued and a value is provided, then
+ the provided value must match the existing value to remove, otherwise the
+ field is left unchanged.</para>
+
+ <para>If the target field is multi-valued, then values in the array you
+ provide are removed from the existing set of values.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"replace"</term>
+ <listitem>
+ <para>The replace operation removes existing values on the target field,
+ and replaces them with the values you provide. It is equivalent to
+ performing a remove on the field, then an add with the values you
+ provide.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>"increment"</term>
+ <listitem>
+ <para>The increment operation increments or decrements the value or values
+ in the target field by the amount you specify, which is positive to
+ increment, negative to decrement. The target field must be a number or
+ a set of numbers. The value you provide must be a single number.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>One key nuance in how patch works with OpenDJ has to do with
+ multi-valued fields. Although JSON resources represent multi-valued fields as
+ <emphasis>arrays</emphasis>, OpenDJ treats those values as
+ <emphasis>sets</emphasis>. In other words, values in the field are unique,
+ and the ordering of an array of values is not meaningful in the context of
+ patch operations. If you reference array values by index, OpenDJ returns
+ an error.<footnote><para>OpenDJ does let you use a hyphen as the last element
+ of the "field" JSON pointer value to add an element to the set, as in
+ <command>curl --user kvaughan:bribery --request PATCH --header "Content-Type:
+ application/json" --data '[{ "operation" : "add", "field" : "/members/-",
+ "value" : { "_id" : "bjensen" } }]'
+ http://opendj.example.com:8080/groups/Directory%20Administrators</command>.</para>
+ </footnote></para>
+
+ <para>Instead use the patch operations as if arrays values were sets. For
+ example, you can include Barbara Jensen in a group by adding her to the set
+ of members.</para>
+
+ <screen>$ curl
+ --user kvaughan:bribery
+ --request PATCH
+ --header "Content-Type: application/json"
+ --data '[
+ {
+ "operation": "add",
+ "field": "/members",
+ "value": [
+ {
+ "_id": "bjensen"
+ }
+ ]
+ }
+ ]'
+ http://opendj.example.com:8080/groups/Directory%20Administrators
+ ?_prettyPrint=true
+{
+ "_rev" : "00000000b70c881a",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "_id" : "Directory Administrators",
+ "displayName" : "Directory Administrators",
+ "meta" : {
+ "lastModified" : "2013-05-13T16:40:23Z"
+ },
+ "members" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ }, {
+ "_id" : "rdaugherty",
+ "displayName" : "Robert Daugherty"
+ }, {
+ "_id" : "bjensen",
+ "displayName" : "Barbara Jensen"
+ }, {
+ "_id" : "hmiller",
+ "displayName" : "Harry Miller"
+ } ]
+}</screen>
+
+ <para>Removing her from the group is similar.</para>
+
+ <screen>$ curl
+ --user kvaughan:bribery
+ --request PATCH
+ --header "Content-Type: application/json"
+ --data '[
+ {
+ "operation": "remove",
+ "field": "/members",
+ "value": [
+ {
+ "_id": "bjensen"
+ }
+ ]
+ }
+ ]'
+ http://opendj.example.com:8080/groups/Directory%20Administrators
+ ?_prettyPrint=true
+{
+ "_rev" : "00000000e241797e",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "_id" : "Directory Administrators",
+ "displayName" : "Directory Administrators",
+ "meta" : {
+ "lastModified" : "2013-05-13T16:40:55Z"
+ },
+ "members" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ }, {
+ "_id" : "rdaugherty",
+ "displayName" : "Robert Daugherty"
+ }, {
+ "_id" : "hmiller",
+ "displayName" : "Harry Miller"
+ } ]
+}</screen>
+
+ <para>You can use resource revision numbers in <literal>If-Match:
+ <replaceable>revision</replaceable></literal> headers to patch the resource
+ only if the resource matches a particular version.</para>
+
+ <screen>$ curl
+ --user kvaughan:bribery
+ "http://opendj.example.com:8080/users/bjensen?_prettyPrint=true&_fields=_rev"
+{
+ "_rev" : "00000000c1b6d4c7"
+}
+$ curl
+ --user kvaughan:bribery
+ --request PATCH
+ --header "If-Match: 00000000c1b6d4c7"
+ --header "Content-Type: application/json"
+ --data '[
+ {
+ "operation": "add",
+ "field": "/contactInformation/emailAddress",
+ "value": "babs@example.com"
+ }
+ ]'
+ http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
+{
+ "_rev" : "00000000f946d377",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1862",
+ "emailAddress" : "babs@example.com"
+ },
+ "_id" : "bjensen",
+ "name" : {
+ "familyName" : "Jensen",
+ "givenName" : "Barbara"
+ },
+ "userName" : "babs@example.com",
+ "displayName" : "Barbara Jensen",
+ "meta" : {
+ "lastModified" : "2013-05-13T16:56:33Z"
+ },
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ]
+}</screen>
+
+ <para>The resource revision changes after you successfully perform the patch
+ operation.</para>
+ </section>
+
+ <section xml:id="action-rest">
+ <title>Using Actions</title>
+
+ <para>OpenDJ implements an action that lets the server set the resource ID
+ on creation. To use this action, perform an HTTP POST with header
+ <literal>Content-Type: application/json</literal>,
+ <literal>_action=create</literal> in the query string, and the JSON content of
+ your resource.</para>
+
+ <para>The following example creates a new user entry.</para>
+
+ <screen width="82">$ curl
+ --request POST
+ --user kvaughan:bribery
+ --header "Content-Type: application/json"
+ --data '{
+ "_id": "newuser",
+ "contactInformation": {
+ "telephoneNumber": "+1 408 555 1212",
+ "emailAddress": "newuser@example.com"
+ },
+ "name": {
+ "familyName": "New",
+ "givenName": "User"
+ },
+ "displayName": "New User",
+ "manager": [
+ {
+ "_id": "kvaughan",
+ "displayName": "Kirsten Vaughan"
+ }
+ ]
+ }'
+ "http://opendj.example.com:8080/users?_action=create&_prettyPrint=true"
+{
+ "_rev" : "0000000034a23ca7",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1212",
+ "emailAddress" : "newuser@example.com"
+ },
+ "_id" : "newuser",
+ "name" : {
+ "familyName" : "New",
+ "givenName" : "User"
+ },
+ "userName" : "newuser@example.com",
+ "displayName" : "New User",
+ "meta" : {
+ "created" : "2013-04-11T11:19:08Z"
+ },
+ "manager" : [ {
+ "_id" : "kvaughan",
+ "displayName" : "Kirsten Vaughan"
+ } ]
+}</screen>
+ </section>
+
+ <section xml:id="query-rest">
+ <title>Querying Resource Collections</title>
+
+ <para>To query resource collections, perform an HTTP GET with a
+ <literal>_queryFilter=<replaceable>filter</replaceable></literal> parameter
+ in your query string.</para>
+
+ <variablelist>
+ <para>For query operations, your <replaceable>filter</replaceable>
+ expressions are constructed from the following building blocks.
+ Make sure you URL encode the filter expressions, which are shown here
+ without URL encoding to make them easier to read.</para>
+
+ <para>In these expressions the simplest
+ <replaceable>json-pointer</replaceable> is a field of the JSON resource,
+ such as <literal>userName</literal> or <literal>id</literal>. A
+ <replaceable>json-pointer</replaceable> can however point to nested
+ elements as described in the <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer">JSON
+ Pointer</link> Internet-Draft.</para>
+
+ <varlistentry>
+ <term>Comparison expressions</term>
+ <listitem>
+ <para>You can build filters using the following comparison expressions.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> eq <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer equals the value, as in the following
+ example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+eq+"bjensen@example.com"&_prettyPrint=true'
+{
+ "result" : [ {
+ "_rev" : "00000000315fb731",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1862",
+ "emailAddress" : "bjensen@example.com"
+ },
+ "_id" : "bjensen",
+ "name" : {
+ "familyName" : "Jensen",
+ "givenName" : "Barbara"
+ },
+ "userName" : "bjensen@example.com",
+ "displayName" : "Barbara Jensen"
+ } ],
+ "resultCount" : 1,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> co <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer contains the value, as in the following
+ example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+co+"jensen"&_fields=userName&_prettyPrint=true'
+{
+ "result" : [ {
+ "userName" : "ajensen@example.com"
+ }, {
+ "userName" : "bjensen@example.com"
+ }, {
+ "userName" : "gjensen@example.com"
+ }, {
+ "userName" : "jjensen@example.com"
+ }, {
+ "userName" : "kjensen@example.com"
+ }, {
+ "userName" : "rjensen@example.com"
+ }, {
+ "userName" : "tjensen@example.com"
+ } ],
+ "resultCount" : 7,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> sw <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer starts with the value, as in the
+ following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+sw+"ab"&_fields=userName&_prettyPrint=true'
+{
+ "result" : [ {
+ "userName" : "abarnes@example.com"
+ }, {
+ "userName" : "abergin@example.com"
+ } ],
+ "resultCount" : 2,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> lt <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer is less than the value, as in the
+ following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+lt+"ac"&_fields=userName&_prettyPrint=true'
+{
+ "result" : [ {
+ "userName" : "abarnes@example.com"
+ }, {
+ "userName" : "abergin@example.com"
+ } ],
+ "resultCount" : 2,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> le <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer is less than or equal to the value, as
+ in the following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+le+"ad"&_fields=userName&_prettyPrint=true'
+{
+ "result" : [ {
+ "userName" : "abarnes@example.com"
+ }, {
+ "userName" : "abergin@example.com"
+ }, {
+ "userName" : "achassin@example.com"
+ } ],
+ "resultCount" : 3,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> gt <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer is greater than the value, as in the
+ following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+gt+"tt"&_fields=userName&_prettyPrint=true'
+{
+ "result" : [ {
+ "userName" : "ttully@example.com"
+ }, {
+ "userName" : "tward@example.com"
+ }, {
+ "userName" : "wlutz@example.com"
+ } ],
+ "resultCount" : 3,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal><replaceable>json-pointer</replaceable> ge <replaceable>json-value</replaceable></literal></term>
+ <listitem>
+ <para>Matches when the pointer is greater than or equal to the value,
+ as in the following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName+ge+"tw"&_fields=userName&_prettyPrint=true'
+{
+ "result" : [ {
+ "userName" : "tward@example.com"
+ }, {
+ "userName" : "wlutz@example.com"
+ } ],
+ "resultCount" : 2,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Presence expression</term>
+ <listitem>
+ <para><literal><replaceable>json-pointer</replaceable> pr</literal> matches
+ any resource on which the <replaceable>json-pointer</replaceable> is
+ present, as in the following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=userName%20pr&_prettyPrint=true'
+{
+ "result" : [ {
+ "_rev" : "000000002210a544",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "manager" : [ {
+ "_id" : "scarter",
+ "displayName" : "Sam Carter"
+ } ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 9445",
+ "emailAddress" : "abarnes@example.com"
+ },
+ "_id" : "abarnes",
+ "name" : {
+ "familyName" : "Barnes",
+ "givenName" : "Anne-Louise"
+ },
+ "userName" : "abarnes@example.com",
+ "displayName" : "Anne-Louise Barnes"
+ },… many entries omitted …
+ "_id" : "newuser",
+ "name" : {
+ "familyName" : "New",
+ "givenName" : "User"
+ },
+ "userName" : "newuser@example.com",
+ "displayName" : "New User",
+ "meta" : {
+ "created" : "2013-03-26T10:52:42Z"
+ }
+ } ],
+ "resultCount" : 152,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Literal expressions</term>
+ <listitem>
+ <para><literal>true</literal> matches any resource in the collection.</para>
+ <para><literal>false</literal> matches no resource in the collection.</para>
+
+ <para>In other words you can list all resources in a collection as in the
+ following example.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /groups?_queryFilter=true&_fields=displayName&_prettyPrint=true'
+{
+ "result" : [ {
+ "displayName" : "Accounting Managers"
+ }, {
+ "displayName" : "Directory Administrators"
+ }, {
+ "displayName" : "HR Managers"
+ }, {
+ "displayName" : "PD Managers"
+ }, {
+ "displayName" : "QA Managers"
+ } ],
+ "resultCount" : 5,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Complex expressions</term>
+ <listitem>
+ <para>You can combine expressions using boolean operators
+ <literal>and</literal>, <literal>or</literal>, and <literal>!</literal>
+ (not), using parentheses,
+ <literal>(<replaceable>expression</replaceable>)</literal>, to group
+ expressions. The following example queries resources with last name
+ Jensen and manager name starting with <literal>Bar</literal>. Notice that
+ the filters use the JSON pointers <literal>name/familyName</literal> and
+ <literal>manager/displayName</literal> to identify the fields that are
+ nested inside the <literal>name</literal> and <literal>manager</literal>
+ objects.</para>
+
+ <screen>$ curl --user kvaughan:bribery 'http://opendj.example.com:8080
+ /users?_queryFilter=(userName+co+"jensen"+and+manager/displayName+sw+"Sam")
+ &_fields=displayName&_prettyPrint=true'
+{
+ "result" : [ {
+ "displayName" : "Jody Jensen"
+ }, {
+ "displayName" : "Ted Jensen"
+ } ],
+ "resultCount" : 2,
+ "pagedResultsCookie" : null,
+ "remainingPagedResults" : -1
+}</screen>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <!-- Pending implementation https://bugster.forgerock.org/jira/browse/OPENDJ-702
+ <para>You can have the server sort JSON resources before it returns them by
+ using the <literal>_sortKeys[+-]=<replaceable>field</replaceable>[,…]</literal>
+ query string.</para>
+ -->
+
+ <!-- Pending implementation https://bugster.forgerock.org/jira/browse/OPENDJ-701
+ <variablelist>
+ <para>You can page through search results using the following query string
+ parameters.</para>
+
+ <varlistentry>
+ <term><literal>__pagedResultsCookie=<replaceable>string</replaceable></literal></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>__pagedResultsOffset=<replaceable>string</replaceable></literal></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>__pagedResultsCookie=<replaceable>string</replaceable></literal></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ -->
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-samba.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-samba.xml
new file mode 100644
index 0000000..f925632
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-samba.xml
@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-samba'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Samba Password Synchronization</title>
+ <indexterm><primary>Samba</primary></indexterm>
+
+ <para><link xlink:href="http://www.samba.org/" xlink:show="new">Samba</link>,
+ the Windows interoperability suite for Linux and UNIX, stores accounts because
+ UNIX and Windows password storage management is not interoperable. The default
+ account storage mechanism is designed to work well with relatively small
+ numbers of accounts and configurations with one domain controller. For larger
+ installations, you can configure Samba to use OpenDJ for storing Samba
+ accounts. See the Samba documentation for your platform for instructions on
+ how to configure an LDAP directory server such as OpenDJ as a Samba passdb
+ backend.</para>
+
+ <para>The rest of this chapter focuses on how you keep passwords in sync when
+ using OpenDJ for Samba account storage.</para>
+
+ <para>When you store Samba accounts in OpenDJ, Samba stores its own attributes
+ as defined in the Samba schema. Samba does not use the LDAP standard
+ <literal>userPassword</literal> attribute to store users' Samba passwords.
+ You can configure Samba to apply changes to Samba passwords to LDAP passwords
+ as well, too. Yet, if a user modifies her LDAP password directly without
+ updating the Samba password, the LDAP and Samba passwords get out of
+ sync.</para>
+
+ <para>The OpenDJ Samba Password plugin resolves this problem for you. The
+ plugin intercepts password changes to Samba user profiles, synchronizing Samba
+ password and LDAP password values. For an incoming Password Modify Extended
+ Request or modify request changing the user password, the OpenDJ Samba Password
+ plugin detects whether the user's entry reflects a Samba user profile (entry
+ has object class <literal>sambaSAMAccount</literal>), hashes the incoming
+ password value, and applies the password change to the appropriate password
+ attribute, keeping the password values in sync. The OpenDJ Samba Password
+ plugin can perform synchronization as long as new passwords values are
+ provided in clear text in the modification request. If you configure Samba
+ to synchronize LDAP passwords when it changes Samba passwords, then the
+ plugin can ignore changes by the Samba user to avoid duplicate
+ synchronization.</para>
+
+ <procedure xml:id="setup-samba-administrator-account">
+ <title>To Set Up a Samba Administrator Account</title>
+
+ <para>The Samba Administrator synchronizes LDAP passwords after changing
+ Samba passwords by issuing a Password Modify Extended Request. In Samba's
+ <filename>smb.conf</filename> configuration file, the value of
+ <literal>ldap admin dn</literal> is set to the DN of this account. When
+ the Samba Administrator changes a user password, the plugin ignores
+ the changes, so choose a distinct account different from Directory Manager
+ and other administrators.</para>
+
+ <step>
+ <para>Create or choose an account for the Samba Administrator.</para>
+ <screen>$ cat samba.ldif
+dn: uid=samba-admin,ou=Special Users,dc=example,dc=com
+cn: Samba Administrator
+givenName: Samba
+mail: samba@example.com
+objectClass: person
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: top
+sn: Administrator
+uid: samba-admin
+userPassword: password
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename samba.ldif
+Processing ADD request for uid=samba-admin,ou=Special Users,dc=example,dc=com
+ADD operation successful for DN uid=samba-admin,ou=Special Users,
+ dc=example,dc=com</screen>
+ </step>
+ <step>
+ <para>Ensure the Samba Administrator can reset user passwords.</para>
+ <screen>$ cat samba-rights.ldif
+dn: uid=samba-admin,ou=Special Users,dc=example,dc=com
+changetype: modify
+add: ds-privilege-name
+ds-privilege-name: password-reset
+
+dn: dc=example,dc=com
+changetype: modify
+add: aci
+aci: (target="ldap:///dc=example,dc=com") (targetattr ="*")(version 3.0; acl "
+ Samba Admin user rights"; allow(all) groupdn ="ldap:///uid=samba-user,ou=
+ Special Users,dc=example,dc=com";)
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename samba-rights.ldif
+Processing MODIFY request for uid=samba-admin,ou=Special Users,dc=example,dc=com
+MODIFY operation successful for DN
+ uid=samba-admin,ou=Special Users,dc=example,dc=com
+Processing MODIFY request for dc=example,dc=com
+MODIFY operation successful for DN dc=example,dc=com</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="setup-samba-pwd-plugin">
+ <title>To Set Up the Samba Password Plugin</title>
+
+ <step>
+ <para>Determine whether the plugin must store passwords hashed like
+ LanManager (<literal>sync-lm-password</literal>) or like Windows NT
+ (<literal>sync-nt-password</literal>), based on how you set up Samba
+ in your environment.</para>
+ </step>
+ <step>
+ <para>Enable the plugin.</para>
+ <screen>$ dsconfig
+ create-plugin
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --plugin-name "Samba Password Synchronisation"
+ --type samba-password
+ --set enabled:true
+ --set pwd-sync-policy:sync-nt-password
+ --set
+ samba-administrator-dn:"uid=samba-admin,ou=Special Users,dc=example,dc=com"
+ --trustAll
+ --no-prompt</screen>
+ <para>At this point the Samba Password plugin is active.</para>
+ </step>
+ <step performance="optional">
+ <para>When troubleshooting Samba Password plugin issues, you can turn on
+ debug logging as follows.</para>
+ <screen>$ dsconfig
+ create-debug-target
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --target-name org.opends.server.plugins.SambaPasswordPlugin
+ --set debug-level:all
+ --trustAll
+ --no-prompt
+$ dsconfig
+ set-log-publisher-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+ </step>
+ </procedure>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-schema.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-schema.xml
new file mode 100644
index 0000000..b77e159
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-schema.xml
@@ -0,0 +1,632 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-schema'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Managing Schema</title>
+ <indexterm><primary>Schema</primary></indexterm>
+
+ <para>Schema definitions describe the data, and especially the object classes
+ and attribute types that can be stored in the directory. By default OpenDJ
+ conforms strictly to LDAPv3 standards pertaining to schema definitions and
+ attribute syntax checking, ensuring that data stored is valid and properly
+ formed. Unless your data use only standard schema present in OpenDJ when
+ you install, then you must add additional schema definitions to account
+ the data your applications stored.</para>
+
+ <para>Out of the box, OpenDJ comes with many standard schema definitions.
+ In addition you can update and extend schema definitions while OpenDJ
+ is online. As a result you can add new applications requiring additional
+ data without stopping your directory service.</para>
+
+ <para>This chapter demonstrates how to change and to extend OpenDJ schema.
+ This chapter also identifies the standard schema definitions available when
+ you install OpenDJ.</para>
+
+ <section xml:id="about-schema">
+ <title>About Directory Schema</title>
+
+ <para>Directory schema, described in <link
+ xlink:href='http://tools.ietf.org/html/rfc4512'>RFC 4512</link>, define
+ the kinds of information you find in the directory, and can define how
+ the information are related. This chapter focuses primarily on two types
+ of directory schema definitions.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><firstterm>Attribute type</firstterm> definitions describe attributes
+ of directory entries, such as <literal>givenName</literal> or
+ <literal>mail</literal>.</para>
+ <para>Here is an example of an attribute type definition.</para>
+ <programlisting language="ldif"># Attribute type definition
+attributeTypes: ( 0.9.2342.19200300.100.1.3 NAME ( 'mail' 'rfc822Mailbox' )
+ EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} X-ORIGIN 'RFC 4524' )</programlisting>
+ <para>Attribute type definitions start with an object identifier (OID),
+ and generally a short name or names that are easier to remember than the
+ OID. The attribute type definition can specify how attribute values
+ should be collated for sorting, and what syntax they use. The X-ORIGIN
+ is an extension to identify where the definition originated. When you
+ define your one schema, you likely want to provide an X-ORIGIN to help
+ you to track versions of definitions, and where the definitions came
+ from.</para>
+ </listitem>
+ <listitem>
+ <para><firstterm>Object class</firstterm> definitions identify the
+ attribute types that an entry must have, and may have. Examples of
+ object classes include <literal>person</literal> and
+ <literal>organizationalUnit</literal>.</para>
+ <para>Here is an example of an object class definition.</para>
+ <programlisting language="ldif"># Object class definition
+objectClasses: ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )
+ MAY ( userPassword $ telephoneNumber $ seeAlso $ description )
+ X-ORIGIN 'RFC 4519' )</programlisting>
+ <para>Entries all have an attribute identifying their object classes,
+ called <literal>objectClass</literal>.</para>
+ <para>Object class definitions start with an object identifier (OID), and
+ generally a short name that is easier to remember than the OID. The
+ definition here says that the person object class inherits from the top
+ object class, which is the top-level parent of all object classes. When
+ you view the objectclass attribute values on an entry, you see the list
+ of object classes that the entry takes. An entry can have one STRUCTURAL
+ object class inheritance branch, such as <literal>top</literal> -
+ <literal>person</literal> - <literal>organizationalPerson</literal> -
+ <literal>inetOrgPerson</literal>. Yet entries can have multiple
+ AUXILIARY object classes. The object class then defines the attribute
+ types that must be included, and the attribute types that may be included
+ on entries having the object class.</para>
+ </listitem>
+
+ <listitem>
+ <para>An <firstterm>attribute syntax</firstterm> constrains what directory
+ clients can store as attribute values.</para>
+
+ <para>An attribute syntax is identified in an attribute type definition by
+ its OID. String-based syntax OIDs are optionally followed by a number, set
+ between braces, that represents a minimum upper bound on the number of
+ characters in the attribute value. For example, in the attribute type
+ definition shown above, the syntax is
+ <literal>1.3.6.1.4.1.1466.115.121.1.26{256}</literal>. The syntax is an
+ IA5 string (composed of characters from the international version of the
+ ASCII character set) that can contain at least 256 characters.</para>
+
+ <para>You can find a table matching attribute syntax OIDs with their
+ human-readable names in RFC 4517, <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc4517#appendix-A">Appendix A.
+ Summary of Syntax Object Identifiers</link>. The RFC describes
+ attribute syntaxes in detail. Alternatively, you can see the attribute
+ syntaxes that OpenDJ supports by opening the OpenDJ Control Panel and
+ browsing to Schema > Manage Schema > Attribute Syntaxes. You can
+ also list them by using the <command>dsconfig</command> command.</para>
+
+ <para>Although attribute syntaxes are often specified in attribute type
+ definitions, directory servers do not always check that attribute values
+ comply with attribute syntaxes. OpenDJ directory server does tend to
+ enforce compliance by default, in particular for certificates, country
+ strings, directory strings, JPEG photos, and telephone numbers. The aim
+ is to avoid accumulating garbage in your directory data.</para>
+
+ <para>If you are trying unsuccessfully to import non-compliant data from a
+ more lenient directory server, you can either clean the data before
+ importing it, or if cleaning the data is not an option, read <xref
+ linkend="schema-legacy-support" />.</para>
+
+ <para>When creating your own attribute type definitions, use existing
+ attribute syntaxes where possible. If you must create your own attribute
+ syntax, then consider the extensions in
+ <xref linkend="attr-syntax-schema-definition-extensions" />.</para>
+ </listitem>
+
+ <listitem>
+ <para>Matching rules determine how the directory server compares attribute
+ values to assertion values for LDAP search and LDAP compare
+ operations.</para>
+
+ <para>For example, suppose you search with the filter
+ <literal>(uid=bjensen)</literal>. The assertion value in this case is
+ <literal>bjensen</literal>.</para>
+
+ <para>OpenDJ has the following schema definition for the user ID
+ attribute.</para>
+
+ <programlisting language="ldif"
+ >attributeTypes: ( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' )
+ EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} X-ORIGIN 'RFC 4519' )</programlisting>
+
+ <para>When finding an equality match for your search, OpenDJ uses the
+ <literal>caseIgnoreMatch</literal> matching rule to check for user ID
+ attribute values that equal <literal>bjensen</literal> without regard
+ to case.</para>
+
+ <para>You can see the matching rules that OpenDJ supports by opening the
+ OpenDJ Control Panel and browsing to Schema > Manage Schema >
+ Matching Rules. Notice that many matching rules support string collation
+ in languages other than English. You can also list matching rules by
+ using the <command>dsconfig</command> command.</para>
+
+ <para>As you can read in examples like, <link
+ xlink:href="admin-guide#extensible-match-search"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Search: List
+ Active Accounts</citetitle></link>, OpenDJ matching rules enable
+ directory clients to do more interesting searches than simply comparing
+ strings. That example shows how to search for users who have
+ authenticated in the last three months.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>OpenDJ exposes schema over protocol through the
+ <literal>cn=schema</literal> entry. OpenDJ stores the schema definitions
+ corresponding to the entry in LDIF under the
+ <filename>config/schema/</filename> directory. Many standard definitions
+ and definitions pertaining to the server configuration are included at
+ installation time.</para>
+ </section>
+
+ <section xml:id="update-schema">
+ <title>Updating Directory Schema</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Schema definitions</secondary>
+ </indexterm>
+
+ <para>OpenDJ directory server is designed to permit updating the list of
+ directory schema definitions while the server is running. As a result you can
+ add support for new applications that require new attributes or new kinds
+ of entries without interrupting the directory service. OpenDJ also replicates
+ schema definitions, so the schema you add on one replica are propagated to
+ other replicas without you having to intervene manually.</para>
+
+ <para>As it is easy to introduce typos into schema definitions, the
+ best way to start defining your own schema is with the OpenDJ Control
+ Panel. Open the Control Panel > Schema > Manage Schema window to
+ get started creating your custom object classes and attribute types.</para>
+
+ <mediaobject xml:id="figure-manage-schema">
+ <imageobject>
+ <imagedata fileref="images/Manage-Schema.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>As object classes reference attribute types, you first create
+ custom attribute types, and then create the object class that references
+ the attribute types.</para>
+
+ <para>Create a custom attribute type through the New Attribute window.</para>
+
+ <mediaobject xml:id="figure-custom-attrtype">
+ <imageobject>
+ <imagedata fileref="images/custom-attrtype.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Using the New Object Class window, create an auxiliary object class
+ that allows your new custom attribute type. You set the type to Auxiliary
+ under Extra Options.</para>
+
+ <mediaobject xml:id="figure-custom-objclass">
+ <imageobject>
+ <imagedata fileref="images/custom-objclass.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+ <para>When you finish, the schema changes show up by default in the file
+ <filename>config/schema/99-user.ldif</filename>. Notice that the file name
+ starts with a number, 99. This number is larger than the numbers prefixing
+ other schema file names. In fact, OpenDJ reads the schema files in sorted
+ order, reading schema definitions as they occur. If OpenDJ reads a schema
+ definition for an object class before it has read the definitions of the
+ attribute types mentioned in the object class definition, then it displays
+ an error. Therefore, when naming your schema file, make sure the name appears
+ in the sorted list of file names <emphasis>after</emphasis> all the schema
+ files containing definitions that your schema definitions depends on. The
+ default file name for your schema, <filename>99-user.ldif</filename>, ensures
+ that your definitions load only after all of the schema files installed by
+ default.</para>
+
+ <para>You can create this file in the lab using the Control Panel, and then
+ apply the definitions in production by adapting the content for use with the
+ <command>ldapmodify</command> command, for example.</para>
+
+ <screen>$ cat config/schema/99-user.ldif
+dn: cn=schema
+objectClass: top
+objectClass: ldapSubentry
+objectClass: subschema
+cn: schema
+attributeTypes: ( temporary-fake-attr-id NAME 'myCustomAttribute' EQUALITY case
+ IgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstrings
+ Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
+objectClasses: ( temporary-fake-oc-id NAME 'myCustomObjClass
+ ' SUP top AUXILIARY MAY myCustomAttribute )
+modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
+modifyTimestamp: 20110620095948Z
+</screen>
+
+ <para>To test your schema definition, add the object class and attribute
+ to an entry.</para>
+
+ <screen>$ cat custom-attr.ldif
+dn: uid=bjensen,ou=People,dc=example,dc=com
+changetype: modify
+add: objectClass
+objectClass: myCustomObjClass
+-
+add: myCustomAttribute
+myCustomAttribute: Testing 1, 2, 3...
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename custom-attr.ldif
+Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com
+$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ myCustomAttribute
+dn: uid=bjensen,ou=People,dc=example,dc=com
+myCustomAttribute: Testing 1, 2, 3...
+</screen>
+
+ <para>In addition to supporting the standard schema definitions that are
+ described in <link xlink:href="http://tools.ietf.org/html/rfc4512#section-4.1"
+ >RFC 4512, section 4.1</link>, OpenDJ also supports the following extensions
+ that you can use when adding your own definitions.</para>
+
+ <variablelist xml:id="general-schema-definition-extensions">
+ <title>Extensions for All Schema Definitions</title>
+
+ <indexterm>
+ <primary>Schema</primary>
+ <secondary>Schema definition extensions</secondary>
+ </indexterm>
+
+ <varlistentry>
+ <term><literal>X-ORIGIN</literal></term>
+ <listitem>
+ <para>Used to specify the origin of a schema element. Examples include
+ <literal>X-ORIGIN 'RFC 4519'</literal>, <literal>X-ORIGIN
+ 'draft-ietf-ldup-subentry'</literal>, and <literal>X-ORIGIN
+ 'OpenDJ Directory Server'</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>X-SCHEMA-FILE</literal></term>
+ <listitem>
+ <para>Used to specify the relative path to the schema file containing the
+ schema element such as <literal>X-SCHEMA-FILE '00-core.ldif'</literal>.
+ Schema definitions are located by default in
+ <filename>/path/to/opendj/config/schema/*.ldif</filename> files.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist xml:id="attr-syntax-schema-definition-extensions">
+ <title>Extensions for Attribute Syntax Descriptions</title>
+
+ <indexterm>
+ <primary>Schema</primary>
+ <secondary>Schema definition extensions</secondary>
+ </indexterm>
+
+ <varlistentry>
+ <term><literal>X-ENUM</literal></term>
+ <listitem>
+ <para>Used to define a syntax that is an enumeration of values. The
+ following attribute syntax description defines a syntax allowing four
+ possible attribute values for example.</para>
+ <programlisting language="ldif"
+ >ldapSyntaxes: ( security-label-syntax-oid DESC 'Security Label'
+ X-ENUM ( 'top-secret' 'secret' 'confidential' 'unclassified' ) )</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>X-PATTERN</literal></term>
+ <listitem>
+ <para>Used to define a syntax based on a regular expression pattern, where
+ valid regular expressions are those defined for <link xlink:show="new"
+ xlink:href="http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html"
+ ><literal>java.util.regex.Pattern</literal></link>. The following attribute
+ syntax description defines a simple, lenient SIP phone URI syntax
+ check.</para>
+ <programlisting language="ldif"
+ >ldapSyntaxes: ( simple-sip-uri-syntax-oid DESC 'Lenient SIP URI Syntax'
+ X-PATTERN '^sip:[a-zA-Z0-9.]+@[a-zA-Z0-9.]+(:[0-9]+)?$' )</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>X-SUBST</literal></term>
+ <listitem>
+ <para>Used as a fallback to substitute a defined syntax for one that
+ OpenDJ does not implement. The following example substitutes Directory
+ String syntax, which has OID 1.3.6.1.4.1.1466.115.121.1.15, for a syntax
+ that OpenDJ does not implement.</para>
+ <programlisting language="ldif"
+ >ldapSyntaxes: ( non-implemented-syntax-oid DESC 'Not Implemented in OpenDJ'
+ X-SUBST '1.3.6.1.4.1.1466.115.121.1.15' )</programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist xml:id="attr-type-schema-definition-extensions">
+ <title>Extension for Attribute Type Descriptions</title>
+
+ <indexterm>
+ <primary>Schema</primary>
+ <secondary>Schema definition extensions</secondary>
+ </indexterm>
+
+ <varlistentry>
+ <term><literal>X-APPROX</literal></term>
+ <listitem>
+ <para><literal>X-APPROX</literal> is used to specify the approximate
+ matching rule to use for a given attribute type when not using the default,
+ which is the <link xlink:href="http://aspell.net/metaphone/"
+ xlink:show="new">double metaphone approximate match</link>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="schema-legacy-support">
+ <title>Relaxing Schema Checking to Import Legacy Data</title>
+ <indexterm>
+ <primary>Schema</primary>
+ <secondary>Legacy data</secondary>
+ </indexterm>
+
+ <para>By default, OpenDJ accepts data that follows the standards in terms of
+ what is allowed and what is rejected. You might have legacy data from a
+ directory service that is more lenient, allowing non-standard constructions
+ such as multiple structural object classes per entry, not checking attribute
+ value syntax, or even not respecting schema definitions.</para>
+
+ <para>For example, when importing data with multiple structural object
+ classes defined per entry, you can relax schema checking to warn rather
+ than reject entries having this issue.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set single-structural-objectclass-behavior:warn
+ --trustAll
+ --no-prompt</screen>
+
+ <para>You can allow attribute values that do not respect the defined syntax
+ with the <command>dsconfig</command> command as well.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set invalid-attribute-syntax-behavior:warn
+ --trustAll
+ --no-prompt</screen>
+
+ <para>You can even turn off schema checking altogether, although turning
+ off schema checking only really makes sense when you are absolutely sure
+ that the entries and attribute values respect the schema definitions, and
+ you simply want to turn off schema checking temporarily to speed up import
+ processing.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set check-schema:false
+ --trustAll
+ --no-prompt</screen>
+ </section>
+
+ <section xml:id="standard-schema">
+ <title>Standard Schema Included With OpenDJ</title>
+ <indexterm>
+ <primary>Schema</primary>
+ <secondary>Bundled definitions</secondary>
+ </indexterm>
+
+ <para>The following files under <filename>config/schema/</filename>
+ contain schema definitions out of the box.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <filename>00-core.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains a core set of attribute type and objectlass
+ definitions from several standard LDAP documents, including
+ draft-ietf-boreham-numsubordinates, draft-findlay-ldap-groupofentries,
+ draft-furuseth-ldap-untypedobject, draft-good-ldap-changelog,
+ draft-ietf-ldup-subentry, draft-wahl-ldap-adminaddr, RFC 1274, RFC 2079,
+ RFC 2256, RFC 2798, RFC 3045, RFC 3296, RFC 3671, RFC 3672, RFC 4512,
+ RFC 4519, RFC 4523, RFC 4524, RFC 4530, RFC 5020, and X.501.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>01-pwpolicy.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from
+ draft-behera-ldap-password-policy, which defines a mechanism for storing
+ password policy information in an LDAP directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>02-config.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains the attribute type and objectclass definitions
+ for use with the directory server configuration.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-changelog.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from
+ draft-good-ldap-changelog, which defines a mechanism for storing
+ information about changes to directory server data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-rfc2713.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 2713, which defines a
+ mechanism for storing serialized Java objects in the directory
+ server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-rfc2714.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 2714, which defines a
+ mechanism for storing CORBA objects in the directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-rfc2739.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 2739, which defines a
+ mechanism for storing calendar and vCard objects in the directory server.
+ Note that the definition in RFC 2739 contains a number of errors, and this
+ schema file has been altered from the standard definition in order to fix
+ a number of those problems.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-rfc2926.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 2926, which defines a
+ mechanism for mapping between Service Location Protocol (SLP)
+ advertisements and LDAP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-rfc3112.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 3112, which defines
+ the authentication password schema.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-rfc3712.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 3712, which defines a
+ mechanism for storing printer information in the directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>03-uddiv3.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 4403,
+ which defines a mechanism for storing UDDIv3 information in the directory
+ server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>04-rfc2307bis.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from the
+ draft-howard-rfc2307bis specification, used to store naming service
+ information in the directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>05-rfc4876.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions from RFC 4876, which defines
+ a schema for storing Directory User Agent (DUA) profiles and preferences
+ in the directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>05-samba.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions required when storing Samba
+ user accounts in the directory server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>05-solaris.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains schema definitions required for Solaris and
+ OpenSolaris LDAP naming services.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <filename>06-compat.ldif</filename>
+ </term>
+ <listitem>
+ <para>This file contains the attribute type and objectclass definitions
+ for use with the directory server configuration.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-server-process.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-server-process.xml
new file mode 100644
index 0000000..e473616
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-server-process.xml
@@ -0,0 +1,183 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-server-process'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Managing Server Processes</title>
+ <para>Using the OpenDJ Control Panel, you can start and stop local servers.
+ You can also start and stop OpenDJ using command-line tools, and use the
+ operating system's capabilities for starting OpenDJ at boot time.</para>
+
+ <para>This chapter demonstrates how to start and stop server processes
+ with command line tools and using operating system capabilities. This
+ chapter also describes what OpenDJ directory server does during startup
+ and shutdown, and how it recovers following an abrupt shutdown such as
+ happens during a system crash or when you kill the server process using
+ system tools.</para>
+
+ <section xml:id="start-server">
+ <title>Starting a Server</title>
+ <indexterm><primary>Start server</primary></indexterm>
+
+ <itemizedlist>
+ <para>Use one of the following techniques.</para>
+ <listitem>
+ <para>Use the <command>start-ds</command> command.</para>
+ <screen>$ opendj/bin/start-ds</screen>
+ <para>Alternatively, you can specify the --no-detach option to start
+ the server in the foreground.</para>
+ </listitem>
+ <listitem>
+ <para>(UNIX) Create an RC script, and then use the script to start
+ the server.</para>
+ <para>Unless you run OpenDJ as root, use the --userName
+ <replaceable>userName</replaceable> option to specify the user
+ who installed OpenDJ.</para>
+ <screen>$ sudo opendj/bin/create-rc-script
+ --outputFile /etc/init.d/opendj
+ --userName mark
+$ sudo /etc/init.d/opendj start</screen>
+ <para>For example, on Linux if you run OpenDJ as root, you can use the
+ RC script to start the server at system boot, and stop the server at
+ system shutdown.</para>
+ <screen>$ sudo update-rc.d opendj defaults
+update-rc.d: warning: /etc/init.d/opendj missing LSB information
+update-rc.d: see <http://wiki.debian.org/LSBInitScripts>
+ Adding system startup for /etc/init.d/opendj ...
+ /etc/rc0.d/K20opendj -> ../init.d/opendj
+ /etc/rc1.d/K20opendj -> ../init.d/opendj
+ /etc/rc6.d/K20opendj -> ../init.d/opendj
+ /etc/rc2.d/S20opendj -> ../init.d/opendj
+ /etc/rc3.d/S20opendj -> ../init.d/opendj
+ /etc/rc4.d/S20opendj -> ../init.d/opendj
+ /etc/rc5.d/S20opendj -> ../init.d/opendj</screen>
+ </listitem>
+ <listitem>
+ <para>(Windows) Register OpenDJ as a Windows Service, and then manage
+ the service through Windows administration tools.</para>
+ <screen>C:\Users\Mark> opendj\bat\windows-service.bat --enableService</screen>
+ </listitem>
+ </itemizedlist>
+
+ <para>By default OpenDJ saves a compressed version of the server
+ configuration used on successful startup. This ensures that the server
+ provides a "last known good" configuration, which can be used as a reference
+ or copied into the active configuration if the server fails to start with the
+ current active configuration. It is possible, though not usually recommended,
+ to turn this behavior off by changing the global server setting
+ <literal>save-config-on-successful-startup</literal> to
+ <literal>false</literal>.</para>
+ </section>
+
+ <section xml:id="stop-server">
+ <title>Stopping a Server</title>
+ <indexterm><primary>Stop server</primary></indexterm>
+
+ <itemizedlist>
+ <para>Use one of the following techniques.</para>
+ <listitem>
+ <para>Use the <command>stop-ds</command> command.</para>
+ <screen>$ opendj/bin/stop-ds</screen>
+ </listitem>
+ <listitem>
+ <para>(UNIX) Create an RC script, and then use the script to stop
+ the server.</para>
+ <screen>$ sudo opendj/bin/create-rc-script
+ --outputFile /etc/init.d/opendj
+ --userName mark
+$ sudo /etc/init.d/opendj stop</screen>
+ </listitem>
+ <listitem>
+ <para>(Windows) Register OpenDJ as a Windows Service, and then manage
+ the service through Windows administration tools.</para>
+ <screen>C:\Users\Mark> opendj\bat\windows-service.bat --enableService</screen>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="restart-server">
+ <title>Restarting a Server</title>
+ <indexterm><primary>Restart server</primary></indexterm>
+
+ <itemizedlist>
+ <para>Use one of the following techniques.</para>
+ <listitem>
+ <para>Use the <command>stop-ds</command> command.</para>
+ <screen>$ opendj/bin/stop-ds --restart</screen>
+ </listitem>
+ <listitem>
+ <para>(UNIX) Create an RC script, and then use the script to stop
+ the server.</para>
+ <screen>$ sudo opendj/bin/create-rc-script
+ --outputFile /etc/init.d/opendj
+ --userName mark
+$ /etc/init.d/opendj restart</screen>
+ </listitem>
+ <listitem>
+ <para>(Windows) Register OpenDJ as a Windows Service, and then manage
+ the service through Windows administration tools.</para>
+ <screen>C:\Users\Mark> opendj\bat\windows-service.bat --enableService</screen>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="crash-recovery">
+ <title>Server Recovery</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Crash recovery</secondary>
+ </indexterm>
+
+ <para>OpenDJ tends to show resilience when restarting after a crash or after
+ the server process is killed abruptly. OpenDJ might have to replay the last
+ few entries in a transaction log. Generally OpenDJ returns to service
+ quickly.</para>
+
+ <para>You can find Berkeley Java Edition database recovery messages in the
+ database log file, such as
+ <filename>/path/to/opendj/db/userRoot/je.info.0</filename>. The following
+ shows two example messages from that log, the first written at the beginning
+ of the recovery process, the second written at the end of the process.</para>
+
+ <screen>111104 10:23:48:967 CONFIG [/path/to/opendj/db/userRoot]Recovery
+ underway, found end of log
+...
+111104 10:23:49:015 CONFIG [/path/to/opendj/db/userRoot]Recovery finished:
+ Recovery Info ...</screen>
+
+ <para>What can take some time during server startup is preloading database
+ content into memory when the server starts. Objects cached in memory do not
+ survive a crash. By default, OpenDJ does not cache objects in memory before
+ starting to accept client requests. You can however set a
+ <link xlink:href="${configRefBase}local-db-backend.html#preload-time-limit"
+ ><literal>preload-time-limit</literal></link> for the database cache of your
+ backend if you do want to load objects into the database cache before
+ OpenDJ begins accepting client connections.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-troubleshooting.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-troubleshooting.xml
new file mode 100644
index 0000000..06a1af7
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-troubleshooting.xml
@@ -0,0 +1,983 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-troubleshooting'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ >
+ <title>Troubleshooting Server Problems</title>
+ <indexterm><primary>Troubleshooting</primary></indexterm>
+
+ <para>This chapter describes how to troubleshoot common server problems,
+ and how to collect information necessary when seeking support help.</para>
+
+ <section xml:id="troubleshoot-identify-problem">
+ <title>Identifying the Problem</title>
+
+ <para>In order to solve your problem methodically, save time by defining the
+ problem clearly up front. In a replicated environment with multiple directory
+ servers and many client applications, it can be particularly important to
+ pin down not only the problem (difference in observed behavior compared to
+ expected behavior), but also the circumstances and steps that lead to the
+ problem occurring.</para>
+
+ <itemizedlist>
+ <para>Answer the following questions.</para>
+
+ <listitem>
+ <para>How do you reproduce the problem?</para>
+ </listitem>
+
+ <listitem>
+ <para>What exactly is the problem? In other words, what is the behavior
+ you expected? What is the behavior you observed?</para>
+ </listitem>
+
+ <listitem>
+ <para>When did the problem start occurring? Under similar circumstances,
+ when does the problem not occur?</para>
+ </listitem>
+
+ <listitem>
+ <para>Is the problem permanent? Intermittent? Is it getting worse?
+ Getting better? Staying the same?</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Pinpointing the problem can sometimes indicate where you should
+ start looking for solutions.</para>
+ </section>
+
+ <section xml:id="troubleshoot-installation">
+ <title>Troubleshooting Installation & Upgrade</title>
+
+ <para>Installation and upgrade procedures result in a log file tracing
+ the operation. The log location differs by operating system, but look for
+ lines in the command output of the following form.</para>
+
+ <literallayout class="monospaced">See /var/....log for a detailed log of this operation.</literallayout>
+ </section>
+
+ <section xml:id="troubleshoot-reset-admin-passwords">
+ <title>Resetting Administrator Passwords</title>
+
+ <para>This section describes what to do if you forgot the password for
+ Directory Manager or for the global (replication) administrator.</para>
+
+ <procedure xml:id="reset-directory-manager-password">
+ <title>Resetting the Directory Manager's Password</title>
+ <indexterm>
+ <primary>Resetting passwords</primary>
+ <secondary>cn=Directory Manager</secondary>
+ </indexterm>
+
+ <para>OpenDJ directory server stores the entry for Directory Manager in
+ the LDIF representation of its configuration. You must be able to edit
+ directory server files in order to reset Directory Manager's password.</para>
+
+ <step>
+ <para>Generate the encoded version of the new password using the OpenDJ
+ <command>encode-password</command> command.</para>
+ <screen>$ cd /path/to/opendj/bin/
+$ ./encode-password --storageScheme SSHA512 --clearPassword password
+Encoded Password: "{SSHA512}yWqHnYV4a5llPvE7WHLe5jzK27oZQWLIlVcs9gySu4TyZJMg
+ NQNRtnR/Xx2xces1wu1dVLI9jVVtl1W4BVsmOKjyjr0rWrHt"</screen>
+ </step>
+
+ <step>
+ <para>Stop OpenDJ directory server while you edit the configuration.</para>
+ <screen>$ ./stop-ds</screen>
+ </step>
+
+ <step>
+ <para>Find Directory Manager's entry, which has DN <literal>cn=Directory
+ Manager,cn=Root DNs,cn=config</literal>, in
+ <filename>/path/to/opendj/config/config.ldif</filename>, and carefully
+ replace the <literal>userpassword</literal> attribute value with the
+ encoded version of the new password, taking care not to leave any
+ whitespace at the end of the line.</para>
+ <programlisting language="ldif"
+ >dn: cn=Directory Manager,cn=Root DNs,cn=config
+objectClass: person
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: ds-cfg-root-dn-user
+objectClass: top
+userpassword: {SSHA512}yWqHnYV4a5llPvE7WHLe5jzK27oZQWLIlVcs9gySu4TyZJMg
+ NQNRtnR/Xx2xces1wu1dVLI9jVVtl1W4BVsmOKjyjr0rWrHt
+givenName: Directory
+cn: Directory Manager
+ds-cfg-alternate-bind-dn: cn=Directory Manager
+sn: Manager
+ds-pwp-password-policy-dn: cn=Root Password Policy,cn=Password Policies
+ ,cn=config
+ds-rlim-time-limit: 0
+ds-rlim-lookthrough-limit: 0
+ds-rlim-idle-time-limit: 0
+ds-rlim-size-limit: 0</programlisting>
+ </step>
+
+ <step>
+ <para>Start OpenDJ directory server again.</para>
+ <screen>$ ./start-ds</screen>
+ </step>
+
+ <step>
+ <para>Verify that you can administer the server as Directory Manager using
+ the new password.</para>
+ <screen>$ ./dsconfig -p 4444 -h `hostname` -D "cn=Directory Manager" -w password
+
+
+>>>> OpenDJ configuration console main menu
+
+What do you want to configure?
+
+...
+
+Enter choice: q</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="reset-repl-admin-password">
+ <title>To Reset the Global Administrator's Password</title>
+ <indexterm>
+ <primary>Resetting passwords</primary>
+ <secondary>Global (replication) administrator</secondary>
+ </indexterm>
+
+ <para>When you enable replication, part of the process involves creating a
+ global administrator and setting that user's password. This user is present
+ on all replicas. If you chose default values, this user has DN
+ <literal>cn=admin,cn=Administrators,cn=admin data</literal>. You reset the
+ password as you would for any other user, though you do so as Directory
+ Manager.</para>
+
+ <step>
+ <para>Use the <command>ldappasswordmodify</command> command to reset the
+ global administrator's password</para>
+ <screen>$ cd /path/to/opendj/bin/
+$ ./ldappasswordmodify
+ --useStartTLS
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --authzID "cn=admin,cn=Administrators,cn=admin data"
+ --newPassword password
+The LDAP password modify operation was successful</screen>
+ </step>
+
+ <step>
+ <para>Let replication copy the password change to other replicas.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="troubleshoot-enable-debug-logging">
+ <title>Enabling Debug Logging</title>
+ <indexterm><primary>Debug log</primary></indexterm>
+ <indexterm>
+ <primary>Logs</primary>
+ <secondary>Debug</secondary>
+ </indexterm>
+
+ <para>OpenDJ can write debug information and stack traces to the server
+ debug log. What is logged depends both on debug targets that you create,
+ and also on the debug level that you choose.</para>
+
+ <procedure xml:id="configure-debug-logging">
+ <title>To Configure Debug Logging</title>
+
+ <step>
+ <para>Enable the debug log, <filename>opendj/logs/debug</filename>, which
+ is not enabled by default.</para>
+
+ <screen>$ dsconfig
+ set-log-publisher-prop
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --set enabled:true
+ --set default-debug-level:all
+ --no-prompt
+ --trustAll</screen>
+
+ <para>You can set <literal>default-debug-level</literal> to a less verbose
+ level if necessary.</para>
+ </step>
+
+ <step>
+ <para>Create a debug target or targets.</para>
+
+ <para>No debug targets are enabled by default.</para>
+
+ <screen>$ dsconfig
+ list-debug-targets
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --no-prompt
+ --trustAll
+
+Debug Target : debug-level : debug-category
+-------------:-------------:---------------
+
+$ </screen>
+
+ <para>A debug target specifies a fully-qualified OpenDJ Java package,
+ class, or method for which to log debug messages at the level you
+ specify.</para>
+
+ <screen>$ dsconfig
+ create-debug-target
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Debug Logger"
+ --type generic
+ --target-name org.opends.server.api
+ --set debug-level:all
+ --no-prompt
+ --trustAll</screen>
+ </step>
+
+ <step>
+ <para>Restart OpenDJ to see debug messages in the log.</para>
+
+ <screen>$ /path/to/opendj/bin/stop-ds --restart
+...
+$ tail -f /path/to/opendj/logs/debug
+...</screen>
+
+ <para>If you have set <literal>debug-level:all</literal>, OpenDJ generates
+ a great deal of output in the debug log file. Use debug logging very
+ sparingly on production systems.</para>
+ </step>
+ </procedure>
+ </section>
+
+ <section xml:id="troubleshoot-use-lockdown-mode">
+ <title>Preventing Access While You Fix Issues</title>
+ <indexterm><primary>Lockdown mode</primary></indexterm>
+
+ <para>Misconfiguration can potentially put OpenDJ in a state where you must
+ intervene, and where you need to prevent users and applications
+ from accessing the directory until you are done fixing the problem.</para>
+
+ <para>OpenDJ provides a <firstterm>lockdown mode</firstterm> that allows
+ connections only on the loopback address, and allows only operations
+ requested by root users, such as <literal>cn=Directory
+ Manager</literal>. You can use lockdown mode to prevent all but
+ administrative access to OpenDJ in order to repair the server.</para>
+
+ <para>To put OpenDJ into lockdown mode, the server must be running. You
+ cause the server to enter lockdown mode by using a task. Notice that
+ the modify operation is performed over the loopback address (accessing
+ OpenDJ on the local host).</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+dn: ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
+objectClass: top
+objectClass: ds-task
+ds-task-id: Enter Lockdown Mode
+ds-task-class-name: org.opends.server.tasks.EnterLockdownModeTask
+
+Processing ADD request for
+ ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks
+ADD operation successful for DN
+ ds-task-id=Enter Lockdown Mode,cn=Scheduled Tasks,cn=tasks</screen>
+
+ <para>OpenDJ logs a notice message in <filename>logs/errors</filename>
+ when lockdown mode takes effect.</para>
+
+ <literallayout class="monospaced">
+[30/Jan/2012:17:04:32 +0100] category=BACKEND severity=NOTICE msgID=9896350
+ msg=Lockdown task Enter Lockdown Mode finished execution</literallayout>
+
+ <para>Client applications that request operations get a message concerning
+ lockdown mode.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" +
+SEARCH operation failed
+Result Code: 53 (Unwilling to Perform)
+Additional Information: Rejecting the requested operation because the server
+ is in lockdown mode and will only accept requests from root users over
+ loopback connections</screen>
+
+ <para>You also leave lockdown mode by using a task.</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+dn: ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
+objectClass: top
+objectClass: ds-task
+ds-task-id: Leave Lockdown Mode
+ds-task-class-name: org.opends.server.tasks.LeaveLockdownModeTask
+
+Processing ADD request for
+ ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks
+ADD operation successful for DN
+ ds-task-id=Leave Lockdown Mode,cn=Scheduled Tasks,cn=tasks</screen>
+
+ <para>OpenDJ also logs a notice message when leaving lockdown.</para>
+
+ <literallayout class="monospaced">
+[30/Jan/2012:17:13:05 +0100] category=BACKEND severity=NOTICE msgID=9896350
+ msg=Leave Lockdown task Leave Lockdown Mode finished execution</literallayout>
+ </section>
+
+ <section xml:id="troubleshoot-import">
+ <title>Troubleshooting LDIF Import</title>
+
+ <para>By default OpenDJ requires that LDIF data you import respect standards.
+ In particular, OpenDJ is set to check that entries to import match the
+ schema defined for the server. You can temporarily bypass this check by using
+ the <option>--skipSchemaValidation</option> with the
+ <command>import-ldif</command> command.</para>
+
+ <para>OpenDJ also ensures by default that entries have only one structural
+ object class. You can relax this behavior by using the advanced global
+ configuration property,
+ <literal>single-structural-objectclass-behavior</literal>. This can be useful
+ when importing data exported from Sun Directory Server. For example, to
+ warn when entries have more than one structural object class instead of
+ reject such entries being added, set
+ <literal>single-structural-objectclass-behavior:warn</literal> as
+ follows.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname `hostname`
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set single-structural-objectclass-behavior:warn
+ --trustAll
+ --no-prompt</screen>
+
+ <para>By default, OpenDJ also checks syntax for a number of attribute types.
+ You can relax this behavior as well by using the <command>dsconfig
+ set-attribute-syntax-prop</command> command. See the list of attribute
+ syntaxes and use the <option>--help</option> option for further
+ information.</para>
+
+ <para>When running <command>import-ldif</command>, you can use the <option>-R
+ <replaceable>rejectFile</replaceable></option> option to capture entries that
+ could not be imported, and the <option>--countRejects</option> option to
+ return the number of rejected entries as the <command>import-ldif</command>
+ exit code.</para>
+
+ <para>Once you work through the issues with your LDIF data, reinstate the
+ default behavior to ensure automated checking.</para>
+ </section>
+
+ <section xml:id="troubleshoot-secure-connections">
+ <title>Troubleshooting TLS/SSL Connections</title>
+
+ <para>In order to trust the server certificate, client applications usually
+ compare the signature on certificates with those of the Certificate
+ Authorities (CAs) whose certificates are distributed with the client
+ software. For example, the Java environment is distributed with a key store
+ holding many CA certificates.</para>
+
+ <screen>$ keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
+ | wc -l
+ 334</screen>
+
+ <para>The self-signed server certificates that can be configured during
+ OpenDJ setup are not recognized as being signed by any CAs. Your software
+ therefore is configured not to trust the self-signed certificates by
+ default. You must either configure the client applications to accept the
+ self-signed certificates, or else use certificates signed by recognized
+ CAs.</para>
+
+ <para>You can further debug the network traffic by collecting debug traces.
+ To see the traffic going over TLS/SSL in debug mode, configure OpenDJ to dump
+ debug traces from <literal>javax.net.debug</literal> into the
+ <filename>logs/server.out</filename> file.</para>
+
+ <screen>OPENDJ_JAVA_ARGS="-Djavax.net.debug=all" start-ds</screen>
+
+ <section xml:id="troubleshoot-certificate-authentication">
+ <title>Troubleshooting Certificates & SSL Authentication</title>
+
+ <para>Replication uses SSL to protect directory data on the network.
+ In some configurations, replica can fail to connect to each other due
+ to SSL handshake errors. This leads to error log messages such as the
+ following.</para>
+
+ <screen>[21/Nov/2011:13:03:20 -0600] category=SYNC severity=NOTICE
+ msgID=15138921 msg=SSL connection attempt from myserver (123.456.789.012)
+ failed: Remote host closed connection during handshake</screen>
+
+ <itemizedlist>
+ <para>Notice these problem characteristics in the message above.</para>
+ <listitem>
+ <para>The host name, <literal>myserver</literal>, is not fully
+ qualified.</para>
+ <para>You should not see non fully qualified host names in the error logs.
+ Non fully qualified host names are a sign that an OpenDJ server has not
+ been configured properly.</para>
+ <para>Always install and configure OpenDJ using fully-qualified host names.
+ The OpenDJ administration connector, which is used by the
+ <command>dsconfig</command> command, and also replication depend upon SSL
+ and, more specifically, self-signed certificates for establishing SSL
+ connections. If the host name used for connection establishment does not
+ correspond to the host name stored in the SSL certificate then the SSL
+ handshake can fail. For the purposes of establishing the SSL connection,
+ a host name like <literal>myserver</literal> does not match
+ <literal>myserver.example.com</literal>, and vice versa.</para>
+ </listitem>
+ <listitem>
+ <para>The connection succeeded, but the SSL handshake failed, suggesting
+ a problem with authentication or with the cipher or protocol negotiation.
+ As most deployments use the same Java Virtual Machine, and the same JVM
+ configuration for each replica, the problem is likely not related to SSL
+ cipher or protocol negotiation, but instead lies with authentication.</para>
+ </listitem>
+ </itemizedlist>
+
+ <orderedlist>
+ <para>Follow these steps on each OpenDJ server to check whether the problem
+ lies with the host name configuration.</para>
+ <listitem>
+ <para>Make sure each OpenDJ server uses only fully qualified host names in
+ the replication configuration. You can obtain a quick summary by running
+ the following command against each server's configuration.</para>
+ <screen>$ grep ds-cfg-replication-server: config/config.ldif | sort | uniq</screen>
+ </listitem>
+ <listitem>
+ <para>Make sure that the host names in OpenDJ certificates also contain
+ fully qualified host names, and correspond to the host names found in the
+ previous step.</para>
+ <screen># Examine the certificates used for the administration connector.
+$ keytool -list -v -keystore config/admin-truststore
+ -storepass `cat config/admin-keystore.pin` |grep "^Owner:"
+
+# Examine the certificates used for replication.
+$ keytool -list -v -keystore config/ads-truststore
+ -storepass `cat config/ads-truststore.pin`| grep "^Owner:"
+ </screen>
+ </listitem>
+ </orderedlist>
+
+ <para>Sample output for a server on host <literal>opendj.example.com</literal>
+ follows.</para>
+ <screen>$ grep ds-cfg-replication-server: config/config.ldif |sort | uniq
+ds-cfg-replication-server: opendj.example.com:8989
+ds-cfg-replication-server: opendj.example.com:9989
+
+$ keytool -list -v -keystore config/admin-truststore
+-storepass `cat config/admin-keystore.pin` | grep "^Owner:"
+Owner: CN=opendj.example.com, O=Administration Connector Self-Signed Certificate
+
+$ keytool -list -v -keystore config/ads-truststore
+ -storepass `cat config/ads-truststore.pin`| grep "^Owner:"
+Owner: CN=opendj.example.com, O=OpenDJ Certificate
+Owner: CN=opendj.example.com, O=OpenDJ Certificate
+Owner: CN=opendj.example.com, O=OpenDJ Certificate</screen>
+
+ <itemizedlist>
+ <para>Unfortunately there is no easy solution to badly configured host
+ names. It is often easier and quicker simply to reinstall your OpenDJ
+ servers remembering to use fully qualified host names everywhere.</para>
+ <listitem>
+ <para>When using the <command>setup</command> tool to install and
+ configure a server ensure that the <option>-h</option> option is
+ included, and that it specifies the fully qualified host name. Make sure
+ you include this option even if you are not enabling SSL/StartTLS LDAP
+ connections (see <link
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-363"
+ >OPENDJ-363</link>).</para>
+ <para>If you are using the GUI installer, then make sure you specify the
+ fully qualified host name on the first page of the wizard.</para>
+ </listitem>
+ <listitem>
+ <para>When using the <command>dsreplication</command> tool to enable
+ replication make sure that any <option>--host</option> options include the
+ fully qualified host name.</para>
+ </listitem>
+ </itemizedlist>
+
+ <orderedlist>
+ <para>If you cannot reinstall the server, follow these steps.</para>
+ <listitem>
+ <para>Disable replication in each replica.</para>
+ <screen>$ dsreplication
+ disable
+ --disableAll
+ --port <replaceable>adminPort</replaceable>
+ --hostname <replaceable>hostName</replaceable>
+ --bindDN "cn=Directory Manager"
+ --adminPassword <replaceable>password</replaceable>
+ --trustAll
+ --no-prompt</screen>
+ </listitem>
+ <listitem>
+ <para>Stop and restart each server in order to clear the in-memory ADS
+ trust store backend.</para>
+ </listitem>
+ <listitem>
+ <para>Enable replication making certain that fully qualified host names
+ are used throughout</para>
+ <screen>$ dsreplication
+ enable
+ --adminUID admin
+ --adminPassword <replaceable>password</replaceable>
+ --baseDN dc=example,dc=com
+ --host1 <replaceable>hostName1</replaceable>
+ --port1 <replaceable>adminPort1</replaceable>
+ --bindDN1 "cn=Directory Manager"
+ --bindPassword1 <replaceable>password</replaceable>
+ --replicationPort1 <replaceable>replPort1</replaceable>
+ --host2 <replaceable>hostName2</replaceable>
+ --port2 <replaceable>adminPort2</replaceable>
+ --bindDN2 "cn=Directory Manager"
+ --bindPassword2 <replaceable>password</replaceable>
+ --replicationPort2 <replaceable>replPort2</replaceable>
+ --trustAll
+ --no-prompt</screen>
+ </listitem>
+ <listitem>
+ <para>Repeat the previous step for each remaining replica. In other words,
+ host1 with host2, host1 with host3, host1 with host4, ..., host1 with
+ hostN.</para>
+ </listitem>
+ <listitem>
+ <para>Initialize all remaining replica with the data from host1.</para>
+ <screen>$ dsreplication
+ initialize-all
+ --adminUID admin
+ --adminPassword password
+ --baseDN dc=example,dc=com
+ --hostname <replaceable>hostName1</replaceable>
+ --port 4444
+ --trustAll
+ --no-prompt</screen>
+ </listitem>
+ <listitem>
+ <para>Check that the host names are correct in the configuration and in
+ the key stores by following the steps you used to check for host name
+ problems. The only broken host name remaining should be in the key and
+ trust stores for the administration connector.</para>
+ <screen>$ keytool -list -v -keystore config/admin-truststore
+ -storepass `cat config/admin-keystore.pin` |grep "^Owner:"</screen>
+ </listitem>
+ <listitem>
+ <para>Stop each server, and then fix the remaining admin connector
+ certificate as described here in the procedure <link
+ xlink:href="admin-guide#replace-key-pair"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
+ Server Key Pair</citetitle></link>.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section xml:id="troubleshoot-compromised-key">
+ <title>Handling Compromised Keys</title>
+ <indexterm><primary>Certificates</primary></indexterm>
+ <indexterm><primary>SSL</primary></indexterm>
+
+ <para>As explained in <link xlink:href="admin-guide#chap-change-certs"
+ xlink:role="http://docbook.org/xlink/role/olink" xlink:show="new"><citetitle
+ >Changing Server Certificates</citetitle></link>, OpenDJ directory server
+ has different keys and key stores for different purposes. The public keys
+ used for replication are also used to encrypt shared secret symmetric keys
+ for example to encrypt and to sign back ups. This section looks at what to
+ do if either a key pair or secret key is compromised.</para>
+
+ <itemizedlist>
+ <para>How you deal with the problem depends on which key was
+ compromised.</para>
+
+ <listitem>
+ <para>For a key pair used for a client connection handler and with a
+ certificate signed by a certificate authority (CA), contact the CA for
+ help. The CA might choose to publish a certificate revocation list (CRL)
+ that identifies the certificate of the compromised key pair.</para>
+
+ <para>Also make sure you replace the key pair. See <link
+ xlink:href="admin-guide#replace-key-pair" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
+ Server Key Pair</citetitle></link> for specific steps.</para>
+ </listitem>
+
+ <listitem>
+ <para>For a key pair used for a client connection handler and that has
+ a self-signed certificate, follow the steps in <link
+ xlink:href="admin-guide#replace-key-pair" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
+ Server Key Pair</citetitle></link>, and make sure the clients remove the
+ compromised certificate from their trust stores, updating those trust
+ stores with the new certificate.</para>
+ </listitem>
+
+ <listitem>
+ <para>For a key pair that is used for replication, mark the key as
+ compromised as described below, and replace the key pair. See <link
+ xlink:href="admin-guide#replace-ads-cert" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Replace a
+ Server Key Pair</citetitle></link> for specific steps.</para>
+
+ <orderedlist>
+ <para>To mark the key pair as compromised, follow these steps.</para>
+
+ <listitem>
+ <para>Identity the key entry by searching administrative data on the
+ server whose key was compromised.</para>
+
+ <para>The server in this example is installed on
+ <literal>opendj.example.com</literal> with administration port
+ <literal>4444</literal>.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --hostname opendj.example.com
+ --baseDN "cn=admin data"
+ "(cn=opendj.example.com:4444)" ds-cfg-key-id
+dn: cn=opendj.example.com:4444,cn=Servers,cn=admin data
+ds-cfg-key-id: 4F2F97979A7C05162CF64C9F73AF66ED</screen>
+
+ <para>The key ID, <literal>4F2F97979A7C05162CF64C9F73AF66ED</literal>, is
+ the RDN of the key entry.</para>
+ </listitem>
+
+ <listitem>
+ <para>Mark the key as compromised by adding the attribute,
+ <literal>ds-cfg-key-compromised-time</literal>, to the key entry.</para>
+
+ <para>The attribute has generalized time syntax, and so takes as its
+ value the time at which the key was compromised expressed in generalized
+ time. In the following example, the key pair was compromised at 8:34 AM
+ UTC on March 21, 2013.</para>
+
+ <screen width="81">$ ldapmodify
+ --port 1389
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+dn: ds-cfg-key-id=4F2F97979A7C05162CF64C9F73AF66ED,cn=instance keys,cn=admin data
+changetype: modify
+add: ds-cfg-key-compromised-time
+ds-cfg-key-compromised-time: 201303210834Z
+
+Processing MODIFY request for ds-cfg-key-id=4F2F97979A7C05162CF64C9F73AF66ED,
+ cn=instance keys,cn=admin data
+MODIFY operation successful for DN ds-cfg-key-id=4F2F97979A7C05162CF64C9F73AF66ED
+ ,cn=instance keys,cn=admin data</screen>
+ </listitem>
+
+ <listitem>
+ <para>If the server uses encrypted or signed data, then the shared secret
+ keys used for encryption or signing and associated with the compromised
+ key pair should also be considered compromised. Therefore, mark all
+ shared secret keys encrypted with the instance key as compromised.</para>
+
+ <para>To identify the shared secret keys, find the list of secret keys
+ in the administrative data whose <literal>ds-cfg-symmetric-key</literal>
+ starts with the key ID of the compromised key.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN "cn=secret keys,cn=admin data"
+ "(ds-cfg-symmetric-key=4F2F97979A7C05162CF64C9F73AF66ED*)" dn
+dn: ds-cfg-key-id=fba16e59-2ce1-4619-96e7-8caf33f916c8,cn=secret keys,cn=admin d
+ ata
+
+dn: ds-cfg-key-id=57bd8b8b-9cc6-4a29-b42f-fb7a9e48d713,cn=secret keys,cn=admin d
+ ata
+
+dn: ds-cfg-key-id=f05e2e6a-5c4b-44d0-b2e8-67a36d304f3a,cn=secret keys,cn=admin d
+ ata</screen>
+
+ <para>For each such key, mark the entry with
+ <literal>ds-cfg-key-compromised-time</literal> as shown above for the
+ instance key.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Changes to administration data are replicated to other OpenDJ
+ servers in the replication topology.</para>
+ </listitem>
+
+ <listitem>
+ <para>For a shared secret key used for data encryption that has been
+ compromised, mark the key entry with
+ <literal>ds-cfg-key-compromised-time</literal> as shown in the example
+ above that demonstrates marking the instance key as compromised.</para>
+
+ <para>Again, changes to administration data are replicated to other OpenDJ
+ servers in the replication topology.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section xml:id="troubleshoot-connections">
+ <title>Troubleshooting Client Operations</title>
+
+ <para>By default OpenDJ logs information about all LDAP client operations in
+ <filename>logs/access</filename>, and all HTTP client operations in
+ <filename>logs/http-access</filename>. The following lines are wrapped for
+ readability, showing a search for the entry with
+ <literal>uid=bjensen</literal> as traced in the LDAP access log. In the access
+ log itself, each line starts with a time stamp.</para>
+
+ <screen>[27/Jun/2011:17:23:00 +0200] CONNECT conn=19 from=127.0.0.1:56641
+ to=127.0.0.1:1389 protocol=LDAP
+[27/Jun/2011:17:23:00 +0200] SEARCH REQ conn=19 op=0 msgID=1
+ base="dc=example,dc=com" scope=wholeSubtree filter="(uid=bjensen)" attrs="ALL"
+[27/Jun/2011:17:23:00 +0200] SEARCH RES conn=19 op=0 msgID=1
+ result=0 nentries=1 etime=3
+[27/Jun/2011:17:23:00 +0200] UNBIND REQ conn=19 op=1 msgID=2
+[27/Jun/2011:17:23:00 +0200] DISCONNECT conn=19 reason="Client Unbind"</screen>
+
+ <para>As you see, each client connection and set of LDAP operations are
+ traced, starting with a time stamp and information about the operation
+ performed, then including information about the connection, the operation
+ number for the sequence of operations performed by the client, a message
+ identification number, and additional information about the operation.</para>
+
+ <para>To match HTTP client operations with related internal server operations,
+ first prevent OpenDJ from suppressing internal operations from the LDAP access
+ log by using the <command>dsconfig</command> command to set the LDAP access
+ log publisher <literal>suppress-internal-operations</literal> advanced
+ property to <literal>false</literal>. Then match the values of the
+ <literal>x-connection-id</literal> field in the HTTP access log with
+ <literal>conn=<replaceable>id</replaceable></literal> values in the LDAP
+ access log.</para>
+
+ <para>For example, consider an HTTP GET request for the <literal>_id</literal>
+ field of the user <literal>newuser</literal>, which is handled by connection 4
+ as shown in <filename>logs/http-access</filename>.</para>
+
+ <screen>- 192.168.0.12 bjensen 22/May/2013:16:27:52 +0200
+ GET /users/newuser?_fields=_id HTTP/1.1 200
+ curl/7.21.4 4 12</screen>
+
+ <para>With internal operations logged in <filename>logs/access</filename>,
+ log lines for the related operations have <literal>conn=4</literal>.</para>
+
+ <screen>[22/May/2013:16:27:52 +0200] CONNECT conn=4
+ from=192.168.0.12:63593 to=192.168.0.12:8080 protocol=HTTP/1.1
+[22/May/2013:16:27:52 +0200] SEARCH REQ conn=4
+ op=0 msgID=0 base="ou=people,dc=example,dc=com" scope=wholeSubtree
+ filter="(&(objectClass=inetOrgPerson)(uid=bjensen))" attrs="1.1"
+[22/May/2013:16:27:52 +0200] SEARCH RES conn=4
+ op=0 msgID=0 result=0 nentries=1 etime=5
+[22/May/2013:16:27:52 +0200] BIND REQ conn=4
+ op=1 msgID=1 version=3 type=SIMPLE
+ dn="uid=bjensen,ou=People,dc=example,dc=com"
+[22/May/2013:16:27:52 +0200] BIND RES conn=4
+ op=1 msgID=1 result=0 authDN="uid=bjensen,ou=People,dc=example,dc=com"
+ etime=3
+[22/May/2013:16:27:52 +0200] SEARCH REQ conn=4
+ op=2 msgID=2 base="uid=newuser,ou=people,dc=example,dc=com" scope=baseObject
+ filter="(objectClass=*)" attrs="uid,etag"
+[22/May/2013:16:27:52 +0200] SEARCH RES conn=4
+ op=2 msgID=2 result=0 nentries=1 etime=4
+[22/May/2013:16:27:52 +0200] UNBIND REQ conn=4
+ op=3 msgID=3
+[22/May/2013:16:27:52 +0200] DISCONNECT conn=4
+ reason="Client Unbind"</screen>
+
+ <para>To help diagnose errors due to access permissions, OpenDJ supports the
+ get effective rights control. The control OID,
+ <literal>1.3.6.1.4.1.42.2.27.9.5.2</literal>, is not allowed by the default
+ global ACIs. You must therefore add access to use the get effective rights
+ control when not using it as Directory Manager.</para>
+
+ <section xml:id="troubleshoot-simple-paged-results">
+ <title>Clients Need Simple Paged Results Control</title>
+
+ <para>For Solaris and some versions of Linux you might see a message in
+ the OpenDJ access logs such as the following.</para>
+
+ <literallayout class="monospaced">
+The request control with Object Identifier (OID) "1.2.840.113556.1.4.319"
+cannot be used due to insufficient access rights</literallayout>
+
+ <para>This message means clients are trying to use the <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc2696">simple paged results
+ control</link> without authenticating. By default, OpenDJ includes a global
+ ACI to allow only authenticated users to use the control.</para>
+
+ <screen>$ dsconfig
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword "password"
+ get-access-control-handler-prop
+
+Property : Value(s)
+-----------:-------------------------------------------------------------------
+enabled : true
+global-aci : (extop="1.3.6.1.4.1.26027.1.6.1 || 1.3.6.1.4.1.26027.1.6.3 ||
+...
+ : (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 1.3.6.1.1.13.2
+ : || <emphasis role="strong">1.2.840.113556.1.4.319</emphasis> || 1.2.826.0.1.3344810.2.3 ||
+ : 2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 ||
+ : 1.2.840.113556.1.4.473 || 1.3.6.1.4.1.42.2.27.9.5.9") (version
+ : 3.0; acl "Authenticated users control access"; allow(read)
+ : userdn="ldap:///all";), (targetcontrol="2.16.840.1.113730.3.4.2 ||
+ : 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
+ : 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
+ : 2.16.840.1.113730.3.4.16") (version 3.0; acl "Anonymous control
+ : access"; allow(read) userdn="ldap:///anyone";)</screen>
+
+ <para>To grant anonymous (unauthenticated) user access to the control,
+ add the OID for the simple paged results control to the list of those in
+ the <literal>Anonymous control access</literal> global ACI.</para>
+
+ <screen>$ dsconfig
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword "password"
+ set-access-control-handler-prop
+ --remove global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 ||
+ 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
+ 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
+ 2.16.840.1.113730.3.4.16\") (version 3.0; acl \"Anonymous control access\";
+ allow(read) userdn=\"ldap:///anyone\";)"
+ --add global-aci:"(targetcontrol=\"2.16.840.1.113730.3.4.2 ||
+ 2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 ||
+ 1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 ||
+ 2.16.840.1.113730.3.4.16 || <emphasis role="strong">1.2.840.113556.1.4.319</emphasis>\")
+ (version 3.0; acl \"Anonymous control access\"; allow(read)
+ userdn=\"ldap:///anyone\";)"
+ --no-prompt</screen>
+
+ <para>Alternatively, stop OpenDJ, edit the corresponding ACI carefully in
+ <filename>/path/to/opendj/config/config.ldif</filename>, and restart OpenDJ.
+ <footnote><para>Unlike the <command>dsconfig</command> command, the
+ <filename>config.ldif</filename> file is not a public interface, so this
+ alternative should not be used in production.</para></footnote></para>
+ </section>
+ </section>
+
+ <section xml:id="troubleshoot-repl">
+ <title>Troubleshooting Replication</title>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Troubleshooting</secondary>
+ </indexterm>
+
+ <para>Replication can generally recover from conflicts and transient issues.
+ Replication does, however, require that update operations be copied
+ from server to server. It is therefore possible to experience temporary
+ delays while replicas converge, especially when the write operation load is
+ heavy. OpenDJ's tolerance for temporary divergence between replicas is what
+ allows OpenDJ to remain available to serve client applications even when
+ networks linking the replicas go down.</para>
+
+ <para>In other words, the fact that directory services are loosely convergent
+ rather than transactional is a feature, not a bug.</para>
+
+ <para>That said, you may encounter errors. Replication uses its own error log
+ file, <filename>logs/replication</filename>. Error messages in the log file
+ have <literal>category=SYNC</literal>. The messages have the following form.
+ Here the line is folded for readability.</para>
+
+ <screen>[27/Jun/2011:14:37:48 +0200] category=SYNC severity=INFORMATION msgID=14680169
+ msg=Replication server accepted a connection from 10.10.0.10/10.10.0.10:52859
+ to local address 0.0.0.0/0.0.0.0:8989 but the SSL handshake failed. This is
+ probably benign, but may indicate a transient network outage or a
+ misconfigured client application connecting to this replication server.
+ The error was: Remote host closed connection during handshake</screen>
+
+ <para>OpenDJ maintains historical information about changes in order to
+ bring replicas up to date, and to resolve replication conflicts. To prevent
+ historical information from growing without limit, OpenDJ purges historical
+ information after a configurable delay
+ (<literal>replication-purge-delay</literal>, default: 3 days). A replica
+ can become irrevocably out of sync if you restore it from a backup archive
+ older than the purge delay, or if you stop it for longer than the purge
+ delay. If this happens to you, disable the replica, and then reinitialize it
+ from a recent backup or from a server that is up to date.</para>
+ </section>
+
+ <section xml:id="troubleshoot-get-help">
+ <title>Asking For Help</title>
+
+ <para>When you cannot resolve a problem yourself, and want to ask for help,
+ clearly identify the problem and how you reproduce it, and also the version
+ of OpenDJ you use to reproduce the problem. The version includes both a
+ version number and also a build time stamp.</para>
+
+ <screen>$ dsconfig --version
+OpenDJ <?eval ${docTargetVersion}?>
+Build <replaceable>yyyymmddhhmmss</replaceable>Z</screen>
+
+ <itemizedlist>
+
+ <para>Be ready to provide additional information, too.</para>
+
+ <listitem>
+ <para>The output from the <command>java -version</command> command.</para>
+ </listitem>
+
+ <listitem>
+ <para><filename>access</filename> and <filename>errors</filename> logs
+ showing what the server was doing when the problem started occurring</para>
+ </listitem>
+
+ <listitem>
+ <para>A copy of the server configuration file,
+ <filename>config/config.ldif</filename>, in use when the problem started
+ occurring</para>
+ </listitem>
+
+ <listitem>
+ <para>Other relevant logs or output, such as those from client applications
+ experiencing the problem</para>
+ </listitem>
+
+ <listitem>
+ <para>A description of the environment where OpenDJ is running, including
+ system characteristics, host names, IP addresses, Java versions, storage
+ characteristics, and network characteristics. This helps to understand
+ the logs, and other information.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-tuning.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-tuning.xml
new file mode 100644
index 0000000..8dd2fdd
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-tuning.xml
@@ -0,0 +1,515 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-tuning'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Tuning Servers For Performance</title>
+ <indexterm><primary>Performance tuning</primary></indexterm>
+
+ <para>Server tuning refers to the art of adjusting server, JVM, and system
+ configuration to meet the service level performance requirements of directory
+ clients. In the optimal case you achieve service level performance
+ requirements without much tuning at all, perhaps only setting JVM runtime
+ options when installing OpenDJ.</para>
+
+ <para>If you are reading this chapter, however, you are probably not
+ facing an optimal situation. Instead you are looking for trade offs that
+ maximize performance for clients given the constraints of your deployment.
+ This chapter therefore aims to provide suggestions on how to measure and
+ to improve directory service performance for better trade offs.</para>
+
+ <section xml:id="perf-define-starting-points">
+ <title>Defining Performance Requirements & Constraints</title>
+
+ <para>Your key performance requirement is most likely to satisfy your
+ users or customers with the resources available to you. Before you can
+ solve potential performance problems, define what those users or customers
+ expect, and determine what resources you will have to satisfy their
+ expectations.</para>
+
+ <section xml:id="perf-sla">
+ <title>Service-Level Agreements</title>
+
+ <para>Service-level agreement (SLA) is a formal name for what directory
+ client applications and the people who run them expect from your service in
+ terms of performance.</para>
+
+ <para>SLAs might cover many aspects of the directory service. Whether or not
+ your SLA is formally defined, you ought to know what is expected, or at least
+ what you provide, in the following four areas.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Directory service <firstterm>response times</firstterm></para>
+
+ <para>Directory service response times range from less than a
+ millisecond on average across a low latency connection on the same
+ network to however long it takes your network to deliver the response.
+ More important than average or best response times is the response time
+ distribution, because applications set timeouts based on worst case
+ scenarios. For example, a response time performance requirement might
+ be defined as, "Directory response times must average less than 10
+ milliseconds for all operations except searches returning more than 10
+ entries, with 99.9% of response times under 40 milliseconds."</para>
+ </listitem>
+ <listitem>
+ <para>Directory service <firstterm>throughput</firstterm></para>
+
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Write throughput</secondary>
+ </indexterm>
+ <para>Directory service throughput can range up to many thousands of
+ operations per second. In fact there is no upper limit for read operations
+ such as searches, because only write operations must be replicated. To
+ increase read throughput, simply add additional replicas. More important
+ than average throughput is peak throughput. You might have peak write
+ throughput in the middle of the night when batch jobs update entries in
+ bulk, and peak binds for a special event or first thing Monday morning.
+ For example, a throughput performance requirement might be expressed as,
+ "The directory service must sustain a mix of 5,000 operations per second
+ made up of 70% reads, 25% modifies, 3% adds, and 2% deletes."</para>
+
+ <para>Even better is to mimic the behavior of key operations for
+ performance testing, so that you understand the patterns of operations
+ in the throughput you need to provide.</para>
+ </listitem>
+ <listitem>
+ <para>Directory service <firstterm>availability</firstterm></para>
+
+ <para>OpenDJ is designed to let you build directory services that are
+ basically available, including during maintenance and even upgrade of
+ individual servers. Yet, in order to reach very high levels of
+ availability, you must make sure not only that the software is
+ designed for availability, but also that your operations execute in
+ such a way as to preserve availability. Availability requirements
+ can be as lax as best effort, or as stringent as 99.999% or more
+ uptime.</para>
+
+ <para>Replication is the OpenDJ feature that allows you to build a
+ highly available directory service.</para>
+ </listitem>
+ <listitem>
+ <para>Directory service administrative support</para>
+
+ <para>Do not forget to make sure you understand and set expectations
+ about how you support your users when they run into trouble. Directory
+ services can perhaps help you turn password management into a self-service
+ visit to a web site, but some users no doubt still need to know what they
+ can expect if they need your help.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Writing down the SLA, even if your first version consists of
+ guesses, helps you reduce performance tuning from an open-ended project
+ to a clear set of measurable goals for a manageable project with a definite
+ outcome.</para>
+ </section>
+
+ <section xml:id="perf-constraints">
+ <title>Available Resources</title>
+
+ <para>With your SLA in hand, take inventory of the server, networks,
+ storage, people, and other resources at your disposal. Now is the time to
+ estimate whether it is possible to meet the requirements at all.</para>
+
+ <para>If for example you are expected to serve more throughput than the
+ network can transfer, maintain high availability with only one physical
+ machine, store 100 GB of backups on a 50 GB partition, or provide 24/7
+ support all alone, no amount of tweaking available resources is likely to
+ fix the problem.</para>
+
+ <para>When checking that the resources you have at least theoretically
+ suffice to meet your requirements, do not forget that high availability in
+ particular requires at least two of everything to avoid single points
+ of failure. Be sure to list the resources you expect to have, when and how
+ long you expect to have them, and why you need them. Also make note of
+ what is missing and why.</para>
+
+ <section xml:id="perf-hardware">
+ <title>Server Hardware Recommendations</title>
+
+ <para>Concerning server hardware, OpenDJ runs on systems with Java support,
+ and is therefore quite portable. That said, OpenDJ tends to perform best on
+ single-board, x86 systems due to low memory latency.</para>
+ </section>
+
+ <section xml:id="perf-storage">
+ <title>Storage Recommendations</title>
+
+ <para>OpenDJ is designed to work with local storage for the database,
+ not for network file systems such as NFS.</para>
+
+ <para>High performance storage is essential if you need to handle high
+ write throughput.</para>
+
+ <para>The Berkeley Java Edition DB works well with traditional disks as
+ long as the database cache size allows the DB to stay fully cached in
+ memory. This is the case because the database transaction log is append
+ only. When the DB is too big to stay cached in memory, however, then
+ cache misses lead to random disk access, slowing OpenDJ performance.</para>
+
+ <para>You might mitigate this effect by using solid-state disks for
+ persistent storage, or for file system cache.</para>
+
+ <para>Regarding database size on disk, if you have sustained write traffic
+ then the database grows to about twice its initial size on disk. This is
+ normal, and due to the way the database manages its logs. The size on disk
+ does not impact the DB cache size requirements.</para>
+ </section>
+ </section>
+ </section>
+
+ <section xml:id="perf-testing">
+ <title>Testing Performance</title>
+
+ <para>Even if you do not need high availability, you still need two of
+ everything, because your test environment needs to mimic your production
+ environment as closely as possible if you want to avoid nasty
+ surprises.</para>
+
+ <para>In your test environment, you set up OpenDJ as you will later in
+ production, and then conduct experiments to determine how best to meet
+ the requirements defined in the SLA.</para>
+
+ <para>Use <link xlink:show="new" xlink:href="admin-guide#make-ldif-1"
+ xlink:role="http://docbook.org/xlink/role/olink">make-ldif</link> to generate
+ sample data that match what you expect to find in production.</para>
+
+ <para>The OpenDJ LDAP Toolkit provides three command-line tools to help
+ with basic performance testing.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <link xlink:show="new" xlink:href="dev-guide#authrate-1"
+ xlink:role="http://docbook.org/xlink/role/olink">authrate</link> command
+ measures bind throughput and response time.</para>
+ </listitem>
+ <listitem>
+ <para>The <link xlink:show="new" xlink:href="dev-guide#modrate-1"
+ xlink:role="http://docbook.org/xlink/role/olink">modrate</link> command
+ measures modification throughput and response time.</para>
+ </listitem>
+ <listitem>
+ <para>The <link xlink:show="new" xlink:href="dev-guide#searchrate-1"
+ xlink:role="http://docbook.org/xlink/role/olink">searchrate</link> command
+ measures search throughput and response time.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>All three commands show you information about the response time
+ distributions, and allow you to perform tests at specific levels of
+ throughput.</para>
+
+ <para>If you need additional precision when evaluating response times, use
+ the global configuration setting <literal>etime-resolution</literal> to
+ change elapsed processing time resolution from milliseconds (default) to
+ nanoseconds.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set etime-resolution:nanoseconds
+ --no-prompt</screen>
+
+ <para>For more extensive testing, try the <link xlink:show="new"
+ xlink:href="http://dl.thezonemanager.com/slamd/">SLAMD Distributed Load
+ Generation Engine</link>. SLAMD is built to test more than just directory,
+ but is particularly well suited to test directory service performance, is
+ well documented, and is available under the Sun Public License. SLAMD is
+ designed both to offer an easy to used web-based interface, and also to
+ allow you to customize jobs to match the access patterns you expect from
+ client applications.</para>
+ </section>
+
+ <section xml:id="perf-tweaking">
+ <title>Tweaking OpenDJ Performance</title>
+
+ <para>When your tests show that OpenDJ performance is lacking even though
+ you have the right underlying network, hardware, storage, and system
+ resources in place, you can tweak OpenDJ performance in a number of ways.
+ This section mentions the most common tweaks.</para>
+
+ <section xml:id="perf-java">
+ <title>Java Settings</title>
+
+ <para>Default Java settings let you evaluate OpenDJ using limited system
+ resources. If you need high performance for production system, test with
+ the following JVM options. These apply to the Sun/Oracle JVM.</para>
+
+ <tip>
+ <para>To apply JVM settings for your server, edit
+ <filename>config/java.properties</filename>, and apply the changes with the
+ <command>dsjavaproperties</command> command.</para>
+ </tip>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>-server</option></term>
+ <listitem>
+ <para>Use the C2 compiler and optimizer.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-d64</option></term>
+ <listitem>
+ <para>To use a heap larger than about 3.5 GB on a 64-bit system, use
+ this option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Xms, -Xmx</option></term>
+ <listitem>
+ <para>Set both minimum and maximum heap size to the same value to avoid
+ resizing. Leave space for the entire DB cache and more.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Xmn</option></term>
+ <listitem>
+ <para>Set the new generation size between 1-4 GB for high throughput
+ deployments, but leave enough overall JVM heap to avoid overlaps with
+ the space used for DB cache.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-XX:MaxTenuringThreshold=1</option></term>
+ <listitem>
+ <para>Force OpenDJ to create only objects that have either a short
+ lifetime, or a long lifetime.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-XX:+UseConcMarkSweepGC</option></term>
+ <listitem>
+ <para>The CMS garbage collector tends to give the best performance
+ characteristics. You might also consider the G1 garbage collector.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-XX:+PrintGCDetails</option></term>
+ <term><option>-XX:+PrintGCTimeStamps</option></term>
+ <listitem>
+ <para>Use these when diagnosing JVM tuning problems. You can turn them
+ off when everything is running smoothly.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-XX:+UseCompressedOops</option></term>
+ <listitem>
+ <para>Java object pointers normally have the same size as native machine
+ pointers. If you run a small, but 64-bit JVM, then compressed object
+ pointers can save space. Set this option when you have a 64-bit JVM,
+ <option>-Xmx</option> less than 32 GB, and Java SE 6u23 or later.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section xml:id="perf-data-storage">
+ <title>Data Storage Settings</title>
+
+ <para>By default, OpenDJ compressing attribute descriptions and object class
+ sets to reduce data size. This is called compact encoding.</para>
+
+ <para>By default, OpenDJ does not however compress entries stored in its
+ backend database. If your entries hold values that compress well —
+ such as text, and not JPEG photos or MP3 audio — you can gain space
+ by setting the local DB backend property
+ <literal>entries-compressed</literal> to <literal>true</literal> before you
+ (re-)import data from LDIF. With <literal>entries-compressed: true</literal>
+ OpenDJ compresses entries before writing them to the database.<footnote>
+ <para>OpenDJ does not proactively rewrite all entries in the database after
+ you change the settings. Instead, to force OpenDJ to compress all entries,
+ import the data from LDIF.</para></footnote></para>
+
+ <screen>$ dsconfig
+ set-backend-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --set entries-compressed:true
+ --trustAll
+ --no-prompt
+$ import-ldif
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --ldifFile /path/to/Example.ldif
+ --backendID userRoot
+ --includeBranch dc=example,dc=com
+ --start 0
+Import task 20120917100628767 scheduled to start Sep 17, 2012 10:06:28 AM CEST</screen>
+ </section>
+
+ <section xml:id="perf-import">
+ <title>LDIF Import Settings</title>
+ <indexterm>
+ <primary>Importing data</primary>
+ <secondary>Performance</secondary>
+ </indexterm>
+
+ <para>You can tweak OpenDJ to speed up import of large LDIF files.</para>
+
+ <para>By default, the temporary directory used for scratch files is
+ <filename>import-tmp</filename> under the directory where you installed
+ OpenDJ. Use <command>import-ldif</command> with the
+ <option>--tmpdirectory</option> option to set this directory to a
+ <literal>tmpfs</literal> file system, such as
+ <filename>/tmp</filename>.</para>
+
+ <para>In some cases, you can improve performance by using the
+ <option>--threadCount</option> option with the
+ <command>import-ldif</command> command to set the thread count larger than
+ the default, which is twice the number of CPUs.</para>
+
+ <para>If you are certain your LDIF contains only valid entries with
+ correct syntax, because the LDIF was exported from OpenDJ with all checks
+ active for example, you can skip schema and DN validation. Use the
+ <option>--skipSchemaValidation</option> and
+ <option>--skipDNValidation</option> options with the
+ <command>import-ldif</command> command to skip validation.</para>
+ </section>
+
+ <section xml:id="perf-db-cache">
+ <title>Database Cache Settings</title>
+
+ <para>Database cache size is, by default, set as a percentage of the JVM
+ heap, using the backend property <literal>db-cache-percent</literal>.
+ Alternatively, you use the backend property
+ <literal>db-cache-size</literal> to set the size. If you set up multiple
+ database backends, the total percent of JVM heap used must remain less than
+ 100, and must leave space for other uses. Default settings work for servers
+ with one user data backend JVM heaps up to 2 GB. For heaps larger than 2 GB,
+ you can allocate a larger percentage of heap space to DB cache.</para>
+
+ <para>Depending on the size of your database, you have a choice to make
+ about database cache settings.</para>
+
+ <para>By caching the entire database in the JVM heap, you can get more
+ deterministic response times and limit disk I/O. Yet, caching the whole
+ DB can require a very large JVM, which you must pre-load on startup, and
+ which can result in long garbage collections and a difficult-to-manage
+ JVM. Test database pre-load on startup by setting the
+ <literal>preload-time-limit</literal> for the backend.</para>
+
+ <screen>$ dsconfig
+ set-backend-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --backend-name userRoot
+ --set preload-time-limit:30m
+ --trustAll
+ --no-prompt</screen>
+
+ <para>Database pre-load is single-threaded, and loads each database one
+ at a time.</para>
+
+ <para>By allowing file system cache to hold the portion of database that
+ does not fit in DB cache, you trade less deterministic and slightly slower
+ response times for not having to pre-load the DB and not having garbage
+ collection pauses with large JVMs. How you configure the file system cache
+ depends on your operating system.</para>
+ </section>
+
+ <section xml:id="perf-entry-cache">
+ <title>Entry Cache Settings</title>
+
+ <para>OpenDJ implements an entry cache. The entry cache is not designed to
+ cache every entry in your database, but is instead useful in cases where you
+ have a few, typically large entries that are regularly used. For example, if
+ you have a few large static groups and applications that regularly check
+ group membership, you could cache your group entries.</para>
+
+ <screen>$ dsconfig
+ create-entry-cache
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --cache-name "Large Group Entry Cache"
+ --type fifo
+ --set cache-level:1
+ --set include-filter:"(ou=Large Static Groups)"
+ --set max-entries:10
+ --set enabled:true
+ --trustAll
+ --no-prompt</screen>
+
+ <para>You can use the global setting, <literal>entry-cache-preload</literal>,
+ to force OpenDJ to load the entry cache as part of server startup.</para>
+
+ <screen>$ dsconfig
+ set-global-configuration-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --set entry-cache-preload:true
+ --no-prompt</screen>
+
+ <para>By default, OpenDJ does not pre-load the entry cache.</para>
+ </section>
+
+ <section xml:id="perf-logging">
+ <title>Logging Settings</title>
+
+ <para>Debug logs trace the internal workings of OpenDJ, and therefore
+ generally should be used sparingly, especially in high performance
+ deployments.</para>
+
+ <para>In general leave other logs active for production environments to
+ help troubleshoot any issues that arise.</para>
+
+ <para>For OpenDJ servers handling very high throughput, however, such as
+ 100,000 operations per second or more, the access log constitute a
+ performance bottleneck, as each client request results in multiple access log
+ messages. Consider disabling the access log in such cases.</para>
+
+ <screen>$ dsconfig
+ set-log-publisher-prop
+ --port 4444
+ --hostname opendj.example.com
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --publisher-name "File-Based Access Logger"
+ --set enabled:false
+ --trustAll
+ --no-prompt</screen>
+ </section>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-virtual-attrs-collective-attrs.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-virtual-attrs-collective-attrs.xml
new file mode 100644
index 0000000..ada1858
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/chap-virtual-attrs-collective-attrs.xml
@@ -0,0 +1,546 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-virtual-attrs-collective-attrs'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Working With Virtual and Collective Attributes</title>
+
+ <para>OpenDJ supports virtual attributes with dynamically generated values.
+ Virtual attributes are used by the server. You can also define your own.
+ OpenDJ also supports standard collective attributes as described in
+ <link xlink:href='http://tools.ietf.org/html/rfc3671'>RFC 3671</link>,
+ allowing entries to share common, read-only attribute values.</para>
+
+ <para>This chapter demonstrates how to define virtual and collective
+ attributes, showing common solutions as examples of their use.</para>
+
+ <section xml:id="virtual-attributes">
+ <title>Virtual Attributes</title>
+ <indexterm><primary>Virtual attributes</primary></indexterm>
+
+ <para>OpenDJ defines a number of virtual attributes by default.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>entryDN</literal></term>
+ <listitem><para>The value is the DN of the entry.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>entryUUID</literal></term>
+ <listitem><para>Provides a universally unique identifier for the
+ entry.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>etag</literal></term>
+ <listitem>
+ <para>Entity tag as defined in <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc2616#section-3.11"
+ >RFC 2616</link>, useful for checking whether an entry has changed since
+ you last read it from the directory.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>hasSubordinates</literal></term>
+ <listitem><para>Boolean. Whether the entry has children.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>numSubordinates</literal></term>
+ <listitem><para>Provides the number of direct child entries.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>isMemberOf</literal></term>
+ <listitem>
+ <para>Identifies groups the entry belongs to.</para>
+ <para>By default OpenDJ generates <literal>isMemberOf</literal> on user
+ entries (entries that have the object class <literal>person</literal>), and
+ on group entries (entries that have the object class
+ <literal>groupOfNames</literal>, <literal>groupOfUniqueNames</literal>, or
+ <literal>groupOfEntries</literal>). You can change this by editing
+ the filter property of the <literal>isMemberOf</literal> virtual
+ attribute configuration.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>member</literal></term>
+ <listitem><para>Generated for virtual static groups.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>uniqueMember</literal></term>
+ <listitem><para>Generated for virtual static groups.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>pwdPolicySubentry</literal></term>
+ <listitem>
+ <para>Identifies the password policy that applies to the
+ entry.</para>
+ <para>By default OpenDJ assigns <firstterm>root DN</firstterm> users
+ the password policy with DN <literal>cn=Root Password Policy,cn=Password
+ Policies,cn=config</literal> and regular users the password policy with DN
+ <literal>cn=Default Password Policy,cn=Password
+ Policies,cn=config</literal>. See <link
+ xlink:href="admin-guide#chap-pwd-policy"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
+ Password Policy</citetitle></link> for information on configuring and
+ assigning password policies.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>subschemaSubentry</literal></term>
+ <listitem><para>References the schema definitions.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>collectiveAttributeSubentries</literal></term>
+ <listitem><para>References applicable collective attribute
+ definitions.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>governingStructureRule</literal></term>
+ <listitem><para>References the rule on what type of subordinates the entry
+ can have.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>structuralObjectClass</literal></term>
+ <listitem><para>References the structural object class for the
+ entry.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>These virtual attributes are typically operational, so you get them
+ back from a search only when you request them.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com dc=example
+dn: dc=example,dc=com
+dc: example
+objectClass: domain
+objectClass: top
+
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com dc=example numSubordinates
+dn: dc=example,dc=com
+numSubordinates: 4
+</screen>
+ <indexterm>
+ <primary>Replication</primary>
+ <secondary>Not for virtual attributes</secondary>
+ </indexterm>
+
+ <para>You can use the existing virtual attribute types to create your
+ own virtual attributes, and you can also use the
+ <literal>user-defined</literal> type to create your own. The virtual
+ attribute is defined by the server configuration, which is not
+ replicated.</para>
+
+ <screen>$ dsconfig
+ create-virtual-attribute
+ --hostname opendj.example.com
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --name "Served By Description"
+ --type user-defined
+ --set enabled:true
+ --set attribute-type:description
+ --set base-dn:dc=example,dc=com
+ --set value:"Served by OpenDJ.Example.com"
+ --trustAll
+ --no-prompt
+$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen description
+dn: uid=bjensen,ou=People,dc=example,dc=com
+description: Served by OpenDJ.Example.com
+</screen>
+
+ <para>Collective attributes cover many use cases better than virtual
+ attributes.</para>
+ </section>
+
+ <section xml:id="collective-attributes">
+ <title>Collective Attributes</title>
+ <indexterm><primary>Collective attributes</primary></indexterm>
+
+ <para>Collective attributes provide a standard mechanism for defining
+ attributes that appear on all the entries in a subtree potentially filtered
+ by object class. Standard collective attribute type names have the prefix
+ <literal>c-</literal>.</para>
+
+ <para>OpenDJ extends collective attributes to make them easier to use.
+ You can define any OpenDJ attribute as collective using the
+ <literal>;collective</literal> attribute option. You can use LDAP filters
+ in your subtree specification for fine-grained control over which entries
+ have the collective attributes.</para>
+
+ <para>You can have entries inherit attributes from other entries using
+ collective attributes. You establish the relationship between entries either
+ by specifying another attribute of the entry that specifies the DN of the
+ entry from which to inherit the attributes, or by specifying how to construct
+ the RDN of the entry from which to inherit the attributes.</para>
+
+ <itemizedlist>
+ <para><link xlink:href="admin-guide#change-group-privileges"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Add Privileges
+ For a Group of Administrators</citetitle></link> demonstrates setting
+ administrative privileges in OpenDJ using collective attributes. The
+ following examples demonstrate additional ways to use collective
+ attributes in OpenDJ.</para>
+ <listitem><para><xref linkend="example-collective-attrs-cos" /></para></listitem>
+ <listitem><para><xref linkend="example-dept-from-manager" /></para></listitem>
+ <listitem><para><xref linkend="example-inherit-from-locality" /></para></listitem>
+ </itemizedlist>
+
+ <example xml:id="example-collective-attrs-cos"><?dbfo keep-together="auto"?>
+ <title>Class of Service With Collective Attributes</title>
+
+ <para>This example defines attributes that specify services available to
+ a user depending on that user's service level.</para>
+
+ <note>
+ <para>The following example depends on the <literal>cos</literal> object
+ class, and the <literal>classOfService</literal> attribute type defined but
+ commented out in the <link xlink:show="new"
+ xlink:href="http://opendj.forgerock.org/Example.ldif"><filename
+ >Example.ldif</filename></link> file imported as sample data. To try this
+ example for yourself, add the attribute type and object class definitions
+ in comments near the top of the file, and then uncomment the
+ <literal>objectClass: cos</literal> and <literal>classOfService</literal>
+ attribute lines in <filename>Example.ldif</filename> before importing
+ the data into OpenDJ.</para>
+ </note>
+
+ <para>This example positions collective attributes that depend on the
+ <literal>classOfService</literal> attribute values.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>For entries with <literal>classOfService: bronze</literal>,
+ <literal>mailQuota</literal> is set to 1 GB, and
+ <literal>diskQuota</literal> is set to 10 GB.</para>
+ </listitem>
+ <listitem>
+ <para>For entries with <literal>classOfService: silver</literal>,
+ <literal>mailQuota</literal> is set to 5 GB, and
+ <literal>diskQuota</literal> is set to 50 GB.</para>
+ </listitem>
+ <listitem>
+ <para>For entries with <literal>classOfService: gold</literal>,
+ <literal>mailQuota</literal> is set to 10 GB, and
+ <literal>diskQuota</literal> is set to 100 GB.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>You define collective attributes in the user data using a subentry.
+ In other words, collective attributes can be replicated. Collective
+ attributes use attributes defined in the directory schema. First, add the
+ <literal>mailQuote</literal> and <literal>diskQuota</literal> attributes,
+ and adjust the definition of the <literal>cos</literal> object class to
+ allow the two quota attributes.</para>
+
+ <screen>$ cat quotas.ldif
+dn: cn=schema
+changetype: modify
+add: attributeTypes
+attributeTypes: ( example-class-of-service-attribute-type NAME 'classOfService
+ ' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnore
+ SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE USAGE user
+ Applications X-ORIGIN 'OpenDJ Documentation Examples' )
+-
+add: attributeTypes
+attributeTypes: ( example-class-of-service-disk-quota NAME 'diskQuota
+ ' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR case
+ IgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE user
+ Applications X-ORIGIN 'OpenDJ Documentation Examples' )
+-
+add: attributeTypes
+attributeTypes: ( example-class-of-service-mail-quota NAME 'mailQuota
+ ' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR case
+ IgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE user
+ Applications X-ORIGIN 'OpenDJ Documentation Examples' )
+-
+add: objectClasses
+objectClasses: ( example-class-of-service-object-class NAME 'cos' SUP top AUX
+ ILIARY MAY ( classOfService $ diskQuota $ mailQuota ) X-ORIGIN 'OpenDJ Doc
+ umentation Examples' )
+
+$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --filename quotas.ldif
+Processing MODIFY request for cn=schema
+MODIFY operation successful for DN cn=schema</screen>
+
+ <para>Use the following collective attribute definitions to set the quotas
+ depending on class of service.</para>
+
+ <programlisting language="ldif"># cos.ldif: quotas by class of service
+dn: cn=Bronze Class of Service,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: Bronze Class of Service
+diskQuota;collective: 10 GB
+mailQuota;collective: 1 GB
+subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ bronze)" }
+
+dn: cn=Silver Class of Service,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: Silver Class of Service
+diskQuota;collective: 50 GB
+mailQuota;collective: 5 GB
+subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ silver)" }
+
+dn: cn=Gold Class of Service,dc=example,dc=com
+objectClass: collectiveAttributeSubentry
+objectClass: extensibleObject
+objectClass: subentry
+objectClass: top
+cn: Gold Class of Service
+diskQuota;collective: 100 GB
+mailQuota;collective: 10 GB
+subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ gold)" }
+</programlisting>
+
+ <para>You can add the collective attribute subentries by using the
+ <command>ldapmodify</command> command.</para>
+
+ <screen>$ ldapmodify
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --defaultAdd
+ --filename cos.ldif
+Processing ADD request for cn=Bronze Class of Service,dc=example,dc=com
+ADD operation successful for DN cn=Bronze Class of Service,dc=example,dc=com
+Processing ADD request for cn=Silver Class of Service,dc=example,dc=com
+ADD operation successful for DN cn=Silver Class of Service,dc=example,dc=com
+Processing ADD request for cn=Gold Class of Service,dc=example,dc=com
+ADD operation successful for DN cn=Gold Class of Service,dc=example,dc=com</screen>
+
+ <para>With the collective attributes defined, you can see the results on
+ user entries.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=bjensen
+ classOfService mailQuota diskQuota
+dn: uid=bjensen,ou=People,dc=example,dc=com
+mailQuota: 1 GB
+classOfService: bronze
+diskQuota: 10 GB
+
+$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=kvaughan
+ classOfService mailQuota diskQuota
+dn: uid=kvaughan,ou=People,dc=example,dc=com
+mailQuota: 5 GB
+classOfService: silver
+diskQuota: 50 GB
+
+$ ldapsearch
+ --port 1389
+ --baseDN dc=example,dc=com
+ uid=scarter
+ classOfService mailQuota diskQuota
+dn: uid=scarter,ou=People,dc=example,dc=com
+mailQuota: 10 GB
+classOfService: gold
+diskQuota: 100 GB</screen>
+ </example>
+
+ <example xml:id="example-dept-from-manager"><?dbfo keep-together="auto"?>
+ <title>Inheriting an Attribute From the Manager's Entry</title>
+
+ <para>This example demonstrates how to have OpenDJ set an employee's
+ department number using the manager's department number. To try the example,
+ first import <link xlink:href="http://opendj.forgerock.org/Example.ldif"
+ xlink:show="new"><filename>Example.ldif</filename></link> into OpenDJ in
+ order to load the appropriate sample data.</para>
+
+ <para>For this example the relationship between employee entries and manager
+ entries is based on the manager attributes on employee entries. Each
+ <literal>manager</literal> attribute on an employee's entry specifies the
+ DN of the manager's entry. OpenDJ retrieves the department number from the
+ manager's entry to populate the attribute on the employee's entry.</para>
+
+ <para>The collective attribute subentry that specifies the relationship
+ looks like this:</para>
+
+ <programlisting language="ldif"
+ >dn: cn=Inherit Department Number From Manager,dc=example,dc=com
+objectClass: top
+objectClass: subentry
+objectClass: inheritedCollectiveAttributeSubentry
+objectClass: inheritedFromDNCollectiveAttributeSubentry
+cn: Inherit Department Number From Manager
+subtreeSpecification: { base "ou=People" }
+inheritFromDNAttribute: manager
+inheritAttribute: departmentNumber
+
+</programlisting>
+
+ <para>This entry specifies that users inherit department number from their
+ manager.</para>
+
+ <para>As seen in <filename>Example.ldif</filename>, Babs Jensen's manager
+ is Torrey Rigden.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+manager: uid=trigden, ou=People, dc=example,dc=com</programlisting>
+
+ <para>Torrey's department number is 3001.</para>
+
+ <programlisting language="ldif">dn: uid=trigden,ou=People,dc=example,dc=com
+departmentNumber: 3001</programlisting>
+
+ <para>Babs inherits her department number from Torrey.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen
+ departmentNumber
+dn: uid=bjensen,ou=People,dc=example,dc=com
+departmentNumber: 3001</screen>
+ </example>
+
+ <example xml:id="example-inherit-from-locality"><?dbfo keep-together="auto"?>
+ <title>Inheriting Attributes From the Locality</title>
+
+ <para>This example demonstrates how to have OpenDJ set a user's language
+ preferences and street address based on locality. To try the example, first
+ import <link xlink:href="http://opendj.forgerock.org/Example.ldif"
+ xlink:show="new"><filename>Example.ldif</filename></link> into OpenDJ in
+ order to load the appropriate sample data.</para>
+
+ <para>For this example the relationship between entries is based on locality.
+ The collective attribute subentry specifies how to construct the RDN of the
+ object holding the attribute values to inherit.</para>
+
+ <programlisting language="ldif"
+ >dn: cn=Inherit From Locality,dc=example,dc=com
+objectClass: top
+objectClass: subentry
+objectClass: inheritedCollectiveAttributeSubentry
+objectClass: inheritedFromRDNCollectiveAttributeSubentry
+cn: Inherit From Locality
+subtreeSpecification: { base "ou=People" }
+inheritFromBaseRDN: ou=Locations
+inheritFromRDNAttribute: l
+inheritFromRDNType: l
+inheritAttribute: preferredLanguage
+inheritAttribute: street
+collectiveConflictBehavior: real-overrides-virtual
+
+</programlisting>
+
+ <para>This specifies that the RDN of the entry from which to inherit
+ attributes is like <literal>l=<replaceable
+ >localityName</replaceable>,ou=Locations</literal>, where <replaceable
+ >localityName</replaceable> is the value of the <literal>l</literal>
+ (<literal>localityName</literal>) attribute on the user's entry.</para>
+
+ <para>In other words, if the user's entry has <literal>l: Bristol</literal>,
+ then the RDN of the entry from which to inherit attributes starts with
+ <literal>l=Bristol,ou=Locations</literal>. The actual entry looks like
+ this:</para>
+
+ <programlisting language="ldif">dn: l=Bristol,ou=Locations,dc=example,dc=com
+objectClass: top
+objectClass: locality
+objectClass: extensibleObject
+l: Bristol
+street: 60 Queen Square
+preferredLanguage: en-gb
+
+</programlisting>
+
+ <para>The subentry also specifies two attributes to inherit for preferred
+ language and street address.</para>
+
+ <para>The object class <literal>extensibleObject</literal> is added to allow
+ the entry to take a preferred language.<footnote><para>The object class
+ <literal>extensibleObject</literal> means, "Let me add whatever attributes
+ I want." It is usually better practice to add your own auxiliary object class
+ if you need to decorate an entry with more attributes. The shortcut is taken
+ here as the focus of this example is not schema extension, but instead how
+ to use collective attributes.</para></footnote></para>
+
+ <para>Notice the last line of the collective attribute subentry:</para>
+
+ <literallayout class="monospaced"
+ >collectiveConflictBehavior: real-overrides-virtual</literallayout>
+
+ <para>This line says that if a collective attribute clashes with a real
+ attribute, the real value takes precedence over the virtual, collective
+ value. You can also set <literal>collectiveConflictBehavior</literal> to
+ <literal>virtual-overrides-real</literal> for the opposite precedence, or to
+ <literal>merge-real-and-virtual</literal> to keep both sets of values.</para>
+
+ <para>Here, users can set their own language preferences. When users set
+ language preferences manually, the collective attribute subentry is
+ configured to give the user's settings precedence over the locality-based
+ setting, which is only a default guess.</para>
+
+ <para>Sam Carter is located in Bristol. Sam has specified no preferred
+ languages.</para>
+
+ <programlisting language="ldif">dn: uid=scarter,ou=People,dc=example,dc=com
+l: Bristol</programlisting>
+
+ <para>Sam inherits both the street address and also preferred language from
+ the Bristol locality.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=scarter
+ preferredLanguage street
+dn: uid=scarter,ou=People,dc=example,dc=com
+preferredLanguage: en-gb
+street: 60 Queen Square</screen>
+
+ <para>Babs's locality is San Francisco. Babs prefers English, but also knows
+ Korean.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+preferredLanguage: en, ko;q=0.8
+l: San Francisco</programlisting>
+
+ <para>Babs inherits the street address from the San Francisco locality, but
+ keeps her language preferences.</para>
+
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen
+ preferredLanguage street
+dn: uid=bjensen,ou=People,dc=example,dc=com
+preferredLanguage: en, ko;q=0.8
+street: 500 3rd Street</screen>
+ </example>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/JXplorer-dsml.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/JXplorer-dsml.png
new file mode 100644
index 0000000..9609fdc
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/JXplorer-dsml.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Entries.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Entries.png
new file mode 100644
index 0000000..3b5fbd8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Entries.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Schema.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Schema.png
new file mode 100644
index 0000000..dc94a91
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/Manage-Schema.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/OpenDJ-Control-Panel.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/OpenDJ-Control-Panel.png
new file mode 100644
index 0000000..a227df7
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/OpenDJ-Control-Panel.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/create-vlv-index.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/create-vlv-index.png
new file mode 100644
index 0000000..9880702
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/create-vlv-index.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-attrtype.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-attrtype.png
new file mode 100644
index 0000000..37da5f9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-attrtype.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-objclass.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-objclass.png
new file mode 100644
index 0000000..ba09093
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/custom-objclass.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/keystores.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/keystores.png
new file mode 100644
index 0000000..1bf728d
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/keystores.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-right.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-right.png
new file mode 100644
index 0000000..ba6b7ea
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-right.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-wrong.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-wrong.png
new file mode 100644
index 0000000..48f8062
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/repl-topologies-wrong.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-monitor-repl.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-monitor-repl.png
new file mode 100644
index 0000000..99292d8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-monitor-repl.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-setup.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-setup.png
new file mode 100644
index 0000000..3577c2b
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replA-setup.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-data-repl.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-data-repl.png
new file mode 100644
index 0000000..dee2e81
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-data-repl.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-global-admin.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-global-admin.png
new file mode 100644
index 0000000..94a7ce1
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-global-admin.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-setup.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-setup.png
new file mode 100644
index 0000000..c29ffdc
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/replB-setup.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/standalone-repl.png b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/standalone-repl.png
new file mode 100644
index 0000000..b463447
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/images/standalone-repl.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/index.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/index.xml
new file mode 100644
index 0000000..cc280db
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/index.xml
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2014 ForgeRock AS
+ !
+-->
+<book xml:id='admin-guide'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info>
+ <xinclude:include href="../shared/mediaobject-fr-logo.xml" />
+ <title>OpenDJ Administration Guide</title>
+ <subtitle>Version ${docTargetVersion}</subtitle>
+ <abstract>
+ <para>Hands-on guide to configuring and using OpenDJ features. The OpenDJ
+ project offers open source LDAP directory services in Java.</para>
+ </abstract>
+ <copyright>
+ <year>2011-2014</year>
+ <holder>ForgeRock AS</holder>
+ </copyright>
+ <authorgroup>
+ <author>
+ <personname><firstname>Mark </firstname><surname>Craig</surname></personname>
+ </author>
+ <author>
+ <personname><firstname>Nemanja </firstname><surname>Lukić</surname></personname>
+ </author>
+ <author>
+ <personname><firstname>Ludovic </firstname><surname>Poitou</surname></personname>
+ </author>
+ <author>
+ <personname><firstname>Chris </firstname><surname>Ridd</surname></personname>
+ <xinclude:include href="../shared/affiliation-fr.xml"/>
+ </author>
+ </authorgroup>
+ <xinclude:include href='../legal.xml' />
+ <date>${publicationDate}</date>
+ <pubdate>${publicationDate}</pubdate>
+ <releaseinfo>${softwareReleaseDate}</releaseinfo>
+ </info>
+
+ <toc />
+
+ <xinclude:include href="preface.xml" />
+
+ <xinclude:include href='chap-admin-tools.xml' />
+ <xinclude:include href='chap-server-process.xml' />
+ <xinclude:include href='chap-import-export.xml' />
+ <xinclude:include href='chap-connection-handlers.xml' />
+ <xinclude:include href='chap-privileges-acis.xml' />
+ <xinclude:include href='chap-ldap-operations.xml' />
+ <xinclude:include href='chap-rest-operations.xml' />
+ <xinclude:include href='chap-indexing.xml' />
+ <xinclude:include href='chap-replication.xml' />
+ <xinclude:include href='chap-backup-restore.xml' />
+ <xinclude:include href='chap-pwd-policy.xml' />
+ <xinclude:include href='chap-account-lockout.xml' />
+ <xinclude:include href='chap-resource-limits.xml' />
+ <xinclude:include href='chap-groups.xml' />
+ <xinclude:include href='chap-attribute-uniqueness.xml' />
+ <xinclude:include href='chap-schema.xml' />
+ <xinclude:include href='chap-referrals.xml' />
+ <xinclude:include href='chap-virtual-attrs-collective-attrs.xml' />
+ <xinclude:include href='chap-pta.xml' />
+ <xinclude:include href='chap-samba.xml' />
+<!-- <xinclude:include href='chap-load-balancing.xml' /> -->
+<!-- <xinclude:include href='chap-failover.xml' /> -->
+<!-- <xinclude:include href='chap-chaining.xml' /> -->
+ <xinclude:include href='chap-monitoring.xml' />
+ <xinclude:include href='chap-tuning.xml' />
+ <xinclude:include href='chap-change-certs.xml' />
+ <xinclude:include href='chap-mv-servers.xml' />
+ <xinclude:include href='chap-troubleshooting.xml' />
+
+ <reference xml:id="admin-tools-ref">
+ <title>Tools Reference</title>
+
+ <partintro>
+ <para>You can find the tools under the <filename>bin/</filename> or
+ <filename>bat\</filename> folder where you installed OpenDJ directory
+ server. For example, <filename>/path/to/opendj/bin</filename>.</para>
+ </partintro>
+
+ <xinclude:include href='../shared/man-backup.xml' />
+ <xinclude:include href='../shared/man-base64.xml' />
+ <xinclude:include href='../shared/man-control-panel.xml' />
+ <xinclude:include href='../shared/man-create-rc-script.xml' />
+ <xinclude:include href='../shared/man-dbtest.xml' />
+ <xinclude:include href='../shared/man-dsconfig.xml' />
+ <xinclude:include href='../shared/man-dsframework.xml' />
+ <xinclude:include href='../shared/man-dsjavaproperties.xml' />
+ <xinclude:include href='../shared/man-dsreplication.xml' />
+ <xinclude:include href='../shared/man-encode-password.xml' />
+ <xinclude:include href='../shared/man-export-ldif.xml' />
+ <xinclude:include href='../shared/man-import-ldif.xml' />
+ <xinclude:include href='man-ldapcompare.xml' />
+ <xinclude:include href='../shared/man-ldapdelete.xml' />
+ <xinclude:include href='man-ldapmodify.xml' />
+ <xinclude:include href='man-ldappasswordmodify.xml' />
+ <xinclude:include href='man-ldapsearch.xml' />
+ <xinclude:include href='../shared/man-ldif-diff.xml' />
+ <xinclude:include href='man-ldifmodify.xml' />
+ <xinclude:include href='man-ldifsearch.xml' />
+ <xinclude:include href='../shared/man-list-backends.xml' />
+ <xinclude:include href='../shared/man-make-ldif.xml' />
+ <xinclude:include href='../shared/man-make-ldif-template.xml' />
+ <xinclude:include href='../shared/man-manage-account.xml' />
+ <xinclude:include href='../shared/man-manage-tasks.xml' />
+ <xinclude:include href='../shared/man-rebuild-index.xml' />
+ <xinclude:include href='../shared/man-restore.xml' />
+ <xinclude:include href='../shared/man-setup.xml' />
+ <xinclude:include href='../shared/man-start-ds.xml' />
+ <xinclude:include href='../shared/man-status.xml' />
+ <xinclude:include href='../shared/man-stop-ds.xml' />
+ <xinclude:include href='../shared/man-uninstall.xml' />
+ <xinclude:include href='../shared/man-upgrade.xml' />
+ <xinclude:include href='../shared/man-verify-index.xml' />
+ </reference>
+
+ <xinclude:include href="../shared/glossary.xml" />
+
+ <xinclude:include href="appendix-rest2ldap.xml" />
+ <xinclude:include href='appendix-file-layout.xml' />
+ <xinclude:include href='appendix-ports-used.xml' />
+ <xinclude:include href='appendix-standards.xml' />
+ <xinclude:include href='appendix-controls.xml' />
+ <xinclude:include href='appendix-extended-ops.xml' />
+ <xinclude:include href='appendix-l10n.xml' />
+ <xinclude:include href='appendix-interface-stability.xml' />
+<!-- For 2.6.x, we deliver only release notes, so leave out the log reference.
+ <xinclude:include href='../../../target/logref/log-message-reference.xml'>
+ <xinclude:fallback>
+ <appendix>
+ <title>Log Message Reference Missing</title>
+ <para>The log message reference is missing. It should be in
+ <filename>../../../target/logref/log-message-reference.xml</filename>.</para>
+ </appendix>
+ </xinclude:fallback>
+ </xinclude:include>
+-->
+
+ <index />
+</book>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapcompare.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapcompare.xml
new file mode 100644
index 0000000..5862476
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapcompare.xml
@@ -0,0 +1,346 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapcompare-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapcompare</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapcompare</refname>
+ <refpurpose>perform LDAP compare operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapcompare</command>
+ <arg choice="req">options</arg>
+ <group><arg>attribute</arg><arg>:</arg><arg>value</arg></group>
+ <arg choice="opt" rep="repeat">DN</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP compare operations in the
+ directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing one DN per line of entries to compare</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m, --useCompareResultCode</option></term>
+ <listitem>
+ <para>Use the LDAP compare result as an exit code for the LDAP compare operations.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --useSASLExternal</option></term>
+ <listitem>
+ <para>Use the SASL EXTERNAL authentication mechanism</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --script-friendly</option></term>
+ <listitem>
+ <para>Use script-friendly mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>5</term>
+ <listitem>
+ <para>The -m option was used, and at least one of the LDAP compare operations did not match.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>6</term>
+ <listitem>
+ <para>The -m option was used, and all the LDAP compare operations did match.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following examples demonstrate comparing Babs Jensen's UID.</para>
+ <para>The following example uses a matching UID value.</para>
+ <screen>$ ldapcompare -p 1389 uid:bjensen uid=bjensen,ou=people,dc=example,dc=com
+Comparing type uid with value bjensen in entry
+uid=bjensen,ou=people,dc=example,dc=com
+Compare operation returned true for entry
+uid=bjensen,ou=people,dc=example,dc=com</screen>
+ <para>The following example uses a UID value that does not match.</para>
+ <screen>$ ldapcompare -p 1389 uid:beavis uid=bjensen,ou=people,dc=example,dc=com
+Comparing type uid with value beavis in entry
+uid=bjensen,ou=people,dc=example,dc=com
+Compare operation returned false for entry
+uid=bjensen,ou=people,dc=example,dc=com</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapmodify.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapmodify.xml
new file mode 100644
index 0000000..0d70432
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapmodify.xml
@@ -0,0 +1,405 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapmodify-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapmodify</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapmodify</refname>
+ <refpurpose>perform LDAP modify, add, delete, mod DN operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapmodify</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP modify, add, delete, and
+ modify DN operations in the directory.</para>
+ <para>When not using a file to specify modifications, end your input with
+ EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --defaultAdd</option></term>
+ <listitem>
+ <para>Treat records with no changetype as add operations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing the changes to apply</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--postReadAttributes {attrList}</option></term>
+ <listitem>
+ <para>Use the LDAP ReadEntry post-read control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--preReadAttributes {attrList}</option></term>
+ <listitem>
+ <para>Use the LDAP ReadEntry pre-read control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --useSASLExternal</option></term>
+ <listitem>
+ <para>Use the SASL EXTERNAL authentication mechanism</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command to add an entry
+ to the directory.</para>
+ <screen>$ cat newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+facsimileTelephoneNumber: +1 408 555 1213
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+givenName: New
+cn: New User
+cn: Real Name
+telephoneNumber: +1 408 555 1212
+sn: Jensen
+roomNumber: 1234
+homeDirectory: /home/newuser
+uidNumber: 10389
+mail: newuser@example.com
+l: South Pole
+ou: Product Development
+ou: People
+gidNumber: 10636
+
+$ ldapmodify -p 1389 -a -f newuser.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
+ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+
+ <para>The following example demonstrates adding a Description attribute
+ to the new user's entry.</para>
+ <screen>$ cat newdesc.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+add: description
+description: A new user's entry
+
+$ ldapmodify -p 1389 -f newdesc.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing MODIFY request for uid=newuser,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+
+ <para>The following example demonstrates changing the Description attribute
+ for the new user's entry.</para>
+ <screen>$ cat moddesc.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+replace: description
+description: Another description
+
+$ ldapmodify -p 1389 -f moddesc.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing MODIFY request for uid=newuser,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+
+ <para>The following example demonstrates deleting the new user's entry.</para>
+ <screen>$ cat deluser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: delete
+
+$ ldapmodify -p 1389 -f deluser.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing DELETE request for uid=newuser,ou=People,dc=example,dc=com
+DELETE operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldappasswordmodify.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldappasswordmodify.xml
new file mode 100644
index 0000000..2adac5a
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldappasswordmodify.xml
@@ -0,0 +1,318 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldappasswordmodify-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldappasswordmodify</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldappasswordmodify</refname>
+ <refpurpose>perform LDAP password modifications</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldappasswordmodify</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP password modify operations in
+ the directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --authzID {authzID}</option></term>
+ <listitem>
+ <para>Authorization ID for the user entry whose password should be changed</para>
+ <para>The authorization ID is a string having either the prefix
+ <literal>dn:</literal> followed by the user's distinguished name, or
+ the prefix <literal>u:</literal> followed by a user identifier that
+ depends on the identity mapping used to match the user identifier to
+ an entry in the directory. Examples include
+ <literal>dn:uid=bjensen,ou=People,dc=example,dc=com</literal>, and, if
+ we assume that <literal>bjensen</literal> is mapped to Barbara Jensen's
+ entry, <literal>u:bjensen</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --provideDNForAuthzID</option></term>
+ <listitem>
+ <para>Use the bind DN as the authorization ID for the password modify
+ operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --currentPassword {currentPassword}</option></term>
+ <listitem>
+ <para>Current password for the target user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-C, --currentPasswordFile {file}</option></term>
+ <listitem>
+ <para>Path to a file containing the current password for the target user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --newPassword {newPassword}</option></term>
+ <listitem>
+ <para>New password to provide for the target user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --newPasswordFile {file}</option></term>
+ <listitem>
+ <para>Path to a file containing the new password to provide for the
+ target user</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display directory server version information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates a user changing the password
+ for her entry.</para>
+ <screen>$ cat /tmp/currpwd.txt /tmp/newpwd.txt
+bribery
+secret12
+$ ldappasswordmodify -p 1389 -C /tmp/currpwd.txt -N /tmp/newpwd.txt
+-A -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+The LDAP password modify operation was successful</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapsearch.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapsearch.xml
new file mode 100644
index 0000000..c1008a4
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldapsearch.xml
@@ -0,0 +1,534 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapsearch-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapsearch</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapsearch</refname>
+ <refpurpose>perform LDAP search operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapsearch</command>
+ <arg choice="req">options</arg>
+ <arg choice="opt">filter</arg>
+ <arg choice="opt" rep="repeat">attributes</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP search operations in the
+ directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --dereferencePolicy {dereferencePolicy}</option></term>
+ <listitem>
+ <para>Alias dereference policy ('never', 'always', 'search', or 'find')</para>
+ <para>Default value: never</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --typesOnly</option></term>
+ <listitem>
+ <para>Only retrieve attribute names but not their values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN format string</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-C, --persistentSearch ps[:changetype[:changesonly[:entrychgcontrols]]]</option></term>
+ <listitem>
+ <para>Use the persistent search control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--countEntries</option></term>
+ <listitem>
+ <para>Count the number of entries returned by the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --getEffectiveRightsAttribute {attribute}</option></term>
+ <listitem>
+ <para>Specifies geteffectiverights control specific attribute list</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing the changes to apply</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-g, --getEffectiveRightsAuthzid {authzID}</option></term>
+ <listitem>
+ <para>Use geteffectiverights control with the provided authzid</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-G, --virtualListView {before:after:index:count | before:after:value}</option></term>
+ <listitem>
+ <para>Use the virtual list view control to retrieve the specified results page</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --timeLimit {timeLimit}</option></term>
+ <listitem>
+ <para>Maximum length of time in seconds to allow for the search</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--matchedValuesFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP matched values control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --searchScope {searchScope}</option></term>
+ <listitem>
+ <para>Search scope ('base', 'one', 'sub', or 'subordinate')</para>
+ <para>Default value: sub</para>
+ <para><literal>subordinate</literal> is an LDAP extension that might
+ not work with all LDAP servers.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --sortOrder {sortOrder}</option></term>
+ <listitem>
+ <para>Sort the results using the provided sort order</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--simplePageSize {numEntries}</option></term>
+ <listitem>
+ <para>Use the simple paged results control with the given page size</para>
+ <para>Default value: 1000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--subEntries</option></term>
+ <listitem>
+ <para>Use subentries control to specify that subentries are visible and
+ normal entries are not</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z, --sizeLimit {sizeLimit}</option></term>
+ <listitem>
+ <para>Maximum number of entries to return from the search</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --useSASLExternal</option></term>
+ <listitem>
+ <para>Use the SASL EXTERNAL authentication mechanism</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --dontWrap</option></term>
+ <listitem><para>Do not wrap long lines</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Filter</title>
+ <para>The filter argument is a string representation of an LDAP search filter
+ as in <literal>(cn=Babs Jensen)</literal>, <literal
+ >(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))</literal>, or
+ <literal>(cn:caseExactMatch:=Fred Flintstone)</literal>.</para>
+ </refsect1>
+ <refsect1>
+ <title>Attribute</title>
+ <para>The optional attribute list specifies the attributes to return in the
+ entries found by the search. In addition to identifying attributes by name
+ such as <literal>cn sn mail</literal> and so forth, you can use the following
+ notations, too.</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>*</literal></term>
+ <listitem>
+ <para>Return all user attributes such as <literal>cn</literal>,
+ <literal>sn</literal>, and <literal>mail</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>+</literal></term>
+ <listitem>
+ <para>Return all operational attributes such as <literal>etag</literal>
+ and <literal>pwdPolicySubentry</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>@<replaceable>objectclass</replaceable></literal></term>
+ <listitem>
+ <para>Return all attributes of the specified object class, where
+ <replaceable>objectclass</replaceable> is one of the object classes
+ on the entries returned by the search.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example searches for entries with UID containing
+ <literal>jensen</literal>, returning only DNs and uid values.</para>
+ <screen>$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=*jensen*)" uid
+dn: uid=ajensen,ou=People,dc=example,dc=com
+uid: ajensen
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+uid: bjensen
+
+dn: uid=gjensen,ou=People,dc=example,dc=com
+uid: gjensen
+
+dn: uid=jjensen,ou=People,dc=example,dc=com
+uid: jjensen
+
+dn: uid=kjensen,ou=People,dc=example,dc=com
+uid: kjensen
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+uid: rjensen
+
+dn: uid=tjensen,ou=People,dc=example,dc=com
+uid: tjensen
+
+
+Result Code: 0 (Success)</screen>
+
+ <para>You can also use <literal>@<replaceable
+ >objectclass</replaceable></literal> notation in the attribute list to return
+ the attributes of a particular object class. The following example shows
+ how to return attributes of the <literal>inetOrgPerson</literal> object
+ class.</para>
+
+ <screen>$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" @inetorgperson
+dn: uid=bjensen,ou=People,dc=example,dc=com
+givenName: Barbara
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+uid: bjensen
+cn: Barbara Jensen
+cn: Babs Jensen
+telephoneNumber: +1 408 555 1862
+sn: Jensen
+roomNumber: 0209
+mail: bjensen@example.com
+l: Cupertino
+ou: Product Development
+ou: People
+facsimileTelephoneNumber: +1 408 555 1992</screen>
+
+ <para>You can use <literal>+</literal> in the attribute list to return
+ all operational attributes, as in the following example.</para>
+
+ <screen>$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" +
+dn: uid=bjensen,ou=People,dc=example,dc=com
+numSubordinates: 0
+structuralObjectClass: inetOrgPerson
+etag: 0000000073c29972
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: uid=bjensen,ou=people,dc=example,dc=com
+entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifmodify.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifmodify.xml
new file mode 100644
index 0000000..fd011ac
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifmodify.xml
@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldifmodify-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldifmodify</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldifmodify</refname>
+ <refpurpose>apply LDIF changes to LDIF</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldifmodify</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to apply a set of modify, add, and delete
+ operations against data in an LDIF file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-m, --changesLDIF {ldifFile}</option></term>
+ <listitem>
+ <para>LDIF file containing the changes to apply.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --sourceLDIF {ldifFile}</option></term>
+ <listitem>
+ <para>LDIF file containing the data to be updated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --targetLDIF {ldifFile}</option></term>
+ <listitem>
+ <para>File to which the updated data should be written.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command.</para>
+ <screen>$ cat /path/to/newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: changeme
+
+$ cat /path/to/newdiff.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+add: userPassword
+userPassword: secret12
+-
+delete: userPassword
+userPassword: changeme
+-
+add: description
+description: A new description.
+
+$ ldifmodify -s /path/to/newuser.ldif -m /path/to/newdiff.ldif -t neweruser.ldif
+$ cat neweruser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: top
+uid: newuser
+description: A new description.
+cn: New User
+sn: User
+userPassword: secret12
+mail: newuser@example.com
+ou: People
+
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifsearch.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifsearch.xml
new file mode 100644
index 0000000..22f1375
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/man-ldifsearch.xml
@@ -0,0 +1,245 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldifsearch-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldifsearch</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldifsearch</refname>
+ <refpurpose>search LDIF with LDAP filters</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldifsearch</command>
+ <arg choice="req">options</arg>
+ <arg choice="opt">filter</arg>
+ <arg choice="opt" rep="repeat">attribute</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform search operations against data in
+ an LDIF file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>The base DN for the search. Multiple base DNs may be specified by
+ providing the option multiple times. If no base DN is provided, then the
+ root DSE will be used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filterFile {filterFile}</option></term>
+ <listitem>
+ <para>The path to the file containing the search filter(s) to use. If
+ this is not provided, then the filter must be provided on the command line
+ after all configuration options.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --ldifFile {ldifFile}</option></term>
+ <listitem>
+ <para>LDIF file containing the data to search. Multiple files may be
+ specified by providing the option multiple times. If no files are provided,
+ the data will be read from standard input.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --outputFile {outputFile}</option></term>
+ <listitem>
+ <para>The path to the output file to which the matching entries should be
+ written. If this is not provided, then the data will be written to
+ standard output.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-O, --overwriteExisting</option></term>
+ <listitem>
+ <para>Any existing output file should be overwritten rather than appending
+ to it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --searchScope {scope}</option></term>
+ <listitem>
+ <para>The scope for the search. It must be one of 'base', 'one', 'sub',
+ or 'subordinate'. If it is not provided, then 'sub' will be used.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --timeLimit {timeLimit}</option></term>
+ <listitem>
+ <para>Maximum length of time (in seconds) to spend processing.</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --dontWrap</option></term>
+ <listitem>
+ <para>Long lines should not be wrapped.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z, --sizeLimit {sizeLimit}</option></term>
+ <listitem>
+ <para>Maximum number of matching entries to return.</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Filter</title>
+ <para>The filter argument is a string representation of an LDAP search filter
+ as in <literal>(cn=Babs Jensen)</literal>, <literal
+ >(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))</literal>, or
+ <literal>(cn:caseExactMatch:=Fred Flintstone)</literal>.</para>
+ </refsect1>
+ <refsect1>
+ <title>Attribute</title>
+ <para>The optional attribute list specifies the attributes to return in the
+ entries found by the search. In addition to identifying attributes by name
+ such as <literal>cn sn mail</literal> and so forth, you can use the following
+ notations, too.</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>*</literal></term>
+ <listitem>
+ <para>Return all user attributes such as <literal>cn</literal>,
+ <literal>sn</literal>, and <literal>mail</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>+</literal></term>
+ <listitem>
+ <para>Return all operational attributes such as <literal>etag</literal>
+ and <literal>pwdPolicySubentry</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>@<replaceable>objectclass</replaceable></literal></term>
+ <listitem>
+ <para>Return all attributes of the specified object class, where
+ <replaceable>objectclass</replaceable> is one of the object classes
+ on the entries returned by the search.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command.</para>
+ <screen>$ ldifsearch -l /path/to/Example.ldif -b dc=example,dc=com uid=bjensen
+dn: uid=bjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+uid: bjensen
+userpassword: hifalutin
+facsimiletelephonenumber: +1 408 555 1992
+givenname: Barbara
+cn: Barbara Jensen
+cn: Babs Jensen
+telephonenumber: +1 408 555 1862
+sn: Jensen
+roomnumber: 0209
+homeDirectory: /home/bjensen
+mail: bjensen@example.com
+l: Cupertino
+ou: Product Development
+ou: People
+uidNumber: 1076
+gidNumber: 1000
+</screen>
+
+ <para>You can also use <literal>@<replaceable
+ >objectclass</replaceable></literal> notation in the attribute list to return
+ the attributes of a particular object class. The following example shows
+ how to return attributes of the <literal>posixAccount</literal> object
+ class.</para>
+
+ <screen>$ ldifsearch --ldifFile /path/to/Example.ldif
+ --baseDN dc=example,dc=com "(uid=bjensen)" @posixaccount
+dn: uid=bjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+uid: bjensen
+userpassword: hifalutin
+cn: Barbara Jensen
+cn: Babs Jensen
+homeDirectory: /home/bjensen
+uidNumber: 1076
+gidNumber: 1000</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/admin-guide/preface.xml b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/preface.xml
new file mode 100644
index 0000000..8145ebb
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/admin-guide/preface.xml
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<preface xml:id='preface'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Preface</title>
+
+ <para>This guide shows you how to configure, maintain, and troubleshoot
+ OpenDJ directory services. This guide also describes file layouts, ports
+ used, and standards, controls, extended operations, and languages supported
+ for OpenDJ installations.</para>
+
+ <section>
+ <title>Who Should Read this Guide</title>
+
+ <para>This guide is written for directory designers and administrators who
+ build, deploy, and maintain OpenDJ directory services for your
+ organizations.</para>
+
+ <para>This guide starts by introducing the OpenDJ administrative interfaces
+ and tools, and by showing how to manage OpenDJ server processes. It also
+ demonstrates how to import and export directory data. This guide continues
+ by showing how to configure and monitor the principle features of individual
+ OpenDJ servers, and how to configure and monitor replicated server
+ topologies for distributed high availability. It then demonstrates how to
+ tune, troubleshoot, and move servers. This guide concludes with appendices
+ of useful reference information for directory designers and
+ administrators.</para>
+
+ <para>You do not need to be an LDAP wizard to learn something from this
+ guide, though a background in directory services and maintaining server
+ software can help. You do need some background in managing servers and
+ services on your operating system of choice. You can nevertheless get
+ started with this guide, and then learn more as you go along.</para>
+ </section>
+
+ <xinclude:include href="../shared/sec-formatting-conventions.xml" />
+ <xinclude:include href="../shared/sec-accessing-doc-online.xml" />
+ <xinclude:include href="../shared/sec-joining-the-community.xml" />
+</preface>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-authenticating.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-authenticating.xml
new file mode 100644
index 0000000..3425ee8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-authenticating.xml
@@ -0,0 +1,278 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-authenticating'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Authenticating To the Directory</title>
+
+ <para>When your client application connects to the directory, the first
+ operation to perform is a bind operation. The bind operation authenticates
+ the client to the directory.</para>
+
+ <section xml:id="simple-auth">
+ <title>Simple Authentication</title>
+ <indexterm>
+ <primary>Authentications</primary>
+ <secondary>Simple</secondary>
+ </indexterm>
+
+ <para>You perform simple authentication by binding with the distinguished
+ name of a user's directory entry and the user's password. For this reason
+ simple authentication over unsecure network connections should be done only
+ in the lab. If your real end users are providing their passwords, your
+ application must use simple authentication only if the network is
+ secure.</para>
+
+ <para>To bind using Barbara Jensen's identity and simple authentication,
+ for example, your application would provide the DN
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> with the
+ password <literal>hifalutin</literal>.</para>
+
+ <para>The directory stores the password value used for simple authentication
+ in binary form on the <literal>userPassword</literal> attribute of the entry.
+ In other words, for the purposes of your application the password is not a
+ string, but instead an array of bytes. Typically the directory is further
+ configured to store only hashed values of user passwords, rather than plain
+ text versions. Thus even if someone managed to read the stored password
+ values, they would still have to crack the hash in order to learn the
+ actual passwords. When your application performing simple authentication
+ sends the password value, the directory server therefore hashes the password
+ value, and then compares the hashed result with the value of the
+ <literal>userPassword</literal> on the user entry. If the values match,
+ then the directory authenticates the user. Once the user has authenticated,
+ the directory determines authorization for operations on the connection
+ based on the users identity.</para>
+
+ <programlisting language="java">
+/**
+ * Authenticate over LDAP.
+ */
+private static void connect()
+{
+ final LDAPConnectionFactory factory = new LDAPConnectionFactory(
+ host, port);
+ Connection connection = null;
+
+ try
+ {
+ connection = factory.getConnection();
+ connection.bind(bindDN, bindPassword.toCharArray());
+ System.out.println("Authenticated as " + bindDN + ".");
+ }
+ catch (final ErrorResultException e)
+ {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+ }
+ finally
+ {
+ if (connection != null) connection.close();
+ }
+}</programlisting>
+
+ <para>If the password values do not match, a directory might nevertheless
+ authenticate the client application. The LDAP specifications say that in this
+ case, however, the directory authenticates the user as anonymous, therefore
+ no doubt with fewer rights than the normal user, and surely fewer rights
+ than an administrator.</para>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SimpleAuth.html"
+ xlink:show="new">SimpleAuth.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+
+ <section xml:id="simple-auth-with-starttls-or-ssl">
+ <title>Start TLS & SSL Authentication</title>
+ <indexterm>
+ <primary>Authentications</primary>
+ <secondary>StartTLS, SSL</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>StartTLS</secondary>
+ </indexterm>
+
+ <para>Simple authentication involves sending a user name and password to
+ the directory server. To avoid sending the user name and password in
+ the clear, you can use SSL or Start TLS.</para>
+
+ <para>For both SSL and Start TLS, you pass LDAP options to the connection
+ factory in order to set an SSL context, and set whether to use Start TLS.
+ The SSL context lets you set a trust manager to check server certificates,
+ and also set a key manager to provide keys when the server needs to check
+ your client certificates. In the simplest, not-so-secure case, you can
+ set up a trust manager that trusts all certificates.</para>
+
+ <para>The following example is an excerpt from the OpenDJ LDAP SDK example,
+ <filename>org.forgerock.opendj.examples.SimpleAuth.java</filename>.</para>
+
+ <programlisting language="java">
+private static LDAPOptions getTrustAllOptions()
+ throws GeneralSecurityException
+{
+ LDAPOptions lo = new LDAPOptions();
+ SSLContext sslContext = new SSLContextBuilder()
+ .setTrustManager(TrustManagers.trustAll()).getSSLContext();
+ lo.setSSLContext(sslContext);
+ lo.setUseStartTLS(useStartTLS);
+ return lo;
+}</programlisting>
+
+ <para>A more secure and extensive SSL context would include a trust manager
+ using a trust store and trust manager methods to check server certificates.
+ If you also want to be able to authenticate to the server using your client
+ certificate, you would need a key manager.</para>
+
+ <para>The authentication over SSL or using Start TLS in the trust-all case is
+ much like simple authentication over LDAP without connection-level security.
+ The primary differences are that you pass the <literal>LDAPOptions</literal>
+ to the LDAP connection factory, and that you handle the potential security
+ exception involved in setting up the SSL context.</para>
+
+ <programlisting language="java">
+/**
+ * Perform authentication over a secure connection, trusting all server
+ * certificates.
+ */
+private static void trustAllConnect()
+{
+ Connection connection = null;
+
+ try
+ {
+ final LDAPConnectionFactory factory =
+ new LDAPConnectionFactory(host, port, getTrustAllOptions());
+ connection = factory.getConnection();
+ connection.bind(bindDN, bindPassword.toCharArray());
+ System.out.println("Authenticated as " + bindDN + ".");
+ }
+ catch (final ErrorResultException e)
+ {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+ }
+ catch (final GeneralSecurityException e)
+ {
+ System.err.println(e.getMessage());
+ System.exit(ResultCode.CLIENT_SIDE_CONNECT_ERROR.intValue());
+ }
+ finally
+ {
+ if (connection != null)
+ connection.close();
+ }
+}</programlisting>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SimpleAuth.html"
+ xlink:show="new">SimpleAuth.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+
+ <section xml:id="sasl-auth">
+ <title>SASL Authentication</title>
+ <indexterm>
+ <primary>Authentications</primary>
+ <secondary>SASL</secondary>
+ </indexterm>
+
+ <para>Simple Authentication and Security Layer (SASL) provides a way to
+ use other mechanisms for authentication such as Kerberos or Digest
+ authentication, or even to define your own authentication mechanism. The
+ directory server likely advertises supported SASL mechanisms in the root
+ DSE. The follow example shows how to search OpenDJ for supported SASL
+ mechanisms.</para>
+
+ <screen>$ ldapsearch
+ --port 1389
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --baseDN ""
+ --searchScope base
+ "(objectclass=*)" supportedSASLMechanisms
+dn:
+supportedSASLMechanisms: PLAIN
+supportedSASLMechanisms: EXTERNAL
+supportedSASLMechanisms: DIGEST-MD5
+supportedSASLMechanisms: CRAM-MD5</screen>
+
+ <para>Notice that neither the Kerberos (GSSAPI SASL) nor the Anonymous
+ mechanism is enabled by default, though OpenDJ implements both.</para>
+
+ <para>In order to use a SASL mechanism to bind, your program must set up
+ a <literal>SASLBindRequest</literal> and pass that to the
+ <literal>bind()</literal> method of the <literal>Connection</literal>.</para>
+
+ <para>This section shows an example using the SASL PLAIN mechanism, which
+ takes either a DN or a user ID to authenticate, with an optional DN or user
+ ID as the authorization ID that identifies the user who performs operations.
+ The SASL PLAIN mechanism itself does not secure the connection, so the
+ example uses StartTLS. The example is provided with the OpenDJ LDAP SDK
+ examples in <filename>org.forgerock.opendj.examples.SASLAuth.java</filename>.
+ The following excerpt shows the core of the bind process.</para>
+
+ <programlisting language="java">
+try
+{
+ final LDAPConnectionFactory factory =
+ new LDAPConnectionFactory(host, port, getTrustAllOptions());
+ connection = factory.getConnection();
+ PlainSASLBindRequest request =
+ Requests.newPlainSASLBindRequest(authcid, passwd.toCharArray())
+ .setAuthorizationID(authzid);
+ connection.bind(request);
+ System.out.println("Authenticated as " + authcid + ".");
+}</programlisting>
+
+ <para>The implementation for <literal>getTrustAllOptions()</literal>, the
+ same as in the example above, sets up Start TLS. When you run this example
+ with both authorization and authentication IDs, <literal>authzid</literal>
+ and <literal>authcid</literal>, set to <literal>u:bjensen</literal> and
+ password <literal>hifalutin</literal>, the bind is successful, and the
+ program reaches the final line of the <literal>try</literal> block.</para>
+
+ <screen>Authenticated as u:bjensen.</screen>
+
+ <para>Behind the scenes, OpenDJ has the SASL PLAIN mechanism configured by
+ default to use the Exact Match Identity Mapper to look up user IDs as
+ <literal>uid</literal> values. If you use another directory server, you might
+ have to configure how it maps user IDs to user entries.</para>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SASLAuth.html"
+ xlink:show="new">SASLAuth.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-best-practices.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-best-practices.xml
new file mode 100644
index 0000000..2031be8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-best-practices.xml
@@ -0,0 +1,397 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-best-practices'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Best Practices For LDAP Application Developers</title>
+
+ <para>Follow the advice in this chapter to write effective, maintainable,
+ high performance directory client applications.</para>
+
+ <section xml:id="authenticate-correctly">
+ <title>Authenticate Correctly</title>
+ <indexterm>
+ <primary>Authentications</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
+
+ <para>Unless your application performs only read operations, you should
+ authenticate to the directory server. Some directory administrators require
+ authentication even to read directory data.</para>
+
+ <para>Once you authenticate (bind), directory servers like OpenDJ make
+ authorization decisions based on your identity. With servers like OpenDJ
+ that support proxied authorization, once authenticated your application can
+ also request an operation on behalf of another identity, for example the
+ identity of the end user.</para>
+
+ <para>Your application therefore should have an account used to authenticate
+ such as <literal>cn=My Killer App,ou=Apps,dc=example,dc=com</literal>. The
+ directory administrator can then authorize appropriate access for your
+ application, and also monitor your application's requests to help you
+ troubleshoot problems if they arise.</para>
+
+ <para>Your application can use simple, password-based authentication. When
+ you opt for password-based authentication, also use Start TLS for example to
+ avoid sending the password as clear text over the network. If you prefer to
+ manage certificates rather than passwords, directory servers like OpenDJ can
+ do client authentication as well.</para>
+ </section>
+
+ <section xml:id="reuse-connections">
+ <title>Reuse Connections</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Pooling</secondary>
+ </indexterm>
+
+ <para>LDAP is a stateful protocol. You authenticate (bind), you do stuff,
+ you unbind. The server maintains a context that lets it make authorization
+ decisions concerning your requests. You should therefore reuse
+ connections when possible.</para>
+
+ <para>You can make multiple requests without having to set up a new
+ connection and authenticate for every request. You can issue a request and
+ get results asynchronously, while you issue another request. You can even
+ share connections in a pool, avoiding the overhead of setting up and tearing
+ down connections if you use them often.</para>
+ </section>
+
+ <section xml:id="health-check-connections">
+ <title>Health Check Connections</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Health check</secondary>
+ </indexterm>
+
+ <para>In a network built for HTTP applications, your long-lived LDAP
+ connections can get cut by network equipment configured to treat idle and
+ even just old connections as stale resources to reclaim.</para>
+
+ <para>When you maintain a particularly long-lived connection such as a
+ connection for a persistent search, periodically perform a health check to
+ make sure nothing on the network quietly decided to drop your connection
+ without notification. A health check might involve reading an attribute
+ on a well-known entry in the directory.</para>
+
+ <para>OpenDJ LDAP SDK offers
+ <literal>Connections.newHeartBeatConnectionFactory()</literal> methods to
+ ensure your <literal>ConnectionFactory</literal> serves connections that
+ are periodically checked to detect whether they are still alive.</para>
+ </section>
+
+ <section xml:id="request-what-you-need-all-at-once">
+ <title>Request Exactly What You Need All At Once</title>
+
+ <para>By the time your application makes it to production, you should know
+ what attributes you want, so request them explicitly and request all
+ the attributes you need in the same search. For example, if all you need
+ is <literal>mail</literal> and <literal>cn</literal>, then specify both
+ attributes in your <literal>SearchRequest</literal>.</para>
+ </section>
+
+ <section xml:id="use-specific-filters">
+ <title>Use Specific LDAP Filters</title>
+ <indexterm>
+ <primary>Filters</primary>
+ </indexterm>
+
+ <para>The difference between a general filter
+ <literal>(mail=*@example.com)</literal> and a good, specific filter like
+ <literal>(mail=user@example.com)</literal> can be huge numbers of entries
+ and enormous amounts of processing time, both for the directory server
+ that has to return search results, and also for your application that has
+ to sort through the results. Many use cases can be handled with short,
+ specific filters. As a rule, prefer equality filters over substring
+ filters.</para>
+
+ <para>Some directory servers like OpenDJ reject unindexed searches by
+ default, because unindexed searches are generally far more resource intensive.
+ If your application needs to use a filter that results in an unindexed search,
+ then work with your directory administrator to find a solution, such as having
+ the directory maintain the indexes required by your application.</para>
+
+ <para>Furthermore, always use <literal>&</literal> with
+ <literal>!</literal> to restrict the potential result set before returning
+ all entries that do not match part of the filter. For example, <literal
+ >(&(location=Oslo)(!(mail=birthday.girl@example.com)))</literal>.</para>
+ </section>
+
+ <section xml:id="make-modifications-specific">
+ <title>Make Modifications Specific</title>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
+
+ <para>When you modify attributes with multiple values, for example when you
+ modify a list of group members, replace or delete specific values
+ individually, rather than replacing the entire list of values. Making
+ modifications specific helps directory servers replicate your changes more
+ effectively.</para>
+ </section>
+
+ <section xml:id="trust-result-codes">
+ <title>Trust Result Codes</title>
+ <indexterm>
+ <primary>Errors</primary>
+ <secondary>Result codes</secondary>
+ </indexterm>
+
+ <para>Trust the LDAP result code that your application gets from the
+ directory server. For example, if you request a modify application and you
+ get <literal>ResultCode.SUCCESS</literal>, then consider the operation a
+ success rather than issuing a search immediately to get the modified
+ entry.</para>
+
+ <para>The LDAP replication model is loosely convergent. In other words,
+ the directory server can, and probably does, send you
+ <literal>ResultCode.SUCCESS</literal> before replicating your change to
+ every directory server instance across the network. If you issue a read
+ immediately after a write, and a load balancer sends your request to another
+ directory server instance, you could get a result that differs from what
+ you expect.</para>
+
+ <indexterm>
+ <primary>Assertions</primary>
+ </indexterm>
+ <para>The loosely convergent model also means that the entry could have
+ changed since you read it. If needed, you can use <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc4528">LDAP assertions</link> to set
+ conditions for your LDAP operations.</para>
+ </section>
+
+ <section xml:id="ismemberof-for-membership">
+ <title>Check Group Membership on the Account, Not the Group</title>
+ <indexterm>
+ <primary>Groups</primary>
+ </indexterm>
+
+ <para>If you need to determine which groups an account belongs to, request
+ <literal>isMemberOf</literal> for example with OpenDJ when you read the
+ account entry. Other directory servers use other names for this attribute
+ that identifies the groups to which an account belongs.</para>
+ </section>
+
+ <section xml:id="ask-directory-what-it-supports">
+ <title>Ask the Directory Server What It Supports</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
+
+ <para>Directory servers expose their capabilities, suffixes they support,
+ and so forth as attribute values on the root DSE. See the section on
+ <link xlink:href="dev-guide#read-root-dse"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Reading Root
+ DSEs</citetitle></link>.</para>
+
+ <para>This allows your application to discover a variety of information at
+ run time, rather than storing configuration separately. Thus putting effort
+ into querying the directory about its configuration and the features it
+ supports can make your application easier to deploy and to maintain.</para>
+
+ <para>For example, rather than hard-coding
+ <literal>dc=example,dc=com</literal> as a suffix DN in your configuration,
+ you can search the root DSE on OpenDJ for <literal>namingContexts</literal>,
+ and then search under the naming context DNs to locate the entries you are
+ looking for in order to initialize your configuration.</para>
+
+ <para>Directory servers also expose their schema over LDAP. The root DSE
+ attribute <literal>subschemaSubentry</literal> shows the DN of the entry
+ holding LDAP schema definitions. See the section, <link
+ xlink:href="dev-guide#get-schema-information"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Getting Schema
+ Information</citetitle></link>. Note that LDAP object class and attribute
+ type names are case-insensitive, so <literal>isMemberOf</literal> and
+ <literal>ismemberof</literal> refer to the same attribute for example.</para>
+ </section>
+
+ <section xml:id="storing-large-attributes">
+ <title>Store Large Attribute Values By Reference</title>
+ <indexterm>
+ <primary>Attributes</primary>
+ </indexterm>
+
+ <para>When you use large attribute values such as photos or audio messages,
+ consider storing the objects themselves elsewhere and keeping only a reference
+ to external content on directory entries. In order to serve results quickly
+ with high availability, directory servers both cache content and also
+ replicate it everywhere.</para>
+
+ <para>Textual entries with a bunch of attributes and perhaps a certificate
+ are often no larger than a few KB. Your directory administrator might
+ therefore be disappointed to learn that your popular application stores
+ users' photo and .mp3 collections as attributes of their accounts.</para>
+ </section>
+
+ <section xml:id="careful-with-persistent-search-and-server-side-sorting">
+ <title>Take Care With Persistent Search & Server-Side Sorting</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Sorting</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
+
+ <para>A persistent search lets your application receive updates from the
+ server as they happen by keeping the connection open and forcing the server
+ to check whether to return additional results any time it performs a
+ modification in the scope of your search. Directory administrators therefore
+ might hesitate to grant persistent search access to your application.
+ Directory servers like OpenDJ can let you discover updates with less
+ overhead by searching the change log periodically. If you do have to use
+ a persistent search instead, try to narrow the scope of your search.</para>
+
+ <para>Directory servers also support a resource-intensive operation called
+ server-side sorting. When your application requests a server-side sort, the
+ directory server retrieves all the entries matching your search, and then
+ returns the whole set of entries in sorted order. For result sets of any size
+ server-side sorting therefore ties up server resources that could be used
+ elsewhere. Alternatives include both sorting the results after your
+ application receives them, and also working with the directory administrator
+ to have appropriate browsing (virtual list view) indexes maintained on the
+ directory server for applications that must regularly page through long
+ lists of search results.</para>
+ </section>
+
+ <section xml:id="reuse-schemas">
+ <title>Reuse Schemas Where Possible</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Schema</secondary>
+ </indexterm>
+
+ <para>Directory servers like OpenDJ come with schema definitions for a wide
+ range of standard object classes and attribute types. This is because
+ directories are designed to be shared by many applications. Directories
+ use unique, typically <link xlink:href="http://www.iana.org/"
+ xlink:show="new">IANA</link>-registered object identifiers (OID) to avoid
+ object class and attribute type name clashes. The overall goal is
+ Internet-wide interoperability.</para>
+
+ <para>You therefore should reuse schema definitions that already exist
+ whenever you reasonably can. Reuse them as is. Do not try to redefine
+ existing schema definitions.</para>
+
+ <para>If you must add schema definitions for your application, extend
+ existing object classes with AUXILIARY classes of your own. Take care to
+ name your definitions such that they do not clash with other names.</para>
+
+ <para>When you have defined schema required for your application, work with
+ the directory administrator to have your definitions added to the directory
+ service. Directory servers like OpenDJ let directory administrators update
+ schema definitions over LDAP, so there is not generally a need to interrupt
+ the service to add your application. Directory administrators can however
+ have other reasons why they hesitate to add your schema definitions.
+ Coming to the discussion prepared with good schema definitions, explanations
+ of why they should be added, and evident regard for interoperability makes
+ it easier for the directory administrator to grant your request.</para>
+ </section>
+
+ <section xml:id="handle-referrals">
+ <title>Handle Referrals</title>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+
+ <para>When a directory server returns a search result, the result is not
+ necessarily an entry. If the result is a referral, then your application
+ should follow up with an additional search based on the URIs provided in
+ the result.</para>
+ </section>
+
+ <section xml:id="check-result-codes">
+ <title>Troubleshooting: Check Result Codes</title>
+ <indexterm>
+ <primary>Errors</primary>
+ <secondary>Result codes</secondary>
+ </indexterm>
+
+ <para>LDAP result codes are standard and clearly defined. When you receive
+ a <literal>Result</literal>, check the <literal>ResultCode</literal> value to
+ determine what action your application should take. When the result is not
+ what you expect, you can also read or at least log the message string from
+ <literal>ResultCode.getDiagnosticMessage()</literal>.</para>
+ </section>
+
+ <section xml:id="check-log-files">
+ <title>Troubleshooting: Check Server Log Files</title>
+
+ <para>If you can read the directory server access log, then you can check
+ what the server did with your application's request. For example, the
+ following OpenDJ access log excerpt shows a successful connection from
+ <literal>cn=My Killer App,ou=Apps,dc=example,dc=com</literal> performing
+ a simple bind after Start TLS, and then a simple search before unbind.
+ The lines are wrapped for readability, whereas in the log each record starts
+ with the time stamp.</para>
+
+ <programlisting language="none">[20/Apr/2012:13:31:05 +0200] CONNECT conn=5
+ from=127.0.0.1:51561 to=127.0.0.1:1389 protocol=LDAP
+[20/Apr/2012:13:31:05 +0200] EXTENDED REQ conn=5 op=0 msgID=1 name="StartTLS"
+ oid="1.3.6.1.4.1.1466.20037"
+[20/Apr/2012:13:31:05 +0200] EXTENDED RES conn=5 op=0 msgID=1 name="StartTLS"
+ oid="1.3.6.1.4.1.1466.20037" result=0 etime=0
+[20/Apr/2012:13:31:07 +0200] BIND REQ conn=5 op=1 msgID=2 version=3 type=SIMPLE
+ dn="cn=My Killer App,ou=Apps,dc=example,dc=com"
+[20/Apr/2012:13:31:07 +0200] BIND RES conn=5 op=1 msgID=2 result=0
+ authDN="cn=My Killer App,ou=Apps,dc=example,dc=com" etime=1
+[20/Apr/2012:13:31:07 +0200] SEARCH REQ conn=5 op=2 msgID=3
+ base="dc=example,dc=com" scope=wholeSubtree
+ filter="(uid=kvaughan)" attrs="isMemberOf"
+[20/Apr/2012:13:31:07 +0200] SEARCH RES conn=5 op=2 msgID=3
+ result=0 nentries=1 etime=6
+[20/Apr/2012:13:31:07 +0200] UNBIND REQ conn=5 op=3 msgID=4
+[20/Apr/2012:13:31:07 +0200] DISCONNECT conn=5 reason="Client Unbind"</programlisting>
+
+ <para>Notice that each operation type is shown in upper case, and that the
+ server tracks both the connection (<literal>conn=5</literal>), operation
+ (<literal>op=[0-3]</literal>), and message ID (<literal>msgID=[1-4]</literal>)
+ numbers to make it easy to filter records. The <literal>etime</literal> refers
+ to how long the server worked on the request in milliseconds. Result code
+ 0 corresponds to <literal>ResultCode.SUCCESS</literal>, as described in
+ <link xlink:href="http://tools.ietf.org/html/rfc4511#section-4.1.9"
+ xlink:show="new">RFC 4511</link>.</para>
+ </section>
+
+ <section xml:id="inspect-network-traffic">
+ <title>Troubleshooting: Inspect Network Traffic</title>
+
+ <para>If result codes and server logs are not enough, many network tools
+ can interpret LDAP packets. Get the necessary certificates to decrypt
+ encrypted packet content.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-controls.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-controls.xml
new file mode 100644
index 0000000..71682cb
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-controls.xml
@@ -0,0 +1,1438 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-controls'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Working With Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Controls</secondary>
+ </indexterm>
+
+ <para>This chapter demonstrates how to use LDAP controls.</para>
+
+ <para>For complete examples corresponding to the excerpts shown below, see
+ <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Controls.html"
+ xlink:show="new">Controls.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+
+ <section xml:id="about-ldap-controls">
+ <title>About LDAP Controls</title>
+ <para>Controls provide a mechanism whereby the semantics and arguments of
+ existing LDAP operations may be extended. One or more controls may be
+ attached to a single LDAP message. A control only affects the semantics of
+ the message it is attached to. Controls sent by clients are termed
+ <emphasis>request controls</emphasis>, and those sent by servers are termed
+ <emphasis>response controls</emphasis>.</para>
+ </section>
+
+ <section xml:id="get-supported-controls">
+ <title>Determining Supported Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Supported</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
+
+ <para>For OpenDJ, the controls supported are listed in the
+ <citetitle>Administration Guide</citetitle> appendix, <link
+ xlink:href="admin-guide#appendix-controls"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>LDAP
+ Controls</citetitle></link>. You can access the list of OIDs for
+ supported LDAP controls by reading the <literal>supportedControl</literal>
+ attribute of the root DSE.</para>
+
+ <screen>$ ldapsearch
+ --baseDN ""
+ --searchScope base
+ --port 1389
+ "(objectclass=*)" supportedControl
+dn:
+supportedControl: 1.2.826.0.1.3344810.2.3
+supportedControl: 1.2.840.113556.1.4.1413
+supportedControl: 1.2.840.113556.1.4.319
+supportedControl: 1.2.840.113556.1.4.473
+supportedControl: 1.2.840.113556.1.4.805
+supportedControl: 1.3.6.1.1.12
+supportedControl: 1.3.6.1.1.13.1
+supportedControl: 1.3.6.1.1.13.2
+supportedControl: 1.3.6.1.4.1.26027.1.5.2
+supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1
+supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2
+supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8
+supportedControl: 1.3.6.1.4.1.4203.1.10.1
+supportedControl: 1.3.6.1.4.1.4203.1.10.2
+supportedControl: 1.3.6.1.4.1.7628.5.101.1
+supportedControl: 2.16.840.1.113730.3.4.12
+supportedControl: 2.16.840.1.113730.3.4.16
+supportedControl: 2.16.840.1.113730.3.4.17
+supportedControl: 2.16.840.1.113730.3.4.18
+supportedControl: 2.16.840.1.113730.3.4.19
+supportedControl: 2.16.840.1.113730.3.4.2
+supportedControl: 2.16.840.1.113730.3.4.3
+supportedControl: 2.16.840.1.113730.3.4.4
+supportedControl: 2.16.840.1.113730.3.4.5
+supportedControl: 2.16.840.1.113730.3.4.9</screen>
+
+ <para>The following excerpt shows couple of methods to check whether the
+ directory server supports a control.</para>
+
+ <programlisting language="java">
+/**
+ * Controls supported by the LDAP server.
+ */
+private static Collection<String> controls;
+
+/**
+ * Populate the list of supported LDAP control OIDs.
+ *
+ * @param connection
+ * Active connection to the LDAP server.
+ * @throws ErrorResultException
+ * Failed to get list of controls.
+ */
+static void checkSupportedControls(Connection connection)
+ throws ErrorResultException {
+ controls = RootDSE.readRootDSE(connection).getSupportedControls();
+}
+
+/**
+ * Check whether a control is supported. Call {@code checkSupportedControls}
+ * first.
+ *
+ * @param control
+ * Check support for this control, provided by OID.
+ * @return True if the control is supported.
+ */
+static boolean isSupported(final String control) {
+ if (controls != null && !controls.isEmpty()) {
+ return controls.contains(control);
+ }
+ return false;
+}
+</programlisting>
+ </section>
+
+ <section xml:id="use-assertion-request-control">
+ <title>Assertion Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Assertion</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Assertions</primary>
+ </indexterm>
+
+ <para>The <link xlink:href="http://tools.ietf.org/html/rfc4528"
+ xlink:show="new" >LDAP assertion control</link> lets you specify a condition
+ that must be true in order for the operation you request to be processed
+ normally. The following excerpt shows, for example, how you might check
+ that no description exists on the entry before adding your description.</para>
+
+ <programlisting language="java">
+if (isSupported(AssertionRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+
+ final ModifyRequest request =
+ Requests.newModifyRequest(dn)
+ .addControl(AssertionRequestControl.newControl(
+ true, Filter.valueOf("!(description=*)")))
+ .addModification(ModificationType.ADD, "description",
+ "Created using LDAP assertion control");
+
+ connection.modify(request);
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ writer.writeEntry(connection.readEntry(dn, "description"));
+ writer.close();
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the LDAP assertion control:</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description: Created using LDAP assertion control</programlisting>
+ </section>
+
+ <section xml:id="use-authorization-identity-control">
+ <title>Authorization Identity Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Authorization ID</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
+
+ <para>The <link xlink:href="http://tools.ietf.org/html/rfc3829"
+ xlink:show="new">LDAP Authorization Identity Controls</link> let you get the
+ authorization identity established when you bind to the directory server.
+ The following excerpt shows simple use of the controls.</para>
+
+ <programlisting language="java">
+if (isSupported(AuthorizationIdentityRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+ final char[] pwd = "hifalutin".toCharArray();
+
+ System.out.println("Binding as " + dn);
+ final BindRequest request =
+ Requests.newSimpleBindRequest(dn, pwd)
+ .addControl(AuthorizationIdentityRequestControl.newControl(true));
+
+ final BindResult result = connection.bind(request);
+ try {
+ final AuthorizationIdentityResponseControl control =
+ result.getControl(AuthorizationIdentityResponseControl.DECODER,
+ new DecodeOptions());
+ System.out.println("Authorization ID returned: "
+ + control.getAuthorizationID());
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the LDAP Authorization Identity
+ Controls:</para>
+
+ <programlisting>Binding as uid=bjensen,ou=People,dc=example,dc=com
+Authorization ID returned: dn:uid=bjensen,ou=People,dc=example,dc=com</programlisting>
+ </section>
+
+ <section xml:id="use-entry-change-notification-control">
+ <title>Entry Change Notification Response Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Entry change notification</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Entry change notification</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Change notification</primary>
+ </indexterm>
+
+ <para>When performing a persistent search, your application can retrieve
+ information using this response control about why the directory server
+ returned the entry. See the Internet-Draft on <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-psearch">persistent
+ searches</link> for background information.</para>
+
+ <programlisting language="java">
+if (isSupported(PersistentSearchRequestControl.OID)) {
+ final SearchRequest request =
+ Requests.newSearchRequest(
+ "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
+ "(objectclass=inetOrgPerson)", "cn")
+ .addControl(PersistentSearchRequestControl.newControl(
+ true, true, true, // critical,changesOnly,returnECs
+ PersistentSearchChangeType.ADD,
+ PersistentSearchChangeType.DELETE,
+ PersistentSearchChangeType.MODIFY,
+ PersistentSearchChangeType.MODIFY_DN));
+
+ final ConnectionEntryReader reader = connection.search(request);
+
+ try {
+ while (reader.hasNext()) {
+ if (!reader.isReference()) {
+ final SearchResultEntry entry = reader.readEntry();
+ System.out.println("Entry changed: "
+ + entry.getName().toString());
+
+ EntryChangeNotificationResponseControl control =
+ entry.getControl(
+ EntryChangeNotificationResponseControl.DECODER,
+ new DecodeOptions());
+
+ PersistentSearchChangeType type = control.getChangeType();
+ System.out.println("Change type: " + type.toString());
+ if (type.equals(PersistentSearchChangeType.MODIFY_DN)) {
+ System.out.println("Previous DN: "
+ + control.getPreviousName().toString());
+ }
+ System.out.println("Change number: "
+ + control.getChangeNumber());
+ System.out.println(); // Add a blank line.
+ }
+ }
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ } catch (final ErrorResultIOException e) {
+ // Request failed due to an IO problem.
+ } catch (final SearchResultReferenceIOException e) {
+ // Read a reference, rather than an entry.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports persistent searches and the entry
+ change notification response control. When another application renames
+ Anne-Louise Barnes's entry, the sample code picks up information from the
+ entry change notification response control:</para>
+
+ <programlisting>Entry changed: uid=bdobbs,ou=People,dc=example,dc=com
+Change type: modifyDN
+Previous DN: uid=abarnes,ou=People,dc=example,dc=com
+Change number: -1</programlisting>
+
+ <para>In this case, <literal>Change number: -1</literal> because the server
+ did not set a change number value. OpenDJ directory server does not set the
+ change number value in the response control. If you need to track the order
+ of changes with OpenDJ directory server, read the external change log instead
+ of using the entry change notification response control.</para>
+ </section>
+
+ <section xml:id="use-get-effective-rights-control">
+ <title>GetEffectiveRights Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>GetEffectiveRights</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
+
+ <para>Your application can attach the GetEffectiveRights request control to
+ retrieve information about what the directory server permits a user to do.
+ Use this control during a search to see permissions on the entries returned.
+ See the Internet-Draft on the <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-acl-model">Access
+ Control Model for LDAP</link> for background.</para>
+
+ <programlisting language="java">
+if (isSupported(GetEffectiveRightsRequestControl.OID)) {
+ final String authDN = "uid=kvaughan,ou=People,dc=example,dc=com";
+
+ final SearchRequest request =
+ Requests.newSearchRequest(
+ "dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
+ "(uid=bjensen)", "cn", "aclRights", "aclRightsInfo")
+ .addControl(GetEffectiveRightsRequestControl.newControl(
+ true, authDN, "cn"));
+
+ final ConnectionEntryReader reader = connection.search(request);
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ while (reader.hasNext()) {
+ if (!reader.isReference()) {
+ final SearchResultEntry entry = reader.readEntry();
+ writer.writeEntry(entry);
+ }
+ }
+ writer.close();
+ } catch (final ErrorResultIOException e) {
+ // Request failed due to an IO problem.
+ } catch (final SearchResultReferenceIOException e) {
+ // Read a reference, rather than an entry.
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ SDK currently implements the request control, but not the
+ response control. The results are shown as values of the
+ <literal>aclRights</literal> and more verbose <literal>aclRightsInfo</literal>
+ attributes.</para>
+
+ <programlisting language="ldif">
+dn: uid=bjensen,ou=People,dc=example,dc=com
+aclRightsInfo;logs;attributeLevel;selfwrite_delete;cn: acl_summary(main)
+ : access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com
+ , distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
+aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read
+ ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, objectClass) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied) ( reason
+ : evaluated allow , deciding_aci: Anonymous read-search access)
+aclRightsInfo;logs;attributeLevel;proxy;cn: acl_summary(main)
+ : access not allowed(proxy) on entry/attr(uid=bjensen,ou=People,dc=example,
+ dc=com, cn) to (uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) (reason: no acis matched the subject )
+aclRights;attributeLevel;cn: search:1,read:1,compare:1,write:1,selfwrite_add:1,
+ selfwrite_delete:1,proxy:0
+aclRightsInfo;logs;attributeLevel;write;cn: acl_summary(main): access allowed
+ (write) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
+aclRights;entryLevel: add:1,delete:1,read:1,write:1,proxy:0
+aclRightsInfo;logs;attributeLevel;search;cn: acl_summary(main): access allowed(
+ search) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
+aclRightsInfo;logs;entryLevel;write: acl_summary(main): access allowed(write
+ ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
+aclRightsInfo;logs;attributeLevel;selfwrite_add;cn: acl_summary(main
+ ): access allowed(write) on entry/attr(uid=bjensen,ou=People,dc=example,
+ dc=com, distinguishedName) to (uid=kvaughan,ou=People,dc=example,dc=com) (
+ not proxied) ( reason: evaluated allow , deciding_aci: allow all Admin group)
+aclRightsInfo;logs;entryLevel;add: acl_summary(main): access allowed(add
+ ) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
+aclRightsInfo;logs;attributeLevel;read;cn: acl_summary(main): access allowed(
+ read) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
+cn: Barbara Jensen
+cn: Babs Jensen
+aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(
+ proxy) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: no acis matched the subject )
+aclRightsInfo;logs;attributeLevel;compare;cn: acl_summary(main): access allowed
+ (compare) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, cn) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: Anonymous read-search access)
+aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access allowed(
+ delete) on entry/attr(uid=bjensen,ou=People,dc=example,dc=com, NULL) to (
+ uid=kvaughan,ou=People,dc=example,dc=com) (not proxied
+ ) ( reason: evaluated allow , deciding_aci: allow all Admin group)
+</programlisting>
+ </section>
+
+ <section xml:id="use-managedsait-control">
+ <title>ManageDsaIT Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>ManageDsaIT</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
+
+ <para>The ManageDsaIT control, described in <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc3296">RFC 3296, <citetitle>Named
+ Subordinate References in LDAP Directories</citetitle></link>, lets your
+ application handle references and other special entries as normal entries.
+ Use it when you want to read from or write to reference or special
+ entry.</para>
+
+ <programlisting language="java">
+if (isSupported(ManageDsaITRequestControl.OID)) {
+ final String dn = "dc=ref,dc=com";
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ System.out.println("Referral without the ManageDsaIT control.");
+ SearchRequest request = Requests.newSearchRequest(dn,
+ SearchScope.SUBORDINATES, "(objectclass=*)", "");
+ final ConnectionEntryReader reader = connection.search(request);
+ while (reader.hasNext()) {
+ if (reader.isReference()) {
+ final SearchResultReference ref = reader.readReference();
+ System.out.println("Reference: " + ref.getURIs().toString());
+ }
+ }
+
+ System.out.println("Referral with the ManageDsaIT control.");
+ request.addControl(ManageDsaITRequestControl.newControl(true));
+ final SearchResultEntry entry = connection.searchSingleEntry(request);
+ writer.writeEntry(entry);
+ writer.close();
+ } catch (final ErrorResultIOException e) {
+ // Request failed due to an IO problem.
+ } catch (final SearchResultReferenceIOException e) {
+ // Read a reference, rather than an entry.
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the ManageDsaIT Request Control. To use
+ the example entry create a new base DN, <literal>dc=ref,dc=com</literal>
+ before you import the data:</para>
+
+ <programlisting>Referral without the ManageDsaIT control.
+Reference: [ldap:///dc=example,dc=com??sub?]
+Referral with the ManageDsaIT control.
+dn: dc=references,dc=ref,dc=com</programlisting>
+ </section>
+
+ <section xml:id="use-matched-values-request-control">
+ <title>Matched Values Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Matched values</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Groups</primary>
+ </indexterm>
+
+ <para>RFC 3876, <link xlink:href="http://tools.ietf.org/html/rfc3876"
+ xlink:show="new"><citetitle>Returning Matched Values with the
+ LDAPv3</citetitle></link>, describes a control that lets your application
+ pass a filter in a search request getting a multivalued attribute such that
+ the directory server only returns attribute values that match the
+ filter.</para>
+
+ <para>Barbara Jensen's entry contains two common name values,
+ <literal>Barbara Jensen</literal> and <literal>Babs Jensen</literal>. The
+ following excerpt retrieves only the latter.</para>
+
+ <programlisting language="java">
+if (isSupported(MatchedValuesRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+ final SearchRequest request =
+ Requests.newSearchRequest(dn, SearchScope.BASE_OBJECT,
+ "(objectclass=*)", "cn")
+ .addControl(MatchedValuesRequestControl.newControl(
+ true, "(cn=Babs Jensen)"));
+
+ final SearchResultEntry entry = connection.searchSingleEntry(request);
+ System.out.println("Reading entry with matched values request.");
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ writer.writeEntry(entry);
+ writer.close();
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the matched values request
+ control.</para>
+
+ <programlisting language="ldif">Reading entry with matched values request.
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Babs Jensen
+</programlisting>
+ </section>
+
+ <section xml:id="use-password-expired-control">
+ <title>Password Expired Response Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Password expired</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+
+ <para>A directory server can return the Password Expired Response Control,
+ described in the Internet-Draft <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy"><citetitle
+ >Password Policy for LDAP Directories</citetitle></link>, when a bind fails
+ because the password has expired. In order to see this, you must configure
+ the directory to expire Barbara Jensen's password.</para>
+
+ <programlisting language="java">
+if (isSupported(PasswordExpiredResponseControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+ final char[] pwd = "hifalutin".toCharArray();
+
+ try {
+ connection.bind(dn, pwd);
+ } catch (final ErrorResultException e) {
+ final Result result = e.getResult();
+ try {
+ final PasswordExpiredResponseControl control =
+ result.getControl(PasswordExpiredResponseControl.DECODER,
+ new DecodeOptions());
+ if (!(control == null) && control.hasValue()) {
+ System.out.println("Password expired for " + dn);
+ }
+ } catch (final DecodeException de) {
+ // Failed to decode the response control.
+ }
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the Password Expired Response Control.
+ To obtain the following output from the excerpt, you can change the default
+ password policy configuration to set a short maximum password age, change
+ Barbara Jensen's password, and wait for it to expire. See the OpenDJ
+ <citetitle>Administration Guide</citetitle> procedure explaining how
+ <link xlink:href="admin-guide#default-pwp"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle
+ >To Adjust the Default Password Policy</citetitle></link> for an example
+ of how to adjust the maximum password age.</para>
+
+ <programlisting
+ >Password expired for uid=bjensen,ou=People,dc=example,dc=com</programlisting>
+ </section>
+
+ <section xml:id="use-password-expiring-control">
+ <title>Password Expiring Response Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Password expiring</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+
+ <para>The Password Expiring Response Control, described in the Internet-Draft
+ <link xlink:href="http://tools.ietf.org/html/draft-vchu-ldap-pwd-policy"
+ xlink:show="new" ><citetitle>Password Policy for LDAP
+ Directories</citetitle></link>, warns your application during a bind
+ that the password used will soon expire.</para>
+
+ <programlisting language="java">
+if (isSupported(PasswordExpiringResponseControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+ final char[] pwd = "hifalutin".toCharArray();
+
+ final BindResult result = connection.bind(dn, pwd);
+ try {
+ final PasswordExpiringResponseControl control =
+ result.getControl(PasswordExpiringResponseControl.DECODER,
+ new DecodeOptions());
+ if (!(control == null) && control.hasValue()) {
+ System.out.println("Password for " + dn + " expires in "
+ + control.getSecondsUntilExpiration() + " seconds.");
+ }
+ } catch (final DecodeException de) {
+ // Failed to decode the response control.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the Password Expiring Response Control.
+ To obtain the following output from the excerpt, you can change the default
+ password policy configuration to set a maximum password age and a warning
+ interval, change Barbara Jensen's password, and wait until you enter the
+ warning interval before password expiration. See the OpenDJ
+ <citetitle>Administration Guide</citetitle> procedure explaining how
+ <link xlink:href="admin-guide#default-pwp"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle
+ >To Adjust the Default Password Policy</citetitle></link> for an example
+ of how to adjust the maximum password age. Also set a short
+ <literal>password-expiration-warning-interval</literal> value.</para>
+
+ <programlisting>Password for uid=bjensen,ou=People,dc=example,dc=com
+ expires in 237 seconds.</programlisting>
+ </section>
+
+ <section xml:id="use-password-policy-controls">
+ <title>Password Policy Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Password policy</secondary>
+ </indexterm>
+
+ <para>The Behera Internet-Draft, <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/draft-behera-ldap-password-policy"
+ ><citetitle>Password Policy for LDAP Directories</citetitle></link>, describes
+ Password Policy Request and Response Controls. You send the request control
+ with a request to let the directory server know that your application can
+ handle the response control. The directory server sends the response control
+ on applicable operations to communicate warnings and errors.</para>
+
+ <programlisting language="java">
+if (isSupported(PasswordPolicyRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+ final char[] pwd = "hifalutin".toCharArray();
+
+ try {
+ final BindRequest request = Requests.newSimpleBindRequest(dn, pwd)
+ .addControl(PasswordPolicyRequestControl.newControl(true));
+
+ final BindResult result = connection.bind(request);
+
+ final PasswordPolicyResponseControl control =
+ result.getControl(PasswordPolicyResponseControl.DECODER,
+ new DecodeOptions());
+ if (!(control == null) && !(control.getWarningType() == null)) {
+ System.out.println("Password policy warning "
+ + control.getWarningType().toString() + ", value "
+ + control.getWarningValue() + " for " + dn);
+ }
+ } catch (final ErrorResultException e) {
+ final Result result = e.getResult();
+ try {
+ final PasswordPolicyResponseControl control =
+ result.getControl(PasswordPolicyResponseControl.DECODER,
+ new DecodeOptions());
+ if (!(control == null)) {
+ System.out.println("Password policy error "
+ + control.getErrorType().toString() + " for " + dn);
+ }
+ } catch (final DecodeException de) {
+ // Failed to decode the response control.
+ }
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the Password Policy Controls. To obtain
+ the output from the excerpt, you can change the default password policy
+ configuration to set a maximum password age and a warning interval, change
+ Barbara Jensen's password, and then run the example during the warning
+ interval and after the password has expired. See the OpenDJ
+ <citetitle>Administration Guide</citetitle> procedure explaining how
+ <link xlink:href="admin-guide#default-pwp"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle
+ >To Adjust the Default Password Policy</citetitle></link> for an example
+ of how to adjust the maximum password age. Also set a short
+ <literal>password-expiration-warning-interval</literal> value.</para>
+
+ <para>For a warning:</para>
+ <programlisting>Password policy warning timeBeforeExpiration, value 237 for
+ uid=bjensen,ou=People,dc=example,dc=com</programlisting>
+
+ <para>For an error:</para>
+ <programlisting>Password policy error passwordExpired for
+ uid=bjensen,ou=People,dc=example,dc=com</programlisting>
+ </section>
+
+ <section xml:id="use-permissive-modify-request-control">
+ <title>Permissive Modify Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Permissive modify</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Modifications</primary>
+ <secondary>Permissive modify</secondary>
+ </indexterm>
+
+ <para>Microsoft defined a Permissive Modify Request Control that relaxes
+ some constraints when your application performs a modify operation and
+ tries to <literal>add</literal> an attribute that already exists, or to
+ <literal>delete</literal> an attribute that does not exist.</para>
+
+ <programlisting language="java">
+if (isSupported(PermissiveModifyRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+
+ final ModifyRequest request =
+ Requests.newModifyRequest(dn)
+ .addControl(PermissiveModifyRequestControl.newControl(true))
+ .addModification(ModificationType.ADD, "uid", "bjensen");
+
+ connection.modify(request);
+ System.out.println("Permissive modify did not complain about "
+ + "attempt to add uid: bjensen to " + dn + ".");
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the Permissive Modify Request
+ Control:</para>
+
+ <programlisting>Permissive modify did not complain about attempt to add
+ uid: bjensen to uid=bjensen,ou=People,dc=example,dc=com.</programlisting>
+ </section>
+
+ <section xml:id="use-persistent-search-request-control">
+ <title>Persistent Search Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Persistent search</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Change notification</primary>
+ </indexterm>
+
+ <para>See <xref linkend="use-entry-change-notification-control" />.</para>
+ </section>
+
+ <section xml:id="use-post-read-control">
+ <title>Post-Read Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Post-read</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+
+ <para>RFC 4527, <link xlink:href="http://tools.ietf.org/html/rfc4527"
+ xlink:show="new"><citetitle>LDAP Read Entry Controls</citetitle></link>,
+ describes the post-read controls that let your application get the content
+ of an entry immediately after modifications are applied.</para>
+
+ <programlisting language="java">
+if (isSupported(PostReadRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+
+ final ModifyRequest request =
+ Requests.newModifyRequest(dn)
+ .addControl(PostReadRequestControl.newControl(true, "description"))
+ .addModification(ModificationType.REPLACE,
+ "description", "Using the PostReadRequestControl");
+
+ final Result result = connection.modify(request);
+ try {
+ final PostReadResponseControl control =
+ result.getControl(PostReadResponseControl.DECODER,
+ new DecodeOptions());
+ final Entry entry = control.getEntry();
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ writer.writeEntry(entry);
+ writer.close();
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports these controls:</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description: Using the PostReadRequestControl</programlisting>
+ </section>
+
+ <section xml:id="use-pre-read-control">
+ <title>Pre-Read Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Pre-read</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Assertions</primary>
+ </indexterm>
+
+ <para>RFC 4527, <link xlink:href="http://tools.ietf.org/html/rfc4527"
+ xlink:show="new"><citetitle>LDAP Read Entry Controls</citetitle></link>,
+ describes the pre-read controls that let your application get the content
+ of an entry immediately before modifications are applied.</para>
+
+ <programlisting language="java">
+if (isSupported(PreReadRequestControl.OID)) {
+ final String dn = "uid=bjensen,ou=People,dc=example,dc=com";
+
+ final ModifyRequest request =
+ Requests.newModifyRequest(dn)
+ .addControl(PreReadRequestControl.newControl(true, "mail"))
+ .addModification(
+ ModificationType.REPLACE, "mail", "modified@example.com");
+
+ final Result result = connection.modify(request);
+ try {
+ final PreReadResponseControl control =
+ result.getControl(PreReadResponseControl.DECODER,
+ new DecodeOptions());
+ final Entry entry = control.getEntry();
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ writer.writeEntry(entry);
+ writer.close();
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports these controls:</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+mail: bjensen@example.com</programlisting>
+ </section>
+
+ <section xml:id="use-proxy-authz-control">
+ <title>Proxied Authorization Request Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Proxied authorization</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
+
+ <para>Proxied authorization provides a standard control as defined in
+ <link xlink:href="http://tools.ietf.org/html/rfc4370" xlink:show="new">RFC
+ 4370</link> (and an earlier Internet-Draft) for binding with the user
+ credentials of a proxy, who carries out LDAP operations on behalf of other
+ users. You might use proxied authorization, for example, to have your
+ application bind with its credentials, and then carry out operations as the
+ users who login to the application.</para>
+
+ <programlisting language="java">
+if (isSupported(ProxiedAuthV2RequestControl.OID)) {
+ final String bindDN = "cn=My App,ou=Apps,dc=example,dc=com";
+ final String targetDn = "uid=bjensen,ou=People,dc=example,dc=com";
+ final String authzId = "dn:uid=kvaughan,ou=People,dc=example,dc=com";
+
+ final ModifyRequest request =
+ Requests.newModifyRequest(targetDn)
+ .addControl(ProxiedAuthV2RequestControl.newControl(authzId))
+ .addModification(ModificationType.REPLACE, "description",
+ "Done with proxied authz");
+
+ connection.bind(bindDN, "password".toCharArray());
+ connection.modify(request);
+ final Entry entry = connection.readEntry(targetDn, "description");
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ writer.writeEntry(entry);
+ writer.close();
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}</programlisting>
+
+ <para>OpenDJ supports proxied authorization, and the example works with the
+ sample data:</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description: Done with proxied authz</programlisting>
+ </section>
+
+ <section xml:id="use-server-side-sort-control">
+ <title>Server-Side Sort Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Server-side sort</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Server-side sort</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Browsing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Sorting</primary>
+ </indexterm>
+
+ <para>The server-side sort controls are described in RFC 2891, <link
+ xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc2891"><citetitle
+ >LDAP Control Extension for Server Side Sorting of Search
+ Results</citetitle></link>. If possible, sort on the client side instead to
+ reduce load on the server. If not, then you can request a server-side
+ sort.</para>
+
+ <programlisting language="java">
+static void useServerSideSortRequestControl(Connection connection)
+ throws ErrorResultException {
+ if (isSupported(ServerSideSortRequestControl.OID)) {
+ final SearchRequest request =
+ Requests.newSearchRequest("ou=People,dc=example,dc=com",
+ SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
+ .addControl(ServerSideSortRequestControl.newControl(
+ true, new SortKey("cn")));
+
+ final SearchResultHandler resultHandler = new MySearchResultHandler();
+ final Result result = connection.search(request, resultHandler);
+
+ try {
+ final ServerSideSortResponseControl control =
+ result.getControl(ServerSideSortResponseControl.DECODER,
+ new DecodeOptions());
+ if (control != null && control.getResult() == ResultCode.SUCCESS) {
+ System.out.println("# Entries are sorted.");
+ } else {
+ System.out.println("# Entries not necessarily sorted");
+ }
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ }
+ } else {
+ System.out.println("ServerSideSortRequestControl not supported");
+ }
+}
+
+private static class MySearchResultHandler implements SearchResultHandler {
+
+ @Override
+ public void handleErrorResult(ErrorResultException error) {
+ // Ignore.
+ }
+
+ @Override
+ public void handleResult(Result result) {
+ // Ignore.
+ }
+
+ @Override
+ public boolean handleEntry(SearchResultEntry entry) {
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ writer.writeEntry(entry);
+ writer.flush();
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+ return true;
+ }
+
+ @Override
+ public boolean handleReference(SearchResultReference reference) {
+ System.out.println("Got a reference: " + reference.toString());
+ return false;
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports server-side sorting:</para>
+
+ <programlisting language="ldif">dn: uid=ajensen,ou=People,dc=example,dc=com
+cn: Allison Jensen
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+
+dn: uid=bjense2,ou=People,dc=example,dc=com
+cn: Bjorn Jensen
+
+dn: uid=gjensen,ou=People,dc=example,dc=com
+cn: Gern Jensen
+
+dn: uid=jjensen,ou=People,dc=example,dc=com
+cn: Jody Jensen
+
+dn: uid=kjensen,ou=People,dc=example,dc=com
+cn: Kurt Jensen
+
+dn: uid=rjense2,ou=People,dc=example,dc=com
+cn: Randy Jensen
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+cn: Richard Jensen
+
+dn: uid=tjensen,ou=People,dc=example,dc=com
+cn: Ted Jensen
+
+# Entries are sorted.</programlisting>
+ </section>
+
+ <section xml:id="use-simple-paged-results-control">
+ <title>Simple Paged Results Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Simple paged results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Simple paged results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Browsing</primary>
+ </indexterm>
+
+ <para>RFC 2696, <link xlink:href="http://tools.ietf.org/html/rfc2696"
+ xlink:show="new"><citetitle>LDAP Control Extension for Simple Paged Results
+ Manipulation</citetitle></link>, defines a control for simple paging of
+ search results that works with a cookie mechanism.</para>
+
+ <programlisting language="java">
+if (isSupported(SimplePagedResultsControl.OID)) {
+ ByteString cookie = ByteString.empty();
+ SearchRequest request;
+ final SearchResultHandler resultHandler = new MySearchResultHandler();
+ Result result;
+
+ int page = 1;
+ do {
+ System.out.println("# Simple paged results: Page " + page);
+
+ request =
+ Requests.newSearchRequest("dc=example,dc=com",
+ SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn")
+ .addControl(SimplePagedResultsControl.newControl(
+ true, 3, cookie));
+
+ result = connection.search(request, resultHandler);
+ try {
+ SimplePagedResultsControl control =
+ result.getControl(SimplePagedResultsControl.DECODER,
+ new DecodeOptions());
+ cookie = control.getCookie();
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ }
+
+ ++page;
+ } while (cookie.length() != 0);
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports getting simple paged results:</para>
+
+ <programlisting language="ldif"># Simple paged results: Page 1
+dn: uid=ajensen,ou=People,dc=example,dc=com
+cn: Allison Jensen
+
+dn: uid=bjense2,ou=People,dc=example,dc=com
+cn: Bjorn Jensen
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+
+# Simple paged results: Page 2
+dn: uid=gjensen,ou=People,dc=example,dc=com
+cn: Gern Jensen
+
+dn: uid=jjensen,ou=People,dc=example,dc=com
+cn: Jody Jensen
+
+dn: uid=kjensen,ou=People,dc=example,dc=com
+cn: Kurt Jensen
+
+# Simple paged results: Page 3
+dn: uid=rjense2,ou=People,dc=example,dc=com
+cn: Randy Jensen
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+cn: Richard Jensen
+
+dn: uid=tjensen,ou=People,dc=example,dc=com
+cn: Ted Jensen
+</programlisting>
+ </section>
+
+ <section xml:id="use-subentry-request-control">
+ <title>Subentries Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Subentries</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Subentries</secondary>
+ </indexterm>
+
+ <para>RFC 3672, <link xlink:href="http://tools.ietf.org/html/rfc3672"
+ xlink:show="new"><citetitle>Subentries in LDAP</citetitle></link>, describes
+ subentries and also the subentries request control. When you perform a search
+ without the control and visibility set to <literal>TRUE</literal>, subentries
+ are only visible in searches with
+ <literal>SearchScope.BASE_OBJECT</literal>.</para>
+
+ <programlisting language="java">
+if (isSupported(SubentriesRequestControl.OID)) {
+ final SearchRequest request =
+ Requests.newSearchRequest("dc=example,dc=com",
+ SearchScope.WHOLE_SUBTREE,
+ "cn=*Class of Service", "cn", "subtreeSpecification")
+ .addControl(SubentriesRequestControl.newControl(
+ true, true));
+
+ final ConnectionEntryReader reader = connection.search(request);
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ try {
+ while (reader.hasNext()) {
+ if (reader.isEntry()) {
+ final SearchResultEntry entry = reader.readEntry();
+ writer.writeEntry(entry);
+ }
+ }
+ writer.close();
+ } catch (final ErrorResultIOException e) {
+ // Request failed due to an IO problem.
+ } catch (final SearchResultReferenceIOException e) {
+ // Read a reference, rather than an entry.
+ } catch (final IOException e) {
+ // The writer could not write to System.out.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the control.</para>
+
+ <programlisting language="ldif">dn: cn=Bronze Class of Service,dc=example,dc=com
+cn: Bronze Class of Service
+subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ bronze)" }
+
+dn: cn=Silver Class of Service,dc=example,dc=com
+cn: Silver Class of Service
+subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ silver)" }
+
+dn: cn=Gold Class of Service,dc=example,dc=com
+cn: Gold Class of Service
+subtreeSpecification: { base "ou=People", specificationFilter "(classOfService=
+ gold)" }
+</programlisting>
+ </section>
+
+ <section xml:id="use-subtree-delete-control">
+ <title>Subtree Delete Request Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Subtree delete</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Deletes</primary>
+ <secondary>Subtree delete</secondary>
+ </indexterm>
+
+ <para>The subtree delete request control, described in the Internet-Draft
+ <link xlink:href="http://tools.ietf.org/html/draft-armijo-ldap-treedelete"
+ xlink:show="new"><citetitle>Tree Delete Control</citetitle></link>, lets
+ your application delete an entire branch of entries starting with the entry
+ you target for deletion.</para>
+
+ <programlisting language="java">
+if (isSupported(SubtreeDeleteRequestControl.OID)) {
+
+ final String dn = "ou=Apps,dc=example,dc=com";
+ final DeleteRequest request =
+ Requests.newDeleteRequest(dn)
+ .addControl(SubtreeDeleteRequestControl.newControl(true));
+
+ final Result result = connection.delete(request);
+ if (result.isSuccess()) {
+ System.out.println("Successfully deleted " + dn
+ + " and all entries below.");
+ } else {
+ System.out.println("Result: " + result.getDiagnosticMessage());
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the subtree delete control:</para>
+
+ <programlisting
+ >Successfully deleted ou=Apps,dc=example,dc=com and all entries below.</programlisting>
+ </section>
+
+ <section xml:id="use-vlv-control">
+ <title>Virtual List View Controls</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Virtual list view</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Virtual list view</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Browsing</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Sorting</primary>
+ </indexterm>
+
+ <para>The virtual list view controls are intended to be used by applications
+ that let users browse lists of directory entries. The Internet-Draft <link
+ xlink:href="http://tools.ietf.org/html/draft-ietf-ldapext-ldapv3-vlv"
+ xlink:show="new"><citetitle>LDAP Extensions for Scrolling View Browsing of
+ Search Results</citetitle></link> describes the controls. The virtual list
+ view request control is used in conjunction with the server-side sort
+ control such that the subset of entries the directory server returns from
+ a search are a window into the full sorted list.</para>
+
+ <programlisting language="java">
+if (isSupported(VirtualListViewRequestControl.OID)) {
+ ByteString contextID = ByteString.empty();
+
+ // Add a window of 2 entries on either side of the first sn=Jensen entry.
+ final SearchRequest request =
+ Requests.newSearchRequest("ou=People,dc=example,dc=com",
+ SearchScope.WHOLE_SUBTREE, "(sn=*)", "sn", "givenName")
+ .addControl(ServerSideSortRequestControl.newControl(
+ true, new SortKey("sn")))
+ .addControl(
+ VirtualListViewRequestControl.newAssertionControl(
+ true,
+ ByteString.valueOf("Jensen"),
+ 2, 2, contextID));
+
+ final SearchResultHandler resultHandler = new MySearchResultHandler();
+ final Result result = connection.search(request, resultHandler);
+
+ try {
+ final ServerSideSortResponseControl sssControl =
+ result.getControl(ServerSideSortResponseControl.DECODER,
+ new DecodeOptions());
+ if (sssControl != null && sssControl.getResult() == ResultCode.SUCCESS){
+ System.out.println("# Entries are sorted.");
+ } else {
+ System.out.println("# Entries not necessarily sorted");
+ }
+
+ final VirtualListViewResponseControl vlvControl =
+ result.getControl(VirtualListViewResponseControl.DECODER,
+ new DecodeOptions());
+ System.out.println("# Position in list: "
+ + vlvControl.getTargetPosition() + "/"
+ + vlvControl.getContentCount());
+ } catch (final DecodeException e) {
+ // Failed to decode the response control.
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the virtual list view controls.
+ In order to set up OpenDJ directory server to produce the following output
+ with the example code, use OpenDJ Control Panel > Manage Indexes > New
+ VLV Index... to set up a virtual list view index for people by last name,
+ using the filter <literal>(|(givenName=*)(sn=*))</literal>, and sorting first
+ by surname, <literal>sn</literal>, in ascending order, then by given name
+ also in ascending order.</para>
+
+ <programlisting language="ldif">dn: uid=skellehe,ou=People,dc=example,dc=com
+givenName: Sue
+sn: Kelleher
+
+dn: uid=ejohnson,ou=People,dc=example,dc=com
+givenName: Emanuel
+sn: Johnson
+
+dn: uid=ajensen,ou=People,dc=example,dc=com
+givenName: Allison
+sn: Jensen
+
+dn: uid=bjense2,ou=People,dc=example,dc=com
+givenName: Bjorn
+sn: Jensen
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+givenName: Barbara
+sn: Jensen
+
+# Entries are sorted.
+# Position in list: 92/150</programlisting>
+ </section>
+
+ <section xml:id="use-generic-control">
+ <title>Using a Generic Control</title>
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>Generic</secondary>
+ </indexterm>
+
+ <para>OpenDJ LDAP SDK supports many controls, but you might still need to
+ work with additional controls. If so, then in some cases you can use the
+ <literal>GenericControl</literal> class when adding the control to your
+ request.</para>
+
+ <para>For example, the Microsoft <link xlink:show="new"
+ xlink:href="http://msdn.microsoft.com/en-us/library/windows/desktop/aa366983(v=vs.85).aspx"
+ >LDAP Server Notification Control</link> with OID
+ <literal>1.2.840.113556.1.4.528</literal> can be used to register a change
+ notification request for a search on Microsoft Active Directory. You can use
+ a <literal>GenericControl.newControl()</literal> static method to add the
+ request control to your search.</para>
+
+ <filename>org.forgerock.opendj.examples.GetADChangeNotifications.java</filename>
+
+ <para>When you run the search against Active Directory and then create,
+ update, and delete a new user, in this example
+ <literal>CN=New User,CN=Users,DC=ad,DC=example,DC=com</literal>, Active
+ Directory notifies you of changes to directory data.</para>
+
+ <programlisting language="ldif"
+ ># Search result entry: CN=RID Set,CN=WIN2008R2641,OU=Domain Controllers,
+ DC=ad,DC=example,DC=com
+dn: CN=RID Set,CN=WIN2008R2641,OU=Domain Controllers,DC=ad,DC=example,DC=com
+objectClass: top
+objectClass: rIDSet
+objectGUID:: 178zQQic3EOoBOB1j2QVgQ==
+uSNChanged: 12446
+
+# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: user
+objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
+uSNChanged: 12753
+
+# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: user
+objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
+uSNChanged: 12755
+
+# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: user
+objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
+uSNChanged: 12757
+
+# Search result entry: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+dn: CN=New User,CN=Users,DC=ad,DC=example,DC=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: user
+objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
+uSNChanged: 12758
+
+# Search result entry: CN=New User\0ADEL:3a3f71ed-5d82-4a14-807a-0c008b678d94,
+# CN=Deleted Objects,DC=ad,DC=example,DC=com
+dn: CN=New User\0ADEL:3a3f71ed-5d82-4a14-807a-0c008b678d94,CN=Deleted Objects,
+ DC=ad,DC=example,DC=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: user
+objectGUID:: 7XE/OoJdFEqAegwAi2eNlA==
+isDeleted: TRUE
+uSNChanged: 12759
+</programlisting>
+
+ <para>The <literal>GenericControl</literal> class is useful with controls that
+ do not require you to encode complex request values, or decode complex
+ response values. If the control you want to you requires complex encoding
+ or decoding, you might have to implement
+ <literal>org.forgerock.opendj.ldap.controls.Control</literal>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-extended-ops.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-extended-ops.xml
new file mode 100644
index 0000000..f169870
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-extended-ops.xml
@@ -0,0 +1,342 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-extended-ops'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Working With Extended Operations</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Extended operations</secondary>
+ </indexterm>
+
+ <para>This chapter demonstrates how to use LDAP extended operations.</para>
+
+ <para>For complete examples corresponding to the excerpts shown below, see
+ <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ExtendedOperations.html"
+ xlink:show="new">ExtendedOperations.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+
+ <section xml:id="about-ldap-extended-operations">
+ <title>About LDAP Extended Operations</title>
+ <para>Extended operations allow additional operations to be defined for
+ services not already available in the protocol</para>
+ </section>
+
+ <section xml:id="get-supported-extended-operations">
+ <title>Determining Supported Extended Operations</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Supported</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
+
+ <para>For OpenDJ, the extended operations supported are listed in the
+ <citetitle>Administration Guide</citetitle> appendix, <link
+ xlink:href="admin-guide#appendix-extended-ops"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>LDAP Extended
+ Operations</citetitle></link>. You can access the list of OIDs for
+ supported LDAP controls by reading the <literal>supportedExtension</literal>
+ attribute of the root DSE.</para>
+
+ <screen>$ ldapsearch
+ --baseDN ""
+ --searchScope base
+ --port 1389
+ "(objectclass=*)" supportedExtension
+dn:
+supportedExtension: 1.3.6.1.1.8
+supportedExtension: 1.3.6.1.4.1.26027.1.6.1
+supportedExtension: 1.3.6.1.4.1.26027.1.6.2
+supportedExtension: 1.3.6.1.4.1.26027.1.6.3
+supportedExtension: 1.3.6.1.4.1.4203.1.11.1
+supportedExtension: 1.3.6.1.4.1.4203.1.11.3
+supportedExtension: 1.3.6.1.4.1.1466.20037</screen>
+
+ <para>The following excerpt shows code to check for supported extended
+ operations.</para>
+
+ <programlisting language="java">
+/**
+ * Controls supported by the LDAP server.
+ */
+private static Collection<String> extendedOperations;
+
+/**
+ * Populate the list of supported LDAP extended operation OIDs.
+ *
+ * @param connection
+ * Active connection to the LDAP server.
+ * @throws ErrorResultException
+ * Failed to get list of extended operations.
+ */
+static void checkSupportedExtendedOperations(Connection connection)
+ throws ErrorResultException {
+ extendedOperations = RootDSE.readRootDSE(connection)
+ .getSupportedExtendedOperations();
+}
+
+/**
+ * Check whether an extended operation is supported. Call
+ * {@code checkSupportedExtendedOperations} first.
+ *
+ * @param extendedOperation
+ * Check support for this extended operation, provided by OID.
+ * @return True if the control is supported.
+ */
+static boolean isSupported(final String extendedOperation) {
+ if (extendedOperations != null && !extendedOperations.isEmpty()) {
+ return extendedOperations.contains(extendedOperation);
+ }
+ return false;
+}
+</programlisting>
+ </section>
+
+ <section xml:id="use-cancel-extended-operation">
+ <title>Cancel Extended Operation</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Cancel</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Cancel</secondary>
+ </indexterm>
+
+ <para>RFC 3909, <link xlink:href="http://tools.ietf.org/html/rfc3909"
+ xlink:show="new"><citetitle>LDAP Cancel Operation</citetitle></link>, defines
+ an extended operation that lets you cancel an operation in progress and get
+ an indication of the outcome.</para>
+
+ <para>The Cancel extended request uses the request ID of operation you
+ want to cancel, and so therefore works with asynchronous searches and
+ updates. Depending on the delay between your application sending the Cancel
+ request and the directory server receiving the request, the server might have
+ already finished processing the original request before it receives your
+ Cancel request.</para>
+
+ <para>You can add a Cancel extended request for example to stop handling
+ entries returned from a search if the directory server returns more entries
+ than you want.</para>
+
+ <programlisting language="java">
+private static final CountDownLatch COMPLETION_LATCH = new CountDownLatch(1);
+private static final CountDownLatch CANCEL_LATCH = new CountDownLatch(1);
+private static final LDIFEntryWriter WRITER = new LDIFEntryWriter(System.out);
+
+static int requestID;
+static int entryCount = 0;
+
+// The requestID is obtained from the future result of the asynchronous search.
+// For more context see the example, SearchAsync.java.
+
+private static final class SearchResultHandlerImpl
+ implements SearchResultHandler {
+
+ @Override
+ public synchronized boolean handleEntry(final SearchResultEntry entry) {
+ try {
+ // Cancel the search if it returns too many results.
+ if (entryCount < 10) {
+ WRITER.writeComment("Search result entry: "
+ + entry.getName().toString());
+ WRITER.writeEntry(entry);
+ ++entryCount;
+ } else {
+ CancelExtendedRequest request =
+ Requests.newCancelExtendedRequest(requestID);
+ connection.extendedRequestAsync(
+ request, null, new CancelResultHandlerImpl());
+ return false;
+ }
+ } catch (final IOException e) {
+ System.err.println(e.getMessage());
+ resultCode = ResultCode.CLIENT_SIDE_LOCAL_ERROR.intValue();
+ COMPLETION_LATCH.countDown();
+ return false;
+ }
+ return true;
+ }
+ ...
+}
+
+private static final class CancelResultHandlerImpl
+ implements ResultHandler<ExtendedResult> {
+
+ @Override
+ public void handleErrorResult(final ErrorResultException error) {
+ System.err.println("Cancel request failed with result code: "
+ + error.getResult().getResultCode().intValue());
+ CANCEL_LATCH.countDown();
+ }
+
+ @Override
+ public void handleResult(final ExtendedResult result) {
+ System.err.println("Cancel request succeeded");
+ CANCEL_LATCH.countDown();
+ }
+
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the cancel operation. If OpenDJ
+ directory server manages to return all entries in
+ <filename>Example.ldif</filename> before it receives the Cancel extended
+ request, you can see the Cancel request fail because the request ID refers
+ to the search, which is no longer in progress. Try adding a new base DN using
+ OpenDJ control panel and adding the default 2000 generated entries to ensure
+ more search results. For example if <literal>dc=example,dc=org</literal>
+ contains 2000 generated entries, and the <literal>SearchAsync</literal>
+ example is run with the arguments <literal>sub objectclass=* cn</literal>
+ for scope, filter, and attributes respectively, then the example produces
+ something like the following output:</para>
+
+ <programlisting>
+Canceled: Processing on this operation was terminated as a result of receiving
+ a cancel request (message ID 3)
+# Search result entry: dc=example,dc=org
+dn: dc=example,dc=org
+
+# Search result entry: ou=People,dc=example,dc=org
+dn: ou=People,dc=example,dc=org
+
+# Search result entry: uid=user.0,ou=People,dc=example,dc=org
+dn: uid=user.0,ou=People,dc=example,dc=org
+cn: Aaccf Amar
+
+...
+
+Cancel request succeeded</programlisting>
+ </section>
+
+ <section xml:id="use-password-modify-extended-operation">
+ <title>Password Modify Extended Operation</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Password modify</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Modifications</primary>
+ <secondary>Password modify</secondary>
+ </indexterm>
+
+ <para>RFC 3062, <link xlink:href="http://tools.ietf.org/html/rfc3062"
+ xlink:show="new"><citetitle>LDAP Password Modify Extended
+ Operation</citetitle></link>, defines an extended operation for modifying
+ user passwords that does not depend on the authentication identity, nor on
+ the way passwords are stored.</para>
+
+ <programlisting language="java">
+if (isSupported(PasswordModifyExtendedRequest.OID)) {
+ final String userIdentity = "u:scarter";
+ final char[] oldPassword = "sprain".toCharArray();
+ final char[] newPassword = "secret12".toCharArray();
+
+ final PasswordModifyExtendedRequest request =
+ Requests.newPasswordModifyExtendedRequest()
+ .setUserIdentity(userIdentity)
+ .setOldPassword(oldPassword)
+ .setNewPassword(newPassword);
+
+ final PasswordModifyExtendedResult result =
+ connection.extendedRequest(request);
+ if (result.isSuccess()) {
+ System.out.println("Changed password for " + userIdentity);
+ } else {
+ System.err.println(result.getDiagnosticMessage());
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the password modify operation.</para>
+
+ <programlisting>Changed password for u:scarter</programlisting>
+ </section>
+
+ <section xml:id="use-starttls-extended-operation">
+ <title>Start TLS Extended Operation</title>
+
+ <para>Use Start TLS when setting up your connection to protect what your
+ application sends to and receives from the directory server. For an example,
+ read the section on <link
+ xlink:href="dev-guide#simple-auth-with-starttls-or-ssl"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Start TLS &
+ SSL Authentication</citetitle></link>.</para>
+ </section>
+
+ <section xml:id="use-who-am-i-extended-operation">
+ <title>Who am I? Extended Operation</title>
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>Who am I?</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
+
+ <para>RFC 4532, <link xlink:href="http://tools.ietf.org/html/rfc4532"
+ xlink:show="new"><citetitle>LDAP "Who am I?" Operation</citetitle></link>,
+ defines an extended operation that lets your application determine the
+ current authorization ID.</para>
+
+ <programlisting language="java">
+if (isSupported(WhoAmIExtendedRequest.OID)) {
+
+ final String name = "uid=bjensen,ou=People,dc=example,dc=com";
+ final char[] password = "hifalutin".toCharArray();
+
+ final Result result = connection.bind(name, password);
+ if (result.isSuccess()) {
+
+ final WhoAmIExtendedRequest request =
+ Requests.newWhoAmIExtendedRequest();
+ final WhoAmIExtendedResult extResult =
+ connection.extendedRequest(request);
+
+ if (extResult.isSuccess()) {
+ System.out.println("Authz ID: " + extResult.getAuthorizationID());
+ }
+ }
+}
+</programlisting>
+
+ <para>OpenDJ directory server supports the "Who am I?" operation.</para>
+
+ <programlisting
+ >Authz ID: dn:uid=bjensen,ou=People,dc=example,dc=com</programlisting>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-get-sdk.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-get-sdk.xml
new file mode 100644
index 0000000..23f9252
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-get-sdk.xml
@@ -0,0 +1,342 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-get-sdk'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Getting OpenDJ LDAP SDK</title>
+
+ <para>This chapter introduces OpenDJ LDAP SDK, demonstrating how to get the
+ software and to build a first basic directory client application.</para>
+
+ <section xml:id="about-opendj-ldap-sdk">
+ <title>About OpenDJ LDAP SDK</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>About</secondary>
+ </indexterm>
+
+ <para>OpenDJ LDAP SDK provides a set of modern, developer-friendly Java APIs
+ as part of the OpenDJ product suite. The product suite includes the client
+ SDK alongside command-line tools and sample code, a 100% pure Java directory
+ server, and more. You can use OpenDJ LDAP SDK to create client applications
+ for use with any server that complies with the <citetitle>Lightweight
+ Directory Access Protocol (LDAP): Technical Specification Road
+ Map</citetitle>, <link xlink:href='http://tools.ietf.org/html/rfc4510'
+ xlink:show="new">RFC 4510</link>.</para>
+
+ <para>OpenDJ LDAP SDK brings you easy-to-use connection management, connection
+ pooling, load balancing, and all the standard LDAP operations to read and
+ write directory entries. OpenDJ LDAP SDK also lets you build applications with
+ capabilities defined in additional draft and experimental RFCs that are
+ supported by modern LDAP servers.</para>
+ </section>
+
+ <section xml:id="prepare-ldap-server">
+ <title>Preparing an LDAP Server</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Data</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Examples</primary>
+ <secondary>Data</secondary>
+ </indexterm>
+
+ <para>Install an LDAP server such as OpenDJ directory server that you can
+ use to test the applications you develop. Also, load sample data into your
+ server. The sample data used in this guide are available in LDIF form at
+ <link xlink:show="new" xlink:href="http://opendj.forgerock.org/Example.ldif"
+ >http://opendj.forgerock.org/Example.ldif</link>.</para>
+ </section>
+
+ <section xml:id="getting-the-ldap-sdk">
+ <title>Getting the LDAP SDK</title>
+
+ <para>You can either install a build or build your own from source.</para>
+
+ <para>Before you either download a build of OpenDJ LDAP SDK, or get the
+ source code to build your own SDK, make sure you have a Java Development Kit
+ installed. See the <citetitle>Release Notes</citetitle> section on
+ <link xlink:href="release-notes#prerequisites-java" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Java
+ Environment</citetitle></link> requirements.</para>
+
+ <procedure xml:id="use-maven">
+ <title>To Include the SDK as a Maven Dependency</title>
+ <indexterm>
+ <primary>Installing</primary>
+ <secondary>With Maven</secondary>
+ </indexterm>
+
+ <para>Let that expensive computer you bought do the work.</para>
+
+ <step>
+ <para>Include the ForgeRock repository in your list, and include the SDK
+ as a dependency.</para>
+
+ <programlisting language="xml"><repositories>
+ <repository>
+ <id>forgerock-staging-repository</id>
+ <name>ForgeRock Release Repository</name>
+ <url>http://maven.forgerock.org/repo/releases</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ <repository>
+ <id>forgerock-snapshots-repository</id>
+ <name>ForgeRock Snapshot Repository</name>
+ <url>http://maven.forgerock.org/repo/snapshots</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ </repository>
+</repositories>
+
+...
+
+<dependencies>
+ <dependency>
+ <groupId>org.forgerock.opendj</groupId>
+ <artifactId>opendj-ldap-sdk</artifactId>
+ <version><?eval ${sdkDocTargetVersion}?></version>
+ </dependency>
+</dependencies></programlisting>
+ </step>
+ </procedure>
+
+ <procedure xml:id="install-latest-sdk">
+ <title>To Install the Latest SDK & Tools</title>
+ <indexterm>
+ <primary>Installing</primary>
+ <secondary>From download</secondary>
+ </indexterm>
+
+ <step>
+ <para>Download the latest OpenDJ LDAP Client Toolkit nightly build from the
+ <link xlink:href="http://forgerock.org/opendj.html" xlink:show="new"
+ >Nightly Builds</link> page.</para>
+ </step>
+ <step>
+ <para>Unzip the bundle,
+ <filename>opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>.zip</filename>,
+ where you want to install the SDK.</para>
+ <screen>$ unzip opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>.zip</screen>
+ </step>
+ <step>
+ <para>Add the tools to your PATH.</para>
+ <screen>(UNIX)
+$ export PATH=/path/to/opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>/bin:$PATH</screen>
+ <screen>(Windows)
+C:\>set PATH=\\path\to\opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>\bat:%PATH%</screen>
+ </step>
+ <step>
+ <para> Add the OpenDJ LDAP SDK for the APIs, the I18N core library,
+ and Grizzly I/O framework for the transport to your CLASSPATH, typically found under
+ <filename>opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>/lib/</filename>.</para>
+ <screen>(UNIX)
+$ export CLASSPATH=/path/to/lib/grizzly-framework-<?eval ${grizzlyFrameworkVersion}?>.jar:$CLASSPATH
+$ export CLASSPATH=/path/to/lib/i18n-core-<?eval ${i18nFrameworkVersion}?>.jar:$CLASSPATH
+$ export CLASSPATH=/path/to/lib/opendj-ldap-sdk-<?eval ${sdkDocTargetVersion}?>.jar:$CLASSPATH
+ </screen>
+ <screen>(Windows)
+C:\>set CLASSPATH=\\path\to\lib\grizzly-framework-<?eval ${grizzlyFrameworkVersion}?>.jar:%CLASSPATH%
+C:\>set CLASSPATH=\\path\to\lib\i18n-core-<?eval ${i18nFrameworkVersion}?>.jar:%CLASSPATH%
+C:\>set CLASSPATH=\\path\to\lib\opendj-ldap-sdk-<?eval ${sdkDocTargetVersion}?>.jar:%CLASSPATH%</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="proc-roll-your-own-sdk">
+ <title>To Build Your Own SDK From Source</title>
+ <indexterm>
+ <primary>Installing</primary>
+ <secondary>Build your own</secondary>
+ </indexterm>
+
+ <step>
+ <para>Make sure you have Subversion (<command>svn</command>) and
+ Maven (<command>mvn</command>) installed.</para>
+ </step>
+ <step>
+ <para>Check out the source code.</para>
+ <screen>$ svn co https://svn.forgerock.org/opendj/trunk/opendj3
+...
+Checked out revision <replaceable>XXXX</replaceable>.</screen>
+ </step>
+ <step>
+ <para>Build the modules and install them in the local repository.</para>
+ <screen>$ cd opendj3/
+$ mvn install
+[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Build Order:
+[INFO]
+[INFO] OpenDJ Directory Services Project
+[INFO] OpenDJ LDAP SDK
+[INFO] OpenDJ LDAP Toolkit
+[INFO] OpenDJ LDAP SDK Examples
+[INFO] OpenDJ Commons REST Adapter
+[INFO] OpenDJ Commons REST LDAP Gateway
+[INFO] OpenDJ Server 2.x Adapter
+[INFO]
+ ...
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 2:51.315s
+[INFO] Finished at: Wed Apr 10 14:28:36 CEST 2013
+[INFO] Final Memory: 37M/382M
+[INFO] ------------------------------------------------------------------------</screen>
+ </step>
+ <step>
+ <para>Unzip the tools and libraries included in the file,
+ <filename>opendj3/opendj-ldap-toolkit/target/opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>.zip</filename>.</para>
+ </step>
+ <step>
+ <para>Add the <filename>opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>/bin</filename>
+ (UNIX) or <filename>opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>\bat</filename>
+ (Windows) directory to your PATH.</para>
+ </step>
+ <step>
+ <para>Set your CLASSPATH to include the OpenDJ LDAP SDK library,
+ <filename>opendj-ldap-sdk-<?eval ${sdkDocTargetVersion}?>.jar</filename>,
+ the I18N core library,
+ <filename>i18n-core-<?eval ${i18nFrameworkVersion}?>.jar</filename>, and the
+ Grizzly framework,
+ <filename>grizzly-framework-<?eval ${grizzlyFrameworkVersion}?>.jar</filename>
+ under
+ <filename>opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>/lib/</filename>.</para>
+ </step>
+ </procedure>
+
+ <para>After you install OpenDJ LDAP SDK and configure your environment as
+ described, if you have a directory server running import sample data,
+ and test your configuration with a sample client application.</para>
+
+ <programlisting language="java">import org.forgerock.opendj.ldap.Connection;
+import org.forgerock.opendj.ldap.LDAPConnectionFactory;
+import org.forgerock.opendj.ldap.SearchScope;
+import org.forgerock.opendj.ldap.responses.SearchResultEntry;
+import org.forgerock.opendj.ldap.responses.SearchResultReference;
+import org.forgerock.opendj.ldif.ConnectionEntryReader;
+import org.forgerock.opendj.ldif.LDIFEntryWriter;
+
+//Test.java:
+//Kick the SDK tires, reading Babs Jensen's entry and displaying LDIF.
+//If your LDAP server is not listening on localhost:1389, or if your
+//data are different change the appropriate lines below.
+
+class Test {
+ public static void main(String[] args) {
+
+ // Create an LDIF writer which will write the search results to stdout.
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ Connection connection = null;
+
+ try {
+ // Connect and bind to the server.
+ // CHANGE THIS IF SERVER IS NOT AT localhost:1389.
+ final LDAPConnectionFactory factory =
+ new LDAPConnectionFactory("localhost", 1389);
+
+ connection = factory.getConnection();
+ // CHANGE THIS IF ANONYMOUS SEARCHES ARE NOT ALLOWED.
+ // connection.bind(userName, password);
+
+ // Read the entries and output them as LDIF.
+ // CHANGE THIS IF NO uid=bjensen,ou=people,dc=example,dc=com EXISTS.
+ final ConnectionEntryReader reader =
+ connection.search("dc=example,dc=com",
+ SearchScope.WHOLE_SUBTREE, "(uid=bjensen)", "*");
+ while (reader.hasNext()) {
+ if (reader.isEntry()) {
+ // Got an entry.
+ final SearchResultEntry entry = reader.readEntry();
+ writer.writeComment("Search result entry: "
+ + entry.getName().toString());
+ writer.writeEntry(entry);
+ } else {
+ // Got a continuation reference.
+ final SearchResultReference ref = reader.readReference();
+ writer.writeComment("Search result reference: "
+ + ref.getURIs().toString());
+ }
+ }
+ writer.flush();
+ } catch (final Exception e) {
+ // Handle exceptions...
+ System.err.println(e.getMessage());
+ } finally {
+ if (connection != null) {
+ connection.close();
+ }
+ }
+ }
+}
+</programlisting>
+
+ <para>If all goes well, <filename>Test.java</filename> compiles without
+ errors. The test program displays Babs Jensen's entry in LDIF.</para>
+
+ <screen>$ javac Test.java
+$ java Test
+# Search result entry: uid=bjensen,ou=People,dc=example,dc=com
+dn: uid=bjensen,ou=People,dc=example,dc=com
+givenName: Barbara
+objectClass: person
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: top
+uid: bjensen
+cn: Barbara Jensen
+cn: Babs Jensen
+sn: Jensen
+telephoneNumber: +1 408 555 1862
+roomNumber: 0209
+ou: Product Development
+ou: People
+l: Cupertino
+mail: bjensen@example.com
+facsimileTelephoneNumber: +1 408 555 1992</screen>
+ </section>
+
+ <section xml:id="opendj-ldap-sdk-examples">
+ <title>Accessing Example Java Code</title>
+ <indexterm>
+ <primary>Examples</primary>
+ <secondary>Java</secondary>
+ </indexterm>
+
+ <para>A number of OpenDJ LDAP SDK examples are available online on the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ community site</link>. There you find samples
+ whose excerpts are shown in this guide.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-getting-directory-info.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
new file mode 100644
index 0000000..edc9b06
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-getting-directory-info.xml
@@ -0,0 +1,244 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-getting-directory-info'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Getting Information About the Directory Service</title>
+
+ <para>LDAP directories expose what their capabilities through the root
+ DSE. They also expose their schema definitions, which define the sort of
+ entries and attributes can be stored in a directory, over protocol. OpenDJ
+ SDK allows you to look up that information in your client application.</para>
+
+ <section xml:id="read-root-dse">
+ <title>Reading Root DSEs</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Root DSE</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Checking supported features</secondary>
+ </indexterm>
+
+ <para>The directory entry with distinguished name <literal>""</literal> (empty
+ string) is called the <firstterm>root DSE</firstterm>. DSE stands for
+ DSA-Specific Entry. DSA stands for Directory Server Agent, a single
+ directory server.</para>
+
+ <para>The root DSE serves to expose information over LDAP about what the
+ directory server supports in terms of LDAP controls, auth password schemes,
+ SASL mechanisms, LDAP protocol versions, naming contexts, features, LDAP
+ extended operations, and so forth. The root DSE holds all the information
+ as values of LDAP attributes. OpenDJ defines these attributes as operational.
+ In other words, OpenDJ only returns the attributes if you either request
+ them specifically, or request all operational attributes.</para>
+
+ <para>To access the list of what an OpenDJ server supports, for example,
+ get all operational attributes from the root DSE entry as in the following
+ excerpt.</para>
+
+ <programlisting language="java">
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(
+ host, port);
+Connection connection = null;
+
+try
+{
+ connection = factory.getConnection();
+
+ // Perform an anonymous search on the root DSE.
+ final SearchResultEntry entry = connection.searchSingleEntry(
+ "", // DN is "" for root DSE.
+ SearchScope.BASE_OBJECT, // Read only the root DSE.
+ "objectclass=*", // Every object matches this filter.
+ "+"); // Return all operational attributes.
+
+ final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
+ writer.writeComment("Root DSE for LDAP server at " + host + ":" + port);
+ if (entry != null) writer.writeEntry(entry);
+ writer.flush();
+}</programlisting>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/GetInfo.html"
+ xlink:show="new">GetInfo.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+
+ <para>Notice that by default you can access the root DSE after authenticating
+ anonymously. When you look at the entry in LDIF, you see that supported
+ capabilities are generally identified by object identifier (OID).</para>
+
+ <screen># Root DSE for LDAP server at localhost:1389
+dn:
+supportedControl: 1.2.826.0.1.3344810.2.3
+supportedControl: 1.2.840.113556.1.4.1413
+supportedControl: 1.2.840.113556.1.4.319
+supportedControl: 1.2.840.113556.1.4.473
+supportedControl: 1.2.840.113556.1.4.805
+supportedControl: 1.3.6.1.1.12
+supportedControl: 1.3.6.1.1.13.1
+supportedControl: 1.3.6.1.1.13.2
+supportedControl: 1.3.6.1.4.1.26027.1.5.2
+supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1
+supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2
+supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8
+supportedControl: 1.3.6.1.4.1.4203.1.10.1
+supportedControl: 1.3.6.1.4.1.4203.1.10.2
+supportedControl: 1.3.6.1.4.1.7628.5.101.1
+supportedControl: 2.16.840.1.113730.3.4.12
+supportedControl: 2.16.840.1.113730.3.4.16
+supportedControl: 2.16.840.1.113730.3.4.17
+supportedControl: 2.16.840.1.113730.3.4.18
+supportedControl: 2.16.840.1.113730.3.4.19
+supportedControl: 2.16.840.1.113730.3.4.2
+supportedControl: 2.16.840.1.113730.3.4.3
+supportedControl: 2.16.840.1.113730.3.4.4
+supportedControl: 2.16.840.1.113730.3.4.5
+supportedControl: 2.16.840.1.113730.3.4.9
+supportedAuthPasswordSchemes: MD5
+supportedAuthPasswordSchemes: SHA1
+supportedAuthPasswordSchemes: SHA256
+supportedAuthPasswordSchemes: SHA512
+supportedAuthPasswordSchemes: SHA384
+supportedSASLMechanisms: PLAIN
+supportedSASLMechanisms: EXTERNAL
+supportedSASLMechanisms: DIGEST-MD5
+supportedSASLMechanisms: CRAM-MD5
+supportedLDAPVersion: 2
+supportedLDAPVersion: 3
+etag: 00000000e9155ba0
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
+supportedFeatures: 1.3.6.1.1.14
+supportedFeatures: 1.3.6.1.4.1.4203.1.5.1
+supportedFeatures: 1.3.6.1.4.1.4203.1.5.2
+supportedFeatures: 1.3.6.1.4.1.4203.1.5.3
+subschemaSubentry: cn=schema
+changelog: cn=changelog
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_RC4_128_SHA
+supportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_RC4_128_SHA
+supportedTLSCiphers: TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
+supportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
+supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
+ds-private-naming-contexts: cn=admin data
+ds-private-naming-contexts: cn=ads-truststore
+ds-private-naming-contexts: cn=backups
+ds-private-naming-contexts: cn=config
+ds-private-naming-contexts: cn=monitor
+ds-private-naming-contexts: cn=schema
+ds-private-naming-contexts: cn=tasks
+ds-private-naming-contexts: dc=replicationChanges
+supportedTLSProtocols: SSLv2Hello
+supportedTLSProtocols: SSLv3
+supportedTLSProtocols: TLSv1
+supportedTLSProtocols: TLSv1.1
+supportedTLSProtocols: TLSv1.2
+numSubordinates: 1
+namingContexts: dc=example,dc=com
+structuralObjectClass: ds-root-dse
+lastExternalChangelogCookie:
+lastChangeNumber: 0
+firstChangeNumber: 0
+supportedExtension: 1.3.6.1.1.8
+supportedExtension: 1.3.6.1.4.1.26027.1.6.1
+supportedExtension: 1.3.6.1.4.1.26027.1.6.2
+supportedExtension: 1.3.6.1.4.1.26027.1.6.3
+supportedExtension: 1.3.6.1.4.1.4203.1.11.1
+supportedExtension: 1.3.6.1.4.1.1466.20037
+supportedExtension: 1.3.6.1.4.1.4203.1.11.3
+vendorName: ForgeRock AS.
+vendorVersion: OpenDJ 2.5.0
+hasSubordinates: true
+entryDN:
+entryUUID: d41d8cd9-8f00-3204-a980-0998ecf8427e
+</screen>
+
+ <para>Three key pieces of information in the entry shown above are attribute
+ values for <literal>namingContexts</literal> (showing the base DNs under
+ which your application can look for user data),
+ <literal>subschemaSubentry</literal> (indicating where the LDAP schema are
+ stored), and <literal>supportedLDAPVersion</literal> (with OpenDJ seen to
+ support both LDAPv2 and LDAPv3).</para>
+ </section>
+
+ <section xml:id="check-ldapv3-support">
+ <title>Checking For LDAPv3 Support</title>
+
+ <para>As shown in the previous section, you can check that the root DSE
+ attribute <literal>supportedLDAPVersion</literal> has a value of 3.</para>
+
+ <para>LDAPv3 has been available since 1997. Client applications built with
+ OpenDJ SDK use LDAPv3.</para>
+ </section>
+
+ <section xml:id="get-schema-information">
+ <title>Getting Schema Information</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Schema</secondary>
+ </indexterm>
+
+ <para>The root DSE attribute <literal>subschemaSubentry</literal> shows
+ the DN of the entry holding LDAP schema definitions. LDAP schema defines the
+ object classes, attributes types, attribute value syntaxes, matching rules
+ and so on that constrain entries held by the LDAP server.</para>
+
+ <para>The <literal>org.forgerock.opendj.ldap.schema</literal> package
+ is devoted to constructing and querying LDAP schemas. The
+ <literal>Schema</literal> class for example lets you
+ <literal>readSchemaForEntry()</literal> to get the relevant schema from the
+ subschema subentry, and then <literal>validateEntry()</literal> to check
+ an entry your application has constructed before sending the entry to the
+ server.</para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-i18n.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-i18n.xml
new file mode 100644
index 0000000..e2a8802
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-i18n.xml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-i18n'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Internationalizing Applications</title>
+ <indexterm>
+ <primary>Internationalization</primary>
+ </indexterm>
+
+ <para>When you internationalize your application — adapting your
+ application for use in different languages and regions — how much you
+ do depends on what you must later localize. Directory servers often support
+ localized user data. OpenDJ directory server supports use of the locales
+ provided by your Java installation, and also supports many language subtypes,
+ for example.</para>
+
+ <para>Therefore if your application is not end user facing and the
+ administrators managing your application all use the same language as you do,
+ you might be content to use language subtypes in LDAP filters, as described
+ in the section on <link xlink:href="dev-guide#about-filters"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Working With
+ Search Filters</citetitle></link>.</para>
+
+ <para>For end user facing applications where you must return localized
+ messages, and for applications where administrators need localized log
+ messages, you can use the <link xlink:show="new"
+ xlink:href="http://commons.forgerock.org/i18n-framework/">ForgeRock I18N
+ Framework</link>.</para>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-ldif.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-ldif.xml
new file mode 100644
index 0000000..7731c83
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-ldif.xml
@@ -0,0 +1,211 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-ldif'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Working With LDIF</title>
+
+ <para>OpenDJ LDAP SDK provides capabilities for working with <link
+ xlink:show="new" xlink:href="http://tools.ietf.org/html/rfc2849">LDAP Data
+ Interchange Format</link> (LDIF) content. This chapter demonstrates how to use
+ those capabilities.</para>
+
+ <section xml:id="about-ldif">
+ <title>About LDIF</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ </indexterm>
+
+ <para>LDAP Data Interchange Format provides a mechanism to represent
+ directory data in text format. LDIF data is typically used to initialize
+ directory databases, but also may be used to move data between different
+ directories that cannot replicate directly, or even as an alternative
+ backup format. When you read OpenDJ's external change log, you get changes
+ expressed in LDIF.</para>
+
+ <para>LDIF uses base64 encoding to store values that are not safe for use in
+ a text file, including values that represent binary objects like JPEG photos
+ and X509 certificates, but also values that hold bits of LDIF, and values that
+ end in white space. The description in the following LDIF holds, "Space at
+ the end of the line " for example. Notice that continuation lines shown in
+ the excerpt of the JPEG photo value start with spaces.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
+description:: U3BhY2UgYXQgdGhlIGVuZCBvZiB0aGUgbGluZSA=
+uid: bjensen
+jpegPhoto:: /9j/4AAQSkZJRgABAQEASABIAAD/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAABt
+ bnRyUkdCIFhZWiAHzgACAAkABgAxAABhY3NwTVNGVAAAAABJRUMgc1JHQgAAAAAAAAAAAAAAAAAA9tY
+ AAQAAAADTLUhQICAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB
+ ...
+ Pxv8A8lh8J/8AXUfzr1qP/WSfWlzPlsZSi3VHqMA/WinUVB0n/9k=
+facsimileTelephoneNumber: +1 408 555 1992
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+givenName: Barbara
+cn: Barbara Jensen
+cn: Babs Jensen
+telephoneNumber: +1 408 555 1862
+sn: Jensen
+roomNumber: 0209
+homeDirectory: /home/bjensen
+ou: Product Development
+ou: People
+l: Cupertino
+mail: bjensen@example.com
+uidNumber: 1076
+gidNumber: 1000
+</programlisting>
+
+ <para>LDIF can serve to describe not only entries with their attributes but
+ also changes to entries. For example, you can express adding a JPEG photo
+ to Babs Jensen's entry as follows.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=people,dc=example,dc=com
+changetype: modify
+add: jpegPhoto
+jpegPhoto:< file:///tmp/opendj-logo.jpg
+</programlisting>
+
+ <para>You can also replace and delete attribute values. Notice the dash,
+ <literal>-</literal>, used to separate changes.</para>
+
+ <programlisting language="ldif">dn: uid=bjensen,ou=people,dc=example,dc=com
+changetype: modify
+replace: roomNumber
+roomNumber: 1234
+-
+delete: description
+-
+delete: jpegPhoto
+</programlisting>
+
+ <para>LDIF also allows <literal>changetype</literal>s of
+ <literal>add</literal> to create entries, <literal>delete</literal> to
+ remove entries, and <literal>modrdn</literal> to rename entries.</para>
+
+ <para>For more examples, see the LDIF specification, <link xlink:show="new"
+ xlink:href="http://tools.ietf.org/html/rfc2849">RFC 2849</link>.</para>
+ </section>
+
+ <section xml:id="reading-ldif">
+ <title>Reading LDIF</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Reading</secondary>
+ </indexterm>
+
+ <para>OpenDJ LDAP SDK provides <literal>ChangeRecordReader</literal>s to
+ read requests to modify directory data, and <literal>EntryReader</literal>s
+ to read entries from a data source such as a file or other source. Both of
+ these are interfaces.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>ConnectionEntryReader</literal> class offers methods
+ to iterate through entries and references returned by a search.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <literal>LDIFChangeRecordReader</literal> and
+ <literal>LDIFEntryReader</literal> classes offer methods to handle LDIF as
+ strings or from an input stream.</para>
+
+ <para>Both classes give you some methods to filter content. You can also
+ use the <literal>LDIF</literal> static methods to filter content.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following short excerpt shows a reader that takes LDIF change
+ records from standard input.</para>
+
+ <programlisting language="java">InputStream ldif = System.in;
+final LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);</programlisting>
+ </section>
+
+ <section xml:id="writing-ldif">
+ <title>Writing LDIF</title>
+ <indexterm>
+ <primary>LDIF</primary>
+ <secondary>Writing</secondary>
+ </indexterm>
+
+ <para><literal>ChangeRecordWriter</literal>s let you write requests to modify
+ directory data, whereas <literal>EntryWriter</literal>s let you write entries
+ to a file or an output stream. Both of these are interfaces.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <literal>ConnectionChangeRecordWriter</literal> and
+ <literal>ConnectionEntryWriter</literal> classes let you write directly
+ to a connection to the directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <literal>LDIFChangeRecordWriter</literal> and
+ <literal>LDIFEntryWriter</literal> classes let you write to a file or other
+ output stream. Both classes offer methods to filter content.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following excerpt shows a writer pushing LDIF changes to a
+ directory server.</para>
+
+ <programlisting language="java"
+ >final LDIFChangeRecordReader reader = new LDIFChangeRecordReader(ldif);
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+
+try {
+ connection = factory.getConnection();
+ connection.bind(userDN, password.toCharArray());
+
+ final ConnectionChangeRecordWriter writer =
+ new ConnectionChangeRecordWriter(connection);
+ while (reader.hasNext()) {
+ ChangeRecord changeRecord = reader.readChangeRecord();
+ writer.writeChangeRecord(changeRecord);
+ }
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} catch (final IOException e) {
+ System.err.println(e.getMessage());
+ System.exit(ResultCode.CLIENT_SIDE_LOCAL_ERROR.intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-reading.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-reading.xml
new file mode 100644
index 0000000..badc6b8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-reading.xml
@@ -0,0 +1,553 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-reading'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Searching & Comparing Directory Data</title>
+
+ <para>Traditionally directories excel at serving read requests. This chapter
+ covers the read (search and compare) capabilities that OpenDJ LDAP Java SDK
+ provides. The data used in examples here is <link xlink:show="new"
+ xlink:href="http://opendj.forgerock.org/Example.ldif">available
+ online</link>.</para>
+
+ <section xml:id="about-searching">
+ <title>About Searching</title>
+ <indexterm>
+ <primary>Searches</primary>
+ </indexterm>
+
+ <itemizedlist>
+ <para>An LDAP search looks up entries based on the following
+ parameters.</para>
+ <listitem>
+ <para>A <firstterm>filter</firstterm> that indicates which attribute values
+ to match</para>
+ </listitem>
+ <listitem>
+ <para>A <firstterm>base DN</firstterm> that specifies where in the
+ directory information tree to look for matches</para>
+ </listitem>
+ <listitem>
+ <para>A <firstterm>scope</firstterm> that defines how far to go under
+ the base DN</para>
+ </listitem>
+ <listitem>
+ <para>A list of attributes to fetch for an entry when a match is
+ found</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For example, imagine you must write an application where users login
+ using their email address and a password. After the user logs in, your
+ application displays the user's full name so it is obvious who is logged in.
+ Your application is supposed to go to the user directory both for
+ authentication, and also to read user profile information. You are told the
+ user directory stores user profile entries under base DN
+ <literal>ou=People,dc=example,dc=com</literal>, that email addresses are
+ stored on the standard <literal>mail</literal> attribute, and full names are
+ store on the standard <literal>cn</literal> attribute.</para>
+
+ <para>You figure out how to authenticate from the chapter on <link
+ xlink:href="dev-guide#chap-authenticating"
+ xlink:role="http://docbook.org/xlink/role/olink">authentication</link>,
+ in which you learn you need a bind DN and a password to do simple
+ authentication. But how do you find the bind DN given the email? How do you
+ get the full name?</para>
+
+ <para>The answer to both questions is that you do an LDAP search for the
+ user's entry, which has the DN that you use to bind, and you have the server
+ fetch the <literal>cn</literal> attribute in the results. Your search uses
+ the following parameters.</para>
+ <itemizedlist>
+ <listitem>
+ <para>The filter is
+ <literal>(mail=<replaceable>emailAddress</replaceable>)</literal>, where
+ <replaceable>emailAddress</replaceable> is the email address the user
+ provided.</para>
+ </listitem>
+ <listitem>
+ <para>The base DN is the one given to you,
+ <literal>ou=People,dc=example,dc=com</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>For the scope, you figure the user entry is somewhere under the base
+ DN, so you opt to search the whole subtree.</para>
+ </listitem>
+ <listitem>
+ <para>The attribute to fetch is <literal>cn</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following code excerpt demonstrates how this might be done in a
+ minimal command-line program.</para>
+
+ <programlisting language="java">// Prompt for mail and password.
+Console c = System.console();
+if (c == null) {
+ System.err.println("No console.");
+ System.exit(1);
+}
+
+String mail = c.readLine("Email address: ");
+char[] password = c.readPassword("Password: ");
+
+// Search using mail address, and then bind with the DN and password.
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(host,
+ port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+
+ // No explicit bind yet so we remain anonymous for now.
+ SearchResultEntry entry = connection.searchSingleEntry(baseDN,
+ SearchScope.WHOLE_SUBTREE, "(mail=" + mail + ")", "cn");
+ DN bindDN = entry.getName();
+ connection.bind(bindDN.toString(), password);
+
+ String cn = entry.getAttribute("cn").firstValueAsString();
+ System.out.println("Hello, " + cn + "!");
+} catch (final ErrorResultException e) {
+ System.err.println("Failed to bind.");
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SearchBind.html"
+ xlink:show="new">SearchBind.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+
+ <section xml:id="basedn-and-scope">
+ <title>Setting Search Base & Scope</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Base</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Scope</secondary>
+ </indexterm>
+
+ <para>Directory servers organize entries somewhat like a file system.
+ Directory data is often depicted as an upside-down tree.</para>
+
+ <mediaobject xml:id="figure-ldap-tree">
+ <alt>Directory data is often depicted as an upside-down tree.</alt>
+ <imageobject>
+ <imagedata fileref="images/ldap-tree.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>This figure shows three levels, the base DN for the suffix, a couple
+ of organizational units, and three user entries.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>In the figure shown above, entries are represented by the relevant
+ parts of their DNs. The entry with DN <literal>dc=example,dc=com</literal>
+ is the base entry for a suffix. Under the base entry, you see two
+ organizational units, one for people, <literal>ou=People</literal>, the other
+ for groups, <literal>ou=Groups</literal>. The entries for people include
+ those of Babs Jensen, Kirsten Vaughan, and Sam Carter.</para>
+
+ <para>When you are searching for a person's entry somewhere under
+ <literal>dc=example,dc=com</literal>, you can start from
+ <literal>dc=example,dc=com</literal>, from
+ <literal>ou=People,dc=example,dc=com</literal>, or if you have enough
+ information to pinpoint the user entry and only want to look up another
+ attribute value for example, then directly from the entry such as
+ <literal>cn=Babs Jensen,ou=People,dc=example,dc=com</literal>. The DN of
+ the entry where you choose to start the search is the base DN for the
+ search.</para>
+
+ <itemizedlist>
+ <para>When searching, you also define the scope. Scope defines what entries
+ the server considers when checking for entries that match your search.</para>
+ <listitem>
+ <para>For <literal>SearchScope.BASE_OBJECT</literal> the server considers
+ only the base entry.</para>
+ <para>This is the scope you use if you know the full DN of the object
+ that interests you. For example, if your base DN points to Babs Jensen's
+ entry, <literal>cn=Babs Jensen,ou=People,dc=example,dc=com</literal>, and
+ you want to read some of Babs's attributes, you would set scope to
+ <literal>SearchScope.BASE_OBJECT</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>For <literal>SearchScope.SINGLE_LEVEL</literal> the server considers
+ all entries directly below the base entry.</para>
+ <para>You use this scope if for example you want to discover organizational
+ units under <literal>dc=example,dc=com</literal>, or if you want to find
+ people's entries and you know they are immediately under
+ <literal>ou=People,dc=example,dc=com</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>For <literal>SearchScope.SUBORDINATES</literal> the server considers
+ all entries below the base entry.</para>
+ <para>This scope can be useful if you know that the base DN for your search
+ is an entry that you do not want to match.</para>
+ </listitem>
+ <listitem>
+ <para>For <literal>SearchScope.WHOLE_SUBTREE</literal> (default) the server
+ considers the base entry and all entries below.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In addition to a base DN and scope, a search request also calls for a
+ search filter.</para>
+ </section>
+
+ <section xml:id="about-filters">
+ <title>Working With Search Filters</title>
+ <indexterm>
+ <primary>Filters</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Filters</secondary>
+ </indexterm>
+
+ <para>When you look someone up in the telephone directory, you use the value
+ of one attribute of a person's entry (last name), to recover the person's
+ directory entry, which has other attributes (phone number, address). LDAP
+ works the same way. In LDAP, search requests identify both the scope of the
+ directory entries to consider (for example, all people or all organizations),
+ and also the entries to retrieve based on some attribute value (for example,
+ surname, mail address, phone number, or something else). The way you express
+ the attribute value(s) to match is by using a search filter.</para>
+
+ <para>LDAP search filters define what entries actually match your request.
+ For example, the following simple equality filter says, "Match all entries
+ that have a surname attribute (sn) value equivalent to Jensen."</para>
+
+ <literallayout class="monospaced">(sn=Jensen)</literallayout>
+
+ <para>When you pass the directory server this filter as part of your search
+ request, the directory server checks the entries in scope for your search to
+ see whether they match.<footnote><para>In fact, the directory server probably
+ checks an index first, and might not even accept search requests unless it
+ can use indexes to match your filter rather than checking all entries in
+ scope.</para></footnote> If the directory server finds entries that match,
+ it returns those entries as it finds them.</para>
+
+ <para>The example, <literal>(sn=Jensen)</literal>, shows a string
+ representation of the search filter. The OpenDJ LDAP SDK lets you express
+ your filters as strings, or as <literal>Filter</literal> objects. In both
+ cases, the SDK translates the strings and objects into the binary
+ representation sent to the server over the network.</para>
+
+ <para>Equality is just one of the types of comparisons available in LDAP
+ filters. Comparison operators include the following.</para>
+
+ <xinclude:include href="../shared/table-filter-operators.xml" />
+
+ <para>When taking user input, take care to protect against users providing
+ input that has unintended consequences. OpenDJ SDK offers several Filter
+ methods to help you. First, you can use strongly typed construction methods
+ such as <literal>Filter.equality()</literal>.</para>
+
+ <programlisting language="java">String userInput = getUserInput();
+Filter filter = Filter.equality("cn", userInput);
+
+// Invoking filter.toString() with input of "*" results in a filter
+// string "(cn=\2A)".</programlisting>
+
+ <para>You can also let the SDK escape user input by using a template with
+ <literal>Filter.format()</literal> as in the following example.</para>
+
+ <programlisting language="java">String template = "(|(cn=%s)(uid=user.%s))";
+String[] userInput = getUserInput();
+Filter filter = Filter.format(template, userInput[0], userInput[1]);</programlisting>
+
+ <para>Finally, you can explicitly escape user input with
+ <literal>Filter.escapeAssertionValue()</literal>.</para>
+
+ <programlisting language="java">String baseDN = "ou=people,dc=example,dc=com";
+String userInput = getUserInput();
+
+// Filter.escapeAssertionValue() transforms user input of "*" to "\2A".
+SearchRequest request = Requests.newSearchRequest(
+ baseDN, SearchScope.WHOLE_SUBTREE,
+ "(cn=" + Filter.escapeAssertionValue(userInput) + "*)", "cn", "mail");</programlisting>
+ </section>
+
+ <section xml:id="send-search-request">
+ <title>Sending a Search Request</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Synchronous</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ </indexterm>
+
+ <para>As shown in the following excerpt with a synchronous connection, you
+ get a <literal>Connection</literal> to the directory server from an
+ <literal>LDAPConnectionFactory</literal>.</para>
+
+ <programlisting language="java"
+>final LDAPConnectionFactory factory = new LDAPConnectionFactory(host,
+ port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+
+ // Do something with the connection...
+} catch (Exception e) {
+ // Handle exceptions...
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+
+ <para>The <literal>Connection</literal> gives you <literal>search()</literal>
+ methods that either take parameters in the style of the
+ <command>ldapsearch</command> command, or that take a
+ <literal>SearchRequest</literal> object. If you are sure that the search only
+ returns a single entry, you can read the entry with the
+ <literal>searchSingleEntry()</literal> methods. If you have the distinguished
+ name, you can use <literal>readEntry()</literal> directly.</para>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Search.html"
+ xlink:show="new">Search.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+
+ <section xml:id="get-search-results">
+ <title>Getting Search Results</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+
+ <para>Depending on the method you use to search, you handle results in
+ different ways.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You can get a <literal>ConnectionEntryReader</literal>, and iterate
+ over the reader to access individual search results.</para>
+
+ <programlisting language="java">Connection connection = ...;
+ConnectionEntryReader reader = connection.search("dc=example,dc=com",
+ SearchScope.WHOLE_SUBTREE, "(objectClass=person)");
+try
+{
+ while (reader.hasNext())
+ {
+ if (reader.isEntry())
+ {
+ SearchResultEntry entry = reader.readEntry();
+
+ // Handle entry...
+ }
+ else
+ {
+ SearchResultReference ref = reader.readReference();
+
+ // Handle continuation reference...
+ }
+ }
+}
+catch (IOException e)
+{
+ // Handle exceptions...
+}
+finally
+{
+ reader.close();
+}</programlisting>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Search.html"
+ xlink:show="new">Search.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can pass in a collection of <literal>SearchResultEntry</literal>s
+ (and optionally a collection of <literal>SearchResultReference</literal>s)
+ to which the SDK adds the results. For this to work, you need enough
+ memory to hold everything the search returns.</para>
+ </listitem>
+
+ <listitem>
+ <para>You can pass in a <literal>SearchResultHandler</literal> to manage
+ results.</para>
+ </listitem>
+
+ <listitem>
+ <para>With <literal>searchSingleEntry()</literal> and
+ <literal>readEntry()</literal>, you can get a single
+ <literal>SearchResultEntry</literal> with methods to access the entry
+ content.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="handle-entry-attributes">
+ <title>Working With Entry Attributes</title>
+ <indexterm>
+ <primary>Attributes</primary>
+ </indexterm>
+
+ <para>When you get an entry object, chances are you want to handle attribute
+ values as objects. The OpenDJ LDAP SDK provides the
+ <literal>Entry.parseAttribute()</literal> method and an
+ <literal>AttributeParser</literal> with methods for a variety of attribute
+ value types. You can use these methods to get attribute values as
+ objects.</para>
+
+ <programlisting language="java">
+// Use Kirsten Vaughan's credentials and her entry.
+String name = "uid=kvaughan,ou=People,dc=example,dc=com";
+char[] password = "bribery".toCharArray();
+connection.bind(name, password);
+
+// Make sure we have a timestamp to play with.
+updateEntry(connection, name, "description");
+
+// Read Kirsten's entry.
+final SearchResultEntry entry = connection.readEntry(name,
+ "cn", "objectClass", "hasSubordinates", "numSubordinates",
+ "isMemberOf", "modifyTimestamp");
+
+// Get the entry DN and some attribute values as objects.
+DN dn = entry.getName();
+
+Set<String> cn = entry.parseAttribute("cn").asSetOfString("");
+Set<AttributeDescription> objectClasses =
+ entry.parseAttribute("objectClass").asSetOfAttributeDescription();
+boolean hasChildren = entry.parseAttribute("hasSubordinates").asBoolean();
+int numChildren = entry.parseAttribute("numSubordinates").asInteger(0);
+Set<DN> groups = entry
+ .parseAttribute("isMemberOf")
+ .usingSchema(Schema.getDefaultSchema()).asSetOfDN();
+Calendar timestamp = entry
+ .parseAttribute("modifyTimestamp")
+ .asGeneralizedTime().toCalendar();
+
+// Do something with the objects.
+// ...
+</programlisting>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ParseAttributes.html"
+ xlink:show="new">ParseAttributes.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+
+ <section xml:id="handle-ldap-urls">
+ <title>Working With LDAP URLs</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>URLs</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
+
+ <para>LDAP URLs express search requests in URL form. In the directory data
+ you can find them used as <literal>memberURL</literal>
+ attribute values for dynamic groups, for example. The following URL from the
+ configuration for the administrative backend lets the directory server build
+ a dynamic group of administrator entries that are children of
+ <literal>cn=Administrators,cn=admin data</literal>.</para>
+
+ <literallayout class="monospaced"
+ >ldap:///cn=Administrators,cn=admin data??one?(objectclass=*)</literallayout>
+
+ <para>The static method <literal>LDAPUrl.valueOf()</literal> takes an LDAP
+ URL string and returns an <literal>LDAPUrl</literal> object. You can then use
+ the <literal>LDAPUrl.asSearchRequest()</literal> method to get the
+ <literal>SearchRequest</literal> that you pass to one of the search methods
+ for the connection.</para>
+ </section>
+
+ <section xml:id="sort-search-results">
+ <title>Sorting Search Results</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Sorting</primary>
+ </indexterm>
+
+ <para>If you want to sort search results in your client application, then
+ make sure you have enough memory in the JVM to hold the results of the search,
+ and use one of the search methods that lets you pass in a collection of
+ <literal>SearchResultEntry</literal>s. After the collection is populated with
+ the results, you can sort them.</para>
+
+ <para>If you are on good terms with your directory administrator, you can
+ perhaps use a server-side sort control. The server-side sort request control
+ asks the server to sort the results before returning them, and so is a
+ memory intensive operation on the directory server. You set up the control
+ using <literal>ServerSideSortRequestControl.newControl()</literal>. You get
+ the control into your search by building a search request to pass to the
+ search method, using <literal>SearchRequest.addControl()</literal> to attach
+ the control before passing in the request.</para>
+
+ <para>If your application needs to scroll through search results a page at
+ a time, work with your directory administrator to set up the virtual list
+ view indexes that facilitate scrolling through results.</para>
+ </section>
+
+ <section xml:id="about-comparisons">
+ <title>About Comparing</title>
+ <indexterm>
+ <primary>Comparisons</primary>
+ </indexterm>
+
+ <para>You use the LDAP compare operation to make an assertion about an
+ attribute value on an entry. Unlike the search operation, you must know
+ the distinguished name of the entry in advance to request a compare operation.
+ You also specify the attribute type name and the value to compare to the
+ values stored on the entry.</para>
+
+ <para><literal>Connection</literal> has a choice of compare methods,
+ depending on how you set up the operation.</para>
+
+ <para>Check the <literal>ResultCode</literal> from
+ <literal>CompareResult.getResultCode()</literal> for
+ <literal>ResultCode.COMPARE_TRUE</literal> or
+ <literal>ResultCode.COMPARE_FALSE</literal>.</para>
+ </section>
+</chapter>
\ No newline at end of file
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-simple-proxy.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-simple-proxy.xml
new file mode 100644
index 0000000..7dd0388
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-simple-proxy.xml
@@ -0,0 +1,253 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-simple-proxy'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Writing a Simple LDAP Proxy</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Proxy</secondary>
+ </indexterm>
+
+ <para>The OpenDJ LDAP SDK <link xlink:show="new"
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Proxy.html"
+ >example Proxy</link> demonstrates a simple LDAP proxy that forwards requests
+ to one or more remote directory servers. Although the implementation is
+ intended as an example, it does demonstrate use of the asynchronous API,
+ load balancing, and connection pooling.</para>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Asynchronous</secondary>
+ </indexterm>
+
+ <para>The Proxy example sets up connections pools with load balancing to the
+ directory servers. It passes the connection factories to a
+ <literal>ProxyBackend</literal> that handles the requests passed back
+ to the directory servers. It also sets up an LDAP listener to receive incoming
+ connections from clients of the Proxy.</para>
+
+ <para>The <literal>ProxyBackend</literal> uses separate connection factories,
+ one for bind operations, the other for other operations. It uses the proxied
+ authorization control to ensure operations are performed using the bind
+ identity for the operation.</para>
+
+ <para>The <literal>ProxyBackend</literal>'s function is to handle each client
+ request, encapsulating the result handlers that allow it to deal with each
+ basic operation. It authenticates to the directory server to check incoming
+ credentials, and adds the proxied authorization control to requests other than
+ binds. The <literal>ProxyBackend</literal> handles all operations using
+ asynchronous connections and methods.</para>
+
+ <section xml:id="connection-pooling">
+ <title>Connection Pooling</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Pooling</secondary>
+ </indexterm>
+
+ <para>As shown in the Proxy example, the
+ <literal>Connections.newFixedConnectionPool()</literal> returns a connection
+ pool of the maximum size you specify.</para>
+
+ <programlisting language="java"
+>final List<ConnectionFactory> factories = new LinkedList<~>();
+
+factories.add(Connections.newFixedConnectionPool(Connections
+ .newAuthenticatedConnectionFactory(Connections
+ .newHeartBeatConnectionFactory(new LDAPConnectionFactory(
+ remoteAddress, remotePort)),
+ Requests.newSimpleBindRequest(proxyDN,
+ proxyPassword.toCharArray())),
+ Integer.MAX_VALUE));</programlisting>
+
+ <para>Connections are returned to the pool when you <literal>close()</literal>
+ them. Notice that <literal>Connections</literal> also provides methods to
+ return <literal>ConnectionFactory</literal>s with a heart beat check on
+ connections provided by the factory, and connection factories that
+ authenticate connections before returning them.</para>
+
+ <para>Connections in the pool are intended for reuse. The Proxy gets an
+ authenticated connection, which is a connection where the OpenDJ LDAP
+ SDK passes a bind request immediately when getting the connection. The Proxy
+ then uses proxied authorization to handle the identity from the client
+ requesting the operation. As a rule, either handle binds separately and use
+ proxied authorization as in the Proxy example, or else make sure that the
+ first operation on a connection retrieved from the pool is a bind that
+ correctly authenticates the user currently served by the connection.</para>
+
+ <para>When you <literal>close()</literal> a connection from the pool, the
+ OpenDJ LDAP SDK does not perform an <literal>unbind()</literal>. This is why
+ you must be careful about how you manage authentication on connections from a
+ pool.</para>
+ </section>
+
+ <section xml:id="load-balancing-and-failover">
+ <title>Load Balancing & Failover</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Load balancing</secondary>
+ </indexterm>
+
+ <para>The <literal>Connections.newLoadBalancer()</literal> method returns a
+ load balancer based on the algorithm you choose. Algorithms include both
+ round robin for equitably sharing load across local directory servers, and
+ also failover usually used for switching automatically from an unresponsive
+ server group to an alternative server group. The algorithms take collections
+ of connection factories, such as those that you set up for connection
+ pooling.</para>
+
+ <para>The following excerpt shows how to set up round robin load balancing
+ across directory servers.</para>
+
+ <programlisting language="java"
+ >final List<ConnectionFactory> factories = new LinkedList<ConnectionFactory>();
+
+// Set up a ConnectionFactory for each directory server in the pool as shown in
+// the previous example, and then set up a load balancer.
+
+final RoundRobinLoadBalancingAlgorithm algorithm =
+ new RoundRobinLoadBalancingAlgorithm(factories);
+
+final ConnectionFactory factory = Connections.newLoadBalancer(algorithm);</programlisting>
+
+ <para>With multiple pools of directory servers, for example in a deployment
+ across multiple data centers, also use fail over load balancing. Fail over
+ load balancing directs all requests to the first (preferred) pool of servers
+ until problems are encountered with the connections to that pool. Then it
+ fails over to the next pool in the list. Therefore in each data center you
+ can set up round robin load balancing, and then set up fail over load
+ balancing across data centers.</para>
+
+ <programlisting language="java"
+ >// localFactory: ConnectionFactory to servers in the local data center
+// remoteFactory: ConnectionFactory for servers in a remote data center
+// localFactory and remoteFactory use round robin load balancing "internally".
+
+final List<ConnectionFactory> factories =
+ Arrays.asList(localFactory, remoteFactory);
+
+final FailoverLoadBalancingAlgorithm algorithm =
+ new FailoverLoadBalancingAlgorithm(factories);
+
+final ConnectionFactory factory = Connections.newLoadBalancer(algorithm);</programlisting>
+
+ <para>The algorithms also include constructors that let you adjust timeouts
+ and so forth.</para>
+ </section>
+
+ <section xml:id="handling-client-connections">
+ <title>Listening For & Handling Client Connections</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Listening for</secondary>
+ </indexterm>
+
+ <para>You create an <literal>LDAPListener</literal> to handle incoming client
+ connections. The <literal>LDAPListener</literal> takes a connection handler
+ that deals with the connections, in this case connections back to the
+ directory servers handling client requests.</para>
+
+ <programlisting language="java">
+final LDAPListenerOptions options = new LDAPListenerOptions().setBacklog(4096);
+LDAPListener listener = null;
+try {
+ listener = new LDAPListener(localAddress, localPort, connectionHandler,
+ options);
+ System.out.println("Press any key to stop the server...");
+ System.in.read();
+} catch (final IOException e) {
+ System.out.println("Error listening on " + localAddress + ":" + localPort);
+ e.printStackTrace();
+} finally {
+ if (listener != null) {
+ listener.close();
+ }
+}
+</programlisting>
+
+ <para>You get a <literal>ServerConnectionFactory</literal> to handle requests
+ coming from clients. The <literal>ServerConnectionFactory</literal> takes a
+ request handler that deals with the incoming client requests. The request
+ handler implements handlers for all supported operations. The Proxy example
+ implements a <literal>ProxyBackend</literal> to handle requests. The
+ <literal>ProxyBackend</literal> sends the requests on to the backend
+ directory servers and routes the results returned back to client
+ applications.</para>
+
+ <programlisting language="java">
+final ProxyBackend backend = new ProxyBackend(factory, bindFactory);
+final ServerConnectionFactory<LDAPClientContext, Integer> connectionHandler =
+ Connections.newServerConnectionFactory(backend);
+</programlisting>
+
+ <para>See the Proxy example code for details about the
+ <literal>ProxyBackend</literal> implementation.</para>
+ </section>
+
+ <section xml:id="dn-attr-rewriting">
+ <title>DN & Attribute Rewriting</title>
+ <indexterm>
+ <primary>Attributes</primary>
+ <secondary>Rewriting</secondary>
+ </indexterm>
+
+ <para>Suppose you have a client application that expects a different
+ attribute name, such as <literal>fullname</literal> for a standard attribute
+ like <literal>cn</literal> (common name), and that expects a distinguished
+ name (DN) suffix different from what is stored in the directory. If you
+ cannot change the application, one possible alternative is a proxy layer
+ that does DN and attribute rewriting.<footnote><para>Some servers, such as
+ OpenDJ directory server, can do attribute rewriting without a proxy layer.
+ See your directory server's documentation for details.</para></footnote></para>
+
+ <screen># A search accessing the directory server
+$ ldapsearch -b dc=example,dc=com -p 1389 "(cn=Babs Jensen)" cn
+dn: uid=bjensen,ou=People,dc=example,dc=com
+cn: Barbara Jensen
+cn: Babs Jensen
+
+# The same search search accessing a proxy that rewrites requests and responses
+$ ldapsearch -b o=example -p 8389 "(fullname=Babs Jensen)" fullname
+dn: uid=bjensen,ou=People,o=example
+fullname: Barbara Jensen
+fullname: Babs Jensen
+</screen>
+
+ <para>The OpenDJ LDAP SDK <link xlink:show="new"
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/RewriterProxy.html"
+ >RewriterProxy</link> example builds on the Proxy example, rewriting requests
+ and search result entries. When you read the example, look for the
+ <literal>rewrite()</literal> methods.</para>
+
+ <para>In the above output, the rewriter proxy listens on port 8389,
+ connecting to a directory server listening on 1389. The directory server
+ contains data from <link xlink:href="http://opendj.forgerock.org/Example.ldif"
+ xlink:show="new"><filename>Example.ldif</filename></link>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-understanding-ldap.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-understanding-ldap.xml
new file mode 100644
index 0000000..ada574e
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-understanding-ldap.xml
@@ -0,0 +1,353 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-understanding-ldap'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Understanding LDAP</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>About</secondary>
+ </indexterm>
+
+ <para>A directory resembles a dictionary or a phone book. If you know a
+ word, you can look it up its entry in the dictionary to learn its definition
+ or its pronunciation. If you know a name, you can look it up its entry in the
+ phone book to find the telephone number and street address associated with the
+ name. If you are bored, curious, or have lots of time, you can also read
+ through the dictionary, phone book, or directory, entry after entry.</para>
+
+ <para>Where a directory differs from a paper dictionary or phone book is
+ in how entries are indexed. Dictionaries typically have one index: words
+ in alphabetical order. Phone books, too: names in alphabetical order.
+ Directories entries on the other hand are often indexed for multiple
+ attributes, names, user identifiers, email addresses, telephone numbers.
+ This means you can look up a directory entry by the name of the user the
+ entry belongs to, but also by her user identifier, her email address, or
+ her telephone number, for example.</para>
+
+ <section xml:id="ldap-directory-history">
+ <title>How Directories & LDAP Evolved</title>
+
+ <para>Phone companies have been managing directories for many decades. The
+ Internet itself has relied on distributed directory services like DNS since
+ the mid 1980s.</para>
+
+ <para>It was not until the late 1980s, however, that experts from what is now
+ the International Telecommunications Union brought forth the X.500 set of
+ international standards, including Directory Access Protocol. The X.500
+ standards specify Open Systems Interconnect (OSI) protocols and
+ data definitions for general-purpose directory services. The X.500 standards
+ were designed to meet the needs of systems built according to the X.400
+ standards, covering electronic mail services.</para>
+
+ <para>Lightweight Directory Access Protocol has been around since the early
+ 1990s. LDAP was originally developed as an alternative protocol that would
+ allow directory access over Internet protocols rather than OSI protocols,
+ and be lightweight enough for desktop implementations. By the mid 1990s, LDAP
+ directory servers became generally available and widely used.</para>
+
+ <para>Until the late 1990s, LDAP directory servers were designed primarily
+ with quick lookups and high availability for lookups in mind. LDAP directory
+ servers replicate data, so when an update is made, that update gets pushed
+ out to other peer directory servers. Thus if one directory server goes down
+ lookups can continue on other servers. Furthermore, if a directory service
+ needs to support more lookups, the administrator can simply add another
+ directory server to replicate with its peers.</para>
+
+ <para>As organizations rolled out larger and larger directories serving more
+ and more applications, they discovered that they needed high availability
+ not only for lookups, but also for updates. Around 2000 directories began
+ to support multi-master replication, that is replication with multiple
+ read-write servers. Soon thereafter the organizations with the very largest
+ directories started to need higher update performance as well as
+ availability.</para>
+
+ <para>The OpenDJ code base began in the mid 2000s, when engineers solving the
+ update performance issue decided the cost of adapting the existing C-based
+ directory technology for high performance updates would be higher than the
+ cost of building a next generation, high performance directory using Java
+ technology.</para>
+ </section>
+
+ <section xml:id="directory-data">
+ <title>Data In LDAP Directories</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Data</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Attributes</primary>
+ </indexterm>
+
+ <para>LDAP directory data is organized into entries, similar to the entries
+ for words in the dictionary, or for subscriber names in the phone book.
+ A sample entry follows.</para>
+
+ <programlisting language="LDIF">dn: uid=bjensen,ou=People,dc=example,dc=com
+uid: bjensen
+cn: Babs Jensen
+cn: Barbara Jensen
+facsimileTelephoneNumber: +1 408 555 1992
+gidNumber: 1000
+givenName: Barbara
+homeDirectory: /home/bjensen
+l: Cupertino
+mail: bjensen@example.com
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: person
+objectClass: posixAccount
+objectClass: top
+ou: People
+ou: Product Development
+roomNumber: 0209
+sn: Jensen
+telephoneNumber: +1 408 555 1862
+uidNumber: 1076
+</programlisting>
+
+ <para>Barbara Jensen's entry has a number of attributes, such as
+ <literal>uid: bjensen</literal>,
+ <literal>telephoneNumber: +1 408 555 1862</literal>, and
+ <literal>objectClass: posixAccount</literal><footnote><para>The
+ <literal>objectClass</literal> attribute type indicates which types of
+ attributes are allowed and optional for the entry. As the entries object
+ classes can be updated online, and even the definitions of object classes
+ and attributes are expressed as entries that can be updated online, directory
+ data is extensible on the fly.</para></footnote>. When you look up her entry
+ in the directory, you specify one or more attributes and values to match
+ in the entries that come back as the result of your search. Typically the
+ attributes you search for are indexed in the directory, so the directory
+ server can retrieve them more quickly.<footnote><para>Attribute values
+ do not have to be strings. The directory can use base64 encoding, however,
+ to make binary attribute values, such as passwords, certificates, or photos,
+ portable in text format.</para></footnote></para>
+
+ <para>The entry also has a unique identifier, shown at the top of the entry,
+ <literal>dn: uid=bjensen,ou=People,dc=example,dc=com</literal>. DN stands
+ for distinguished name. No two entries in the directory have the same
+ distinguished name.<footnote><para>Sometimes your distinguished names include
+ characters that you must escape. The following example shows an entry that
+ includes escaped characters in the DN.</para>
+ <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=escape)"
+dn: cn=\" # \+ \, \; \< = \> \\ DN Escape Characters,dc=example,dc=com
+objectClass: person
+objectClass: inetOrgPerson
+objectClass: organizationalPerson
+objectClass: top
+givenName: " # + , ; < = > \
+uid: escape
+cn: " # + , ; < = > \ DN Escape Characters
+sn: DN Escape Characters
+mail: escape@example.com</screen></footnote></para>
+
+ <para>LDAP entries are arranged hierarchically in the directory. The
+ hierarchical organization resembles a file system on a PC or a web server,
+ often imagined as an upside-down tree structure, looking similar to a
+ pyramid.<footnote><para>Hence pyramid icons are associated with directory
+ servers.</para></footnote>The distinguished name consists of components
+ separated by commas,
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>. Those components
+ reflect the hierarchy of directory entries.</para>
+
+ <mediaobject xml:id="figure-data-organization">
+ <alt>Directory data hierarchy as seen in OpenDJ Control Panel.</alt>
+ <imageobject>
+ <imagedata fileref="images/data-organization.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>You can see the hierarchy of directory data in the left pane of
+ the Manage Entries browser.</para>
+ </textobject>
+ </mediaobject>
+
+ <para>Barbara Jensen's entry is located under an entry with DN
+ <literal>ou=People,dc=example,dc=com</literal>, an organization unit and
+ parent entry for the people at Example.com. The
+ <literal>ou=People</literal> entry is located under the entry with DN
+ <literal>dc=example,dc=com</literal>, the root entry for Example.com.
+ DC stands for domain component. The directory has other root entries, such
+ as <literal>cn=config</literal>, under which the configuration is accessible
+ through LDAP, and potentially others such as
+ <literal>dc=mycompany,dc=com</literal> or <literal>o=myOrganization</literal>.
+ Thus when you look up entries, you specify the parent entry to look under
+ in the same way you need to know whether to look in the New York, Paris,
+ or Tokyo phone book to find a telephone number.<footnote>
+ <para>The root entry for the directory, technically the entry with DN
+ <literal>""</literal> (the empty string), is called the root DSE, and
+ contains information about what the server supports, including the other
+ root entries it serves.</para></footnote></para>
+ </section>
+
+ <section xml:id="ldap-client-server-communication">
+ <title>LDAP Client & Server Communication</title>
+ <indexterm>
+ <primary>LDAP</primary>
+ <secondary>Connected protocol</secondary>
+ </indexterm>
+
+ <para>You may be used to web service client server communication, where
+ each time the web client has something to request of the web server, a
+ connection is set up and then torn down. LDAP has a different model. In
+ LDAP the client application connects to the server and authenticates, then
+ requests any number of operations perhaps processing results in between
+ requests, and finally disconnects when done.</para>
+
+ <mediaobject xml:id="figure-ldap-lifecycle">
+ <alt>Schematic of LDAP client-server session</alt>
+ <imageobject>
+ <imagedata fileref="images/ldap-lifecycle.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>An LDAP client binds, performs operations, and then unbinds.</para>
+ </textobject>
+ </mediaobject>
+
+ <indexterm>
+ <primary>Authentications</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Searches</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Comparisons</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Adds</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Deletes</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Renames</primary>
+ </indexterm>
+ <itemizedlist xml:id="standard-ldap-operations">
+ <para>The standard operations are as follows.</para>
+ <listitem>
+ <para>Bind (authenticate). The first operation in an LDAP session involves
+ the client binding to the LDAP server, with the server authenticating the
+ client. Authentication identifies the client's identity in LDAP terms, the
+ identity which is later used by the server to authorize (or not) access
+ to directory data that the client wants to lookup or change.</para>
+ </listitem>
+ <listitem>
+ <para>Search (lookup). After binding, the client can request that the server
+ return entries based on an LDAP filter, which is an expression that the
+ server uses to find entries that match the request, and a base DN under
+ which to search. For example, to lookup all entries for people with email
+ address <literal>bjensen@example.com</literal> in data for Example.com,
+ you would specify a base DN such as
+ <literal>ou=People,dc=example,dc=com</literal> and the filter
+ <literal>(mail=bjensen@example.com)</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Compare. After binding, the client can request that the server
+ compare an attribute value the client specifies with the value stored
+ on an entry in the directory.</para>
+ </listitem>
+ <listitem>
+ <para>Modify. After binding, the client can request that the server
+ change one or more attribute values stored on one or more entries. Often
+ administrators do not allow clients to change directory data, so request
+ that your administrator set appropriate access rights for your client
+ application if you want to update data.</para>
+ </listitem>
+ <listitem>
+ <para>Add. After binding, the client can request to add one or more
+ new LDAP entries to the server. </para>
+ </listitem>
+ <listitem>
+ <para>Delete. After binding, the client can request that the server
+ delete one or more entries. To delete and entry with other entries
+ underneath, first delete the children, then the parent.</para>
+ </listitem>
+ <listitem>
+ <para>Modify DN. After binding, the client can request that the server
+ change the distinguished name of the entry. For example, if Barbara
+ changes her unique identifier from <literal>bjensen</literal> to something
+ else, her DN would have to change. For another example, if you decide
+ to consolidate <literal>ou=Customers</literal> and
+ <literal>ou=Employees</literal> under <literal>ou=People</literal>
+ instead, all the entries underneath much change distinguished names.
+ <footnote><para>Renaming entire branches of entries can be a major
+ operation for the directory, so avoid moving entire branches if you
+ can.</para></footnote></para>
+ </listitem>
+ <listitem>
+ <para>Unbind. When done making requests, the client should request an
+ unbind operation to release resources right away for other clients.</para>
+ </listitem>
+ <listitem>
+ <para>Abandon. When a request seems to be taking too long to complete,
+ or when a search request returns many more matches than desired, the client
+ can send an abandon request to the server to drop the operation in
+ progress. The server then drops the connection without a reply to the
+ client.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="standard-ldapv3-extensions">
+ <title>Standard LDAPv3 & Extensions</title>
+ <para>LDAP has standardized two mechanisms for extending the kinds of
+ operations that directory servers can perform. One mechanism involves using
+ LDAP controls. The other mechanism involves using LDAP extended
+ operations.</para>
+
+ <indexterm>
+ <primary>Controls</primary>
+ <secondary>About</secondary>
+ </indexterm>
+ <para>LDAP controls are information added to an LDAP message to further
+ specify how an LDAP operation should be processed. For example, the
+ Server Side Sort Request Control modifies a search to request that the
+ directory server return entries to the client in sorted order. The Subtree
+ Delete Request Control modifies a delete to request that the server
+ also remove child entries of the entry targeted for deletion.</para>
+
+ <indexterm>
+ <primary>Extended operations</primary>
+ <secondary>About</secondary>
+ </indexterm>
+ <para>LDAP extended operations are additional LDAP operations not included
+ in the original standard list. For example, the Cancel Extended Operation
+ works like an abandon operation, but finishes with a response from the
+ server after the cancel is complete. The StartTLS Extended Operation allows
+ a client to connect to a server on an unsecure port, but then start
+ Transport Layer Security negotiations to protect communications.</para>
+
+ <para>Both LDAP controls and extended operations are demonstrated later in
+ this guide. OpenDJ directory server supports many LDAP controls and a few
+ LDAP extended operations, controls and extended operations matching those
+ demonstrated in this guide.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-using-the-sdk.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
new file mode 100644
index 0000000..5e9b092
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-using-the-sdk.xml
@@ -0,0 +1,197 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-using-the-sdk'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Using the LDAP SDK</title>
+
+ <para>As LDAP relies on a connection from the client to the directory server,
+ the starting point for working with the LDAP SDK is a new
+ <literal>LDAPConnectionFactory</literal>, from which you then get either
+ a synchronous connection, or pass in a handler to an asynchronous
+ connection. You then use the connection to make requests and get responses
+ from the directory server.</para>
+
+ <section xml:id="sync-vs-async">
+ <title>Synchronous & Asynchronous Operations</title>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Asynchronous</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Connections</primary>
+ <secondary>Synchronous</secondary>
+ </indexterm>
+
+ <para>For synchronous operations your application gets a connection from
+ the <literal>LDAPConnectionFactory</literal> and requests operations on
+ the connection. When finished, your application closes the connection.</para>
+
+ <programlisting language="java">
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+
+try {
+ connection = factory.getConnection();
+
+ // Perform operations on the connection, such as connection.bind(),
+ // connection.search(), connection.modify(), etc.
+
+ } catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+ } finally {
+ if (connection != null) {
+ connection.close();
+ }
+ }
+</programlisting>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/Search.html"
+ xlink:show="new">Search.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+
+ <para>For asynchronous operations, your application passes a result handler
+ to <literal>LDAPConnectionFactory.getConnectionAsync()</literal> that
+ implements the <literal>ResultHandler<Connection></literal>
+ interface.</para>
+
+ <programlisting language="java">
+private static final class ConnectResultHandlerImpl
+ implements ResultHandler<Connection> {
+ @Override
+ public void handleErrorResult(final ErrorResultException error) {
+ ...
+ }
+
+ @Override
+ public void handleResult(final Connection connection) {
+ // Connect succeeded: save connection and initiate bind.
+ SearchAsync.connection = connection;
+
+ final BindRequest request =
+ Requests.newSimpleBindRequest(userName, password.toCharArray());
+ connection.bindAsync(request, null, new BindResultHandlerImpl());
+ }
+}
+
+// Main method initiates async operations by getting a connection...
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(hostName, port);
+factory.getConnectionAsync(new ConnectResultHandlerImpl());
+
+...
+
+if (connection != null) {
+ connection.close();
+}
+</programlisting>
+
+ <para>When the connection result handler gets a connection, your application
+ can pass result handlers for other operations using methods on the connection
+ named <literal>*Async()</literal>. For most operations, your application
+ implements <literal>ResultHandler</literal>. For searches, your application
+ implements <literal>SearchResultHandler</literal>. The result handler is
+ notified upon completion of the operation.</para>
+
+ <para>Asynchronous methods are non-blocking, returning a
+ <literal>FutureResult</literal> whose <literal>get()</literal> method lets
+ you retrieve the result. Your application must coordinate concurrency when
+ you use asynchronous operations.</para>
+
+ <para>For a complete example in context, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/SearchAsync.html"
+ xlink:show="new">SearchAsync.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+ </section>
+
+ <section xml:id="error-handling">
+ <title>Managing Errors</title>
+ <indexterm>
+ <primary>Errors</primary>
+ </indexterm>
+
+ <para>LDAP <link xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A"
+ xlink:show="new">defines many result codes</link> to deal with conditions
+ other than success. The <literal>ResultCode</literal> class encapsulates the
+ LDAP codes and additional client-side codes specific to the SDK.</para>
+
+ <para>Your application deals with most non-success result codes when it
+ catches one of the LDAP SDK exceptions corresponding to the operation you
+ requested. <literal>ErrorResultException</literal> is a common way for the
+ SDK to indicate a non-successful result. Your application can then take
+ remedial action based on the result code, as in the following synchronous
+ excerpt.</para>
+
+ <programlisting language="java">
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+
+try {
+ connection = factory.getConnection();
+ connection.bind(name, password);
+
+ // Perform operations on the connection...
+
+} catch (final ErrorResultException e) {
+
+ // Take remedial action based on the result code...
+ // e.getResult().getResultCode() returns the code for you to interpret.
+
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}
+</programlisting>
+
+ <para>Also notice the methods <literal>ResultCode.getName()</literal> that
+ provides a short, human-readable version of the result code, and
+ <literal>Result.getDiagnosticMessage()</literal> that can also help debug
+ problems after the fact.</para>
+ </section>
+
+ <!-- Pending https://bugster.forgerock.org/jira/browse/OPENDJ-178
+ <section xml:id="referral-handling">
+ <title>Managing Referrals</title>
+ <indexterm>
+ <primary>Searches</primary>
+ <secondary>Handling results</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Referrals</primary>
+ </indexterm>
+
+ <para></para>
+ </section>
+ -->
+</chapter>
\ No newline at end of file
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-writing.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-writing.xml
new file mode 100644
index 0000000..c1af02d
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/chap-writing.xml
@@ -0,0 +1,468 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-writing'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Updating Directory Data</title>
+
+ <para>Modern directory servers like OpenDJ can handle a high load of write
+ requests, replicating changes quickly both on the LAN and over the WAN.</para>
+
+ <para>For a complete example corresponding to the excerpts shown below, see
+ <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/ShortLife.html"
+ xlink:show="new">ShortLife.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+
+ <section xml:id="about-writes">
+ <title>About Add, Modify, Rename, & Delete</title>
+
+ <para>The four basic CRUD operations — create, read, update, and delete
+ — correspond to the LDAP operations add, search, modify (or modify DN),
+ and delete.<footnote><para>The LDAP bind operation can potentially result in
+ an update. Some directory servers can be configured to write time stamps in
+ order to track successful or failed binds for password policy reasons.</para>
+ </footnote></para>
+
+ <indexterm>
+ <primary>Adds</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Renames</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Deletes</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Authorizations</primary>
+ </indexterm>
+
+ <itemizedlist>
+ <listitem>
+ <para>An add request is used to create a new entry in an LDAP directory.
+ The entry must have a unique distinguished name that belongs under a base
+ DN served by the directory. The entry must have a list of attributes that
+ are valid according to the directory schema.</para>
+ </listitem>
+
+ <listitem>
+ <para>Search requests are described in the chapter on <link
+ xlink:href="dev-guide#chap-reading"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Searching &
+ Comparing Directory Data</citetitle></link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>A modify request is used to add, delete, or replace attribute values
+ on an entry in an LDAP directory. The resulting entry must be valid
+ according to the directory schema.</para>
+
+ <para>A modify DN request is used to rename or move a directory entry.
+ In both cases the distinguished name changes. Renaming involves changing
+ the relative distinguished name, for example from
+ <literal>cn=Bob,ou=People,dc=example,dc=com</literal> to
+ <literal>cn=Ted,ou=People,dc=example,dc=com</literal>. Moving
+ involves changing the container where the entry is found, for example from
+ <literal>cn=Barbara Jensen,ou=People,dc=Old Company,dc=com</literal> to
+ <literal>cn=Barbara Jensen,ou=People,dc=New Company,dc=com</literal>.</para>
+
+ <para>Although they are both considered modify DN operations, renaming a
+ leaf entry is generally much simpler than moving a container entry that has
+ child entries. Not all modify DN operations mobilize equivalent resources
+ on the directory server.</para>
+ </listitem>
+
+ <listitem>
+ <para>A delete request is used to remove an entry from an LDAP
+ directory.</para>
+
+ <para>Directory servers can restrict deletes to leaf entries, so that you
+ cannot remove an entry that has other child entries. For example, you have
+ to delete <literal>uid=bjensen,ou=People,dc=example,dc=com</literal> and
+ other peer entries before you delete
+ <literal>ou=People,dc=example,dc=com</literal> unless you send a subtree
+ delete request control.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>As a rule, your client application must be authorized to create,
+ update, and delete directory data. Therefore to prepare to change directory
+ data, you first get a connection, and then bind on that connection as a
+ user who is authorized to make the changes you plan to request.</para>
+ </section>
+
+ <section xml:id="adding-entries">
+ <title>Adding Directory Entries</title>
+ <indexterm>
+ <primary>Adds</primary>
+ </indexterm>
+
+ <para>The <literal>Connection.add()</literal> methods let you provide the
+ entry to add as an <literal>AddRequest</literal>, an <literal>Entry</literal>,
+ or as LDIF. If the changes to make are already expressed in LDIF, then
+ you can also use <literal>ChangeRecordReader</literal>s,
+ <literal>ChangeRecord</literal>s, and <literal>ChangeRecordWriter</literal>s
+ to handle the changes.</para>
+
+ <para>The following excerpt demonstrates how to add a simple user entry under
+ <literal>ou=People,dc=example,dc=com</literal>.</para>
+
+ <programlisting language="java">// An entry to add to the directory
+Entry entry = new LinkedHashMapEntry("cn=Bob,ou=People,dc=example,dc=com")
+ .addAttribute("cn", "Bob")
+ .addAttribute("objectclass", "top")
+ .addAttribute("objectclass", "person")
+ .addAttribute("objectclass", "organizationalPerson")
+ .addAttribute("objectclass", "inetOrgPerson")
+ .addAttribute("mail", "subgenius@example.com")
+ .addAttribute("sn", "Dobbs");
+
+final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+ // Bind as a user who has the right to add entries.
+ connection.bind(adminDN, adminPwd);
+
+ connection.add(entry);
+
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+ </section>
+
+ <section xml:id="modifying-attr-values">
+ <title>Modifying Directory Entry Attribute Values</title>
+ <indexterm>
+ <primary>Modifications</primary>
+ </indexterm>
+
+ <para>The <literal>Connection.modify()</literal> methods let you add, replace,
+ and delete attributes values on an entry. Either the modifications are
+ expressed in LDIF, or you build a <literal>ModifyRequest</literal> to
+ express the changes.</para>
+
+ <para>The following excerpt demonstrates how to replace one attribute value
+ and to add another.</para>
+
+ <programlisting language="java"
+ >final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+ // Bind as a user who has the right to modify entries.
+ connection.bind(adminDN, adminPwd);
+
+ // Here, entry is a user entry with DN cn=Bob,ou=People,dc=example,dc=com.
+ Entry old = TreeMapEntry.deepCopyOfEntry(entry);
+ entry = entry.replaceAttribute("mail", "spammer@example.com")
+ .addAttribute("description", "I see the fnords.");
+ ModifyRequest request = Entries.diffEntries(old, entry);
+
+ connection.modify(request);
+
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+ </section>
+
+ <section xml:id="renaming-entries">
+ <title>Renaming Directory Entries</title>
+ <indexterm>
+ <primary>Renames</primary>
+ </indexterm>
+
+ <para>The <literal>Connection.modifyDN()</literal> methods serve to rename
+ entries and to move them around.</para>
+
+ <para>The following excerpt demonstrates how to rename an entry.</para>
+
+ <programlisting language="java"
+ >final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+ // Bind as a user who has the right to rename entries.
+ connection.bind(adminDN, adminPwd);
+
+ // Here, entryDN contains cn=Bob,ou=People,dc=example,dc=com.
+ // The second argument is the new relative distinguished name.
+ connection.modifyDN(entryDN, "cn=Ted");
+
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+
+ <para>If you must move rather than rename entries, have a look at the methods
+ for <literal>ModifyDNRequest</literal>. You can get a new request by using
+ <literal>Requests</literal> static methods.</para>
+ </section>
+
+ <section xml:id="deleting-entries">
+ <title>Deleting Directory Entries</title>
+ <indexterm>
+ <primary>Deletes</primary>
+ </indexterm>
+
+ <para>The following excerpt demonstrates how to delete an entry with DN
+ <literal>cn=Ted,ou=People,dc=example,dc=com</literal>.</para>
+
+ <programlisting language="java"
+ >final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+ // Bind as a user who has the right to delete entries.
+ connection.bind(adminDN, adminPwd);
+
+ connection.delete("cn=Ted,ou=People,dc=example,dc=com");
+
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+
+ <para>If you must delete an entire branch of entries instead of a single
+ leaf entry, build a <literal>DeleteRequest</literal> that includes the
+ <literal>SubtreeDeleteRequestControl</literal>, as described in the
+ section, <link xlink:href="dev-guide#use-subtree-delete-control"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Subtree Delete
+ Request Control</citetitle></link>.</para>
+ </section>
+
+ <section xml:id="updating-static-groups">
+ <title>Updating Static Groups</title>
+ <indexterm>
+ <primary>Modifications</primary>
+ <secondary>Static groups</secondary>
+ </indexterm>
+
+ <para>Static groups enumerate user entries. Static groups can grow large.
+ For an example, see the group entry at the end of <link xlink:show="new"
+ xlink:href="http://opendj.forgerock.org/big-group.ldif">big-group.ldif</link>:</para>
+
+ <programlisting language="ldif">dn: cn=Static,ou=Groups,dc=example,dc=com
+objectClass: top
+objectClass: groupofnames
+cn: Static
+member: uid=user.0,ou=People,dc=example,dc=com
+member: uid=user.1,ou=People,dc=example,dc=com
+member: uid=user.2,ou=People,dc=example,dc=com
+...
+member: uid=user.10000,ou=People,dc=example,dc=com</programlisting>
+
+ <para>To update a static group, you either add members or remove members.
+ For sample code, see <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/xref/org/forgerock/opendj/examples/UpdateGroup.html"
+ xlink:show="new">UpdateGroup.java</link>, one of the <link
+ xlink:href="http://opendj.forgerock.org/opendj-ldap-sdk-examples/"
+ xlink:show="new">OpenDJ LDAP SDK examples</link>.</para>
+
+ <para>The <literal>UpdateGroup</literal> example checks that the directory
+ server supports the Permissive Modify control. With directory servers such
+ as OpenDJ that support the LDAP Permissive Modify control, you can use the
+ control to avoid having to determine whether a given member is already in the
+ group before performing the operation. Instead you can simply request an
+ add or a delete modification for the member.</para>
+
+ <example xml:id="update-group-with-permissive-modify"><?dbfo keep-together="auto"?>
+ <title>Updating a Group With Permissive Modify</title>
+ <programlisting language="java"
+ >final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+
+ Collection<String> controls =
+ RootDSE.readRootDSE(connection).getSupportedControls();
+
+ final String user = "cn=Directory Manager";
+ final char[] password = "password".toCharArray();
+ connection.bind(user, password);
+
+ if (controls.contains(PermissiveModifyRequestControl.OID)) {
+
+ final ModifyRequest request = Requests.newModifyRequest(groupDN)
+ .addControl(PermissiveModifyRequestControl.newControl(true))
+ .addModification(modType, "member", memberDN);
+ connection.modify(request);
+
+ } else {
+
+ /* ... */
+
+ }
+
+ String op = (modType == ModificationType.ADD) ? "added to" : "deleted from";
+ System.out.println("The entry with DN " + memberDN + " has been "
+ + op + " the group with DN " + groupDN + ".");
+
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+ </example>
+
+ <para>If the directory server does not support the Permissive Modify control,
+ then the example checks whether the member is present in the group by using
+ an LDAP compare operation. If a member to be added does not yet belong to the
+ group, the example requests an add modification. If a member to be deleted
+ does belong to the group, the example requests a delete modification.</para>
+
+ <example xml:id="update-group-with-compare-and-modify"><?dbfo keep-together="auto"?>
+ <title>Updating a Group With Compare & Modify</title>
+ <programlisting language="java"
+ >final LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port);
+Connection connection = null;
+try {
+ connection = factory.getConnection();
+
+ Collection<String> controls =
+ RootDSE.readRootDSE(connection).getSupportedControls();
+
+ final String user = "cn=Directory Manager";
+ final char[] password = "password".toCharArray();
+ connection.bind(user, password);
+
+ if (controls.contains(PermissiveModifyRequestControl.OID)) {
+
+ /* ... */
+
+ } else {
+
+ System.out.println("Checking whether the entry with DN "
+ + memberDN + " belongs to the group with DN " + groupDN
+ + "...");
+ final CompareRequest request =
+ Requests.newCompareRequest(groupDN, "member", memberDN);
+ CompareResult result = connection.compare(request);
+
+ if (modType == ModificationType.ADD) {
+ if (result.getResultCode() == ResultCode.COMPARE_FALSE) {
+ System.out.println("Member does not yet belong to group."
+ + " Adding it...");
+ final ModifyRequest addMember =
+ Requests.newModifyRequest(groupDN)
+ .addModification(modType, "member", memberDN);
+ connection.modify(addMember);
+ }
+ }
+
+ if (modType == ModificationType.DELETE) {
+ if (result.getResultCode() == ResultCode.COMPARE_TRUE) {
+ System.out.println("Member belongs to group."
+ + " Removing it...");
+ final ModifyRequest delMember =
+ Requests.newModifyRequest(groupDN)
+ .addModification(modType, "member", memberDN);
+ connection.modify(delMember);
+ }
+ }
+
+ }
+
+ String op = (modType == ModificationType.ADD) ? "added to" : "deleted from";
+ System.out.println("The entry with DN " + memberDN + " has been "
+ + op + " the group with DN " + groupDN + ".");
+
+} catch (final ErrorResultException e) {
+ System.err.println(e.getMessage());
+ System.exit(e.getResult().getResultCode().intValue());
+ return;
+} finally {
+ if (connection != null) {
+ connection.close();
+ }
+}</programlisting>
+
+ <para>You can change multiple member values with a single modification. The
+ final argument of this form of the
+ <literal>ModifyRequest.addModification()</literal> method takes a series
+ of one or more values. So if you have multiple group members to add or
+ delete, you can loop over your list to perform compare individual compare
+ requests, then construct a single modify request to add or delete the
+ group members. In other words, if you have three members to add, you can
+ list the three member DNs as arguments of
+ <literal>addModification</literal>.</para>
+
+ <programlisting language="java"
+ >String member1 = "uid=user1,ou=people,dc=example,dc=com";
+String member2 = "uid=user1,ou=people,dc=example,dc=com";
+String member3 = "uid=user1,ou=people,dc=example,dc=com";
+final ModifyRequest addMember =
+ Requests.newModifyRequest(groupDN)
+ .addModification(modType, "member", member1, member2, member3);
+connection.modify(addMember);</programlisting>
+ </example>
+
+ <para>To try the example, download and import
+ <filename>big-group.ldif</filename> into your directory server, and then
+ run the sample. For example, if OpenDJ is set up to with directory manager
+ as <literal>cn=Directory Manager</literal>, password
+ <literal>password</literal> listening on <literal>localhost</literal> port
+ <literal>1389</literal>, and you run the example with arguments
+ <literal>localhost 1389 cn=Static,ou=Groups,dc=example,dc=com
+ uid=user.5150,ou=People,dc=example,dc=com del</literal>, the resulting output
+ is <literal>The entry with DN uid=user.5150,ou=People,dc=example,dc=com has
+ been deleted from the group with DN
+ cn=Static,ou=Groups,dc=example,dc=com.</literal>.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/data-organization.png b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/data-organization.png
new file mode 100644
index 0000000..7292d60
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/data-organization.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-lifecycle.png b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-lifecycle.png
new file mode 100644
index 0000000..f633a88
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-lifecycle.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-tree.png b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-tree.png
new file mode 100644
index 0000000..061fffa
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/images/ldap-tree.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/index.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/index.xml
new file mode 100644
index 0000000..b717baa
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/index.xml
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2014 ForgeRock AS
+ !
+-->
+<book xml:id='dev-guide'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info>
+ <xinclude:include href="../shared/mediaobject-fr-logo.xml" />
+ <title>OpenDJ SDK Developer's Guide</title>
+ <subtitle>Version ${sdkDocTargetVersion}</subtitle>
+ <abstract>
+ <para>Hands-on guide to developing applications with the OpenDJ SDK. The
+ OpenDJ project offers open source LDAP directory services in Java.</para>
+ </abstract>
+ <copyright>
+ <year>2011-2014</year>
+ <holder>ForgeRock AS</holder>
+ </copyright>
+ <authorgroup>
+ <author>
+ <personname><firstname>Mark </firstname><surname>Craig</surname></personname>
+ </author>
+ <author>
+ <personname><firstname>Ludovic </firstname><surname>Poitou</surname></personname>
+ <xinclude:include href="../shared/affiliation-fr.xml"/>
+ </author>
+ </authorgroup>
+ <xinclude:include href='../legal.xml' />
+ <date>${publicationDate}</date>
+ <pubdate>${publicationDate}</pubdate>
+ <releaseinfo>${softwareReleaseDate}</releaseinfo>
+ </info>
+
+ <toc />
+
+ <xinclude:include href="preface.xml" />
+
+ <xinclude:include href='chap-understanding-ldap.xml' />
+ <xinclude:include href='chap-best-practices.xml' />
+ <xinclude:include href='chap-get-sdk.xml' />
+ <xinclude:include href='chap-using-the-sdk.xml' />
+ <xinclude:include href='chap-authenticating.xml' />
+ <xinclude:include href='chap-reading.xml' />
+ <xinclude:include href='chap-getting-directory-info.xml' />
+ <xinclude:include href='chap-writing.xml' />
+ <xinclude:include href='chap-ldif.xml' />
+ <xinclude:include href='chap-controls.xml' />
+ <xinclude:include href='chap-extended-ops.xml' />
+ <xinclude:include href='chap-i18n.xml' />
+ <xinclude:include href='chap-simple-proxy.xml' />
+
+ <reference xml:id="dev-tools-ref">
+ <title>Tools Reference</title>
+
+ <partintro>
+ <para>You can find the tools under the <filename>bin/</filename> or
+ <filename>bat\</filename> folder where you installed OpenDJ LDAP SDK
+ toolkit as described in the procedure explaining how <link
+ xlink:href="dev-guide#install-latest-sdk"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Install the
+ Latest SDK & Tools</citetitle></link>. For example,
+ <filename>/path/to/opendj-ldap-toolkit-<?eval ${sdkDocTargetVersion}?>/bin</filename>.</para>
+ </partintro>
+
+ <xinclude:include href='../shared/man-authrate.xml' />
+ <xinclude:include href='../shared/man-ldapcompare.xml' />
+ <xinclude:include href='../shared/man-ldapmodify.xml' />
+ <xinclude:include href='../shared/man-ldappasswordmodify.xml' />
+ <xinclude:include href='../shared/man-ldapsearch.xml' />
+ <xinclude:include href='../shared/man-ldifdiff.xml' />
+ <xinclude:include href='../shared/man-ldifmodify.xml' />
+ <xinclude:include href='../shared/man-ldifsearch.xml' />
+ <xinclude:include href='../shared/man-modrate.xml' />
+ <xinclude:include href='../shared/man-searchrate.xml' />
+ </reference>
+
+ <xinclude:include href="../shared/glossary.xml" />
+
+ <index />
+</book>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/dev-guide/preface.xml b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/preface.xml
new file mode 100644
index 0000000..aa04beb
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/dev-guide/preface.xml
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<preface xml:id='preface'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Preface</title>
+
+ <para>This guide shows you how to work with OpenDJ SDK to create client
+ applications in the Java language to connect to LDAP servers and perform
+ LDAP operations.</para>
+
+ <section>
+ <title>Who Should Read this Guide</title>
+
+ <para>This guide is written for Java developers who want to build directory
+ client applications with OpenDJ LDAP SDK.</para>
+
+ <para>This guide starts by explaining LDAP directories briefly, and
+ describing best practices for LDAP client applications. Then it demonstrates
+ how to install and use OpenDJ LDAP SDK to build LDAP clients.</para>
+
+ <para>You do not need to be an LDAP wizard to learn something from this
+ guide. You do need some background in writing Java 6 and client-server
+ applications to get the most out of this guide. You can nevertheless get
+ started with this guide, and then learn more as you go along.</para>
+ </section>
+
+ <xinclude:include href="../shared/sec-formatting-conventions.xml" />
+ <xinclude:include href="../shared/sec-accessing-doc-online.xml" />
+ <xinclude:include href="../shared/sec-joining-the-community.xml" />
+</preface>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-cli.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-cli.xml
new file mode 100644
index 0000000..9941798
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-cli.xml
@@ -0,0 +1,826 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-install-cli'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Installing OpenDJ From the Command Line</title>
+
+ <para>This chapter covers command-line installation with additional
+ information on setup options.</para>
+
+ <itemizedlist>
+ <listitem><para><xref linkend="before-you-install" /></para></listitem>
+ <listitem><para><xref linkend="command-line-install" /></para></listitem>
+ <listitem><para><xref linkend="install-deb" /></para></listitem>
+ <listitem><para><xref linkend="install-rpm" /></para></listitem>
+ <listitem><para><xref linkend="install-properties-file" /></para></listitem>
+ <listitem><para><xref linkend="install-rest2ldap-servlet" /></para></listitem>
+ <listitem><para><xref linkend="install-dsml-gateway" /></para></listitem>
+ </itemizedlist>
+
+ <procedure xml:id="before-you-install">
+ <title>To Prepare For Installation</title>
+
+ <step xml:id="check-for-java">
+ <para>Make sure you have the correct Java environment installed, as
+ described in the <citetitle>Release Notes</citetitle> section on <link
+ xlink:href="release-notes#prerequisites-java" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Java
+ Environment</citetitle></link> requirements.</para>
+
+ <para>If your default Java environment is not appropriate, set
+ <literal>OPENDJ_JAVA_HOME</literal> to the path to the correct Java
+ environment, or set <literal>OPENDJ_JAVA_BIN</literal> to the absolute path
+ of the <command>java</command> command. The latter environment variable is
+ useful for example if you have both 32-bit and 64-bit versions of the Java
+ environment installed, and want to make sure you use the 64-bit
+ version.</para>
+ </step>
+
+ <step xml:id="download-opendj">
+ <indexterm><primary>Downloading OpenDJ</primary></indexterm>
+
+ <xinclude:include href="../shared/itemizedlist-download.xml" />
+
+ <variablelist>
+ <para>The following server software is available.</para>
+
+ <varlistentry>
+ <term>OpenDJ-<?eval ${docTargetVersion}?>.zip</term>
+ <listitem>
+ <para>Cross-platform OpenDJ directory server installation files</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>opendj_<?eval ${docTargetVersion}?>-1_all.deb</term>
+ <listitem>
+ <para>OpenDJ directory server native package for Debian and related
+ Linux distributions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>opendj-<?eval ${docTargetVersion}?>-1.noarch.rpm</term>
+ <listitem>
+ <para>OpenDJ directory server native package for Red Hat and related
+ Linux distributions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>OpenDJ-<?eval ${docTargetVersion}?>-DSML.war</term>
+ <listitem>
+ <para>Cross-platform OpenDJ DSML gateway web archive</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>opendj-rest2ldap-servlet-<?eval ${docTargetVersion}?>-servlet.war</term>
+ <listitem>
+ <para>Cross-platform OpenDJ REST LDAP gateway web archive</para>
+ </listitem></varlistentry>
+ </variablelist>
+ </step>
+
+ <step xml:id="app-server-needed-for-dsml">
+ <indexterm><primary>DSML gateway</primary></indexterm>
+
+ <para>If you plan to install OpenDJ DSML gateway or OpenDJ REST LDAP gateway,
+ make sure you have an appropriate application server installed.</para>
+ </step>
+
+ <step>
+ <para>If you plan to configure SSL or TLS to secure network
+ communications between the server and client applications, get a
+ properly signed digital certificate that your client applications
+ recognize, such as one that fits with your organization's PKI or one
+ provided by a recognized certificate authority.</para>
+
+ <para>To use the certificate during installation, the certificate
+ must be located in a key store provided with Java (JKS, JCEKS, PKCS#12),
+ or on a PKCS#11 token. To import a signed certificate into a key store,
+ you can use the Java <command>keytool</command> command.</para>
+
+ <para>See <link xlink:href="admin-guide#setup-server-cert"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
+ Secure Communications</citetitle></link> in the <citetitle>Administration
+ Guide</citetitle> for examples.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="command-line-install">
+ <title>To Install OpenDJ Directory Server</title>
+ <indexterm><primary>Command-line installation</primary></indexterm>
+ <step>
+ <para>Unzip <filename>OpenDJ-<?eval ${docTargetVersion}?>.zip</filename>
+ in the file system directory where you want to install the server.</para>
+
+ <para>Unlike the web-based Quick Setup install, the <command>setup</command>
+ command uses the directory where you unzipped the files as the installation
+ directory, and does not ask you where to install OpenDJ. Therefore, if you
+ want to install elsewhere on the file system, unzip the files in that
+ location.</para>
+ </step>
+
+ <step>
+ <para>Run the <command>setup --cli</command> command found in the
+ <filename>opendj</filename> directory.</para>
+
+ <para>This command starts the setup program in interactive mode on the
+ command line, prompting you for each option. Alternatively, use
+ additional <command>setup</command> options to specify
+ values for the options you choose during interactive mode, thus
+ scripting the installation process. See <command>setup --help</command>
+ and the notes below.</para>
+
+ <indexterm><primary>Silent installation</primary></indexterm>
+ <para>To perform a non-interactive, silent installation, provide all
+ the options to configure OpenDJ, and then also use the <literal>-n</literal>
+ or <literal>--no-prompt</literal> option.</para>
+
+ <para>The <command>setup</command> command without the
+ <literal>--cli</literal> option runs the Quick Start
+ GUI installer with your local version of software, as does
+ Java WebStart with a remote version of the software.</para>
+
+ <screen>$ /path/to/opendj/setup --cli
+READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
+THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
+BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
+TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.
+
+...
+
+Please read the License Agreement above.
+You must accept the terms of the agreement before continuing with the
+installation.
+Accept the license (Yes/No) [No]:Yes
+
+What would you like to use as the initial root user DN for the Directory
+Server? [cn=Directory Manager]:
+Please provide the password to use for the initial root user:
+Please re-enter the password for confirmation:
+
+Provide the fully-qualified directory server host name that will be used when
+generating self-signed certificates for LDAP SSL/StartTLS, the administration
+connector, and replication [opendj.example.com]:
+
+On which port would you like the Directory Server to accept connections from
+LDAP clients? [1389]:
+
+On which port would you like the Administration Connector to accept
+connections? [4444]:
+
+Do you want to create base DNs in the server? (yes / no) [yes]:
+
+Provide the base DN for the directory data: dc=example,dc=com
+Options for populating the database:
+
+ 1) Only create the base entry
+ 2) Leave the database empty
+ 3) Import data from an LDIF file
+ 4) Load automatically-generated sample data
+
+Enter choice [1]: 3
+
+Please specify the path to the LDIF file containing the data to import: \
+/path/to/Example.ldif
+
+Do you want to enable SSL? (yes / no) [no]:
+
+Do you want to enable Start TLS? (yes / no) [no]:
+
+Do you want to start the server when the configuration is completed? (yes /
+no) [yes]:
+
+
+Setup Summary
+=============
+LDAP Listener Port: 1389
+Administration Connector Port: 4444
+LDAP Secure Access: disabled
+Root User DN: cn=Directory Manager
+Directory Data: Create New Base DN dc=example,dc=com.
+Base DN Data: Import Data from LDIF File (/path/to/Example.ldif)
+
+Start Server when the configuration is completed
+
+
+What would you like to do?
+
+ 1) Set up the server with the parameters above
+ 2) Provide the setup parameters again
+ 3) Print equivalent non-interactive command-line
+ 4) Cancel and exit
+
+Enter choice [1]:
+
+See /var/.../opendj-setup...log for a detailed log of this operation.
+
+Configuring Directory Server ..... Done.
+Importing LDIF file /path/to/Example.ldif ........... Done.
+Starting Directory Server ........... Done.
+
+To see basic server configuration status and configuration you can launch \
+/path/to/opendj/bin/status</screen>
+
+ <variablelist>
+ <para>Some notes on the options follow.</para>
+ <varlistentry>
+ <term>Initial root user DN</term>
+ <listitem>
+ <para>The root user Distinguished Name identifies a
+ user who can perform all administrative and other operations
+ allowed for the server, called root user due to the similarity
+ to the UNIX root. The default, <literal>cn=Directory Manager</literal>,
+ is a well-known name. If you have reason to be paranoid, you might
+ opt for a different name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Initial root user password</term>
+ <listitem>
+ <para>The root user will use simple, password-based authentication.
+ Later you can limit clear text access to avoid snooping, but for
+ now use a strong password here unless this is a throwaway server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Fully-qualified directory server host name</term>
+ <listitem>
+ <para>OpenDJ uses fully-qualified host name in self-signed certificates
+ and for identification when you use replication. If you are installing
+ a single server temporarily for evaluation, and are not concerned about
+ replication and whether self-signed certificates can be trusted, then
+ you can use an FQDN such as <literal>localhost.localdomain</literal>.
+ Otherwise, use an FQDN that other hosts can resolve to reach your
+ server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>LDAP port</term>
+ <listitem>
+ <para>The default for LDAP is 389. If you are working as a user
+ who cannot open port 389, setup suggests 1389 by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Administration port</term>
+ <listitem>
+ <para>This is the service entrance used to configure the server,
+ run tasks, and so forth. The default is 4444.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Create base DNs</term>
+ <listitem>
+ <para>You need a base Distinguished Name, such as
+ <literal>dc=example,dc=com</literal>, to add directory data. If you
+ already have LDIF, the base DN you want is the distinguished name
+ suffix common to all entries in your LDIF. You can provide more than
+ one base DN if your data belongs in more than one suffix.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Import LDIF</term>
+ <listitem>
+ <para>LDAP data interchange format is the standard text format for
+ expressing LDAP data. If you have LDIF already, one reason you might
+ not want to import the data at the same time you install is because
+ your data uses attributes not defined in the default schema, and so
+ you will wait to add schema definitions before you import.</para>
+
+ <para>If you have a huge data set to import, you no doubt should
+ also increase the import cache size, which you can do by passing
+ a Java properties file. You might also prefer to perform data
+ import offline.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Enable SSL and TLS</term>
+ <listitem>
+ <para>Enabling Secure Sockets Layer or Transport Layer Security lets
+ you protect the network traffic between directory clients and your
+ server.</para>
+ <variablelist>
+ <varlistentry>
+ <term>SSL</term>
+ <listitem>
+ <para>SSL requires its own, separate port for LDAPS traffic. The
+ default port for LDAPS is 636. If you are working as a user
+ who cannot open port 636, setup suggests 1636 by default.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>TLS</term>
+ <listitem>
+ <para>TLS lets you use StartTLS to negotiate a secure connection
+ between a client and server, starting from the same server port
+ you configured for LDAP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>X.509 certificates</term>
+ <listitem>
+ <para>The digital certificate you need for SSL and TLS can be
+ self-signed and created on the fly. Trouble is, client
+ applications view self-signed certificates like fake IDs, and
+ so do not trust them. Self-signed certificates facilitate testing,
+ but are not intended for production use.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Start the server</term>
+ <listitem>
+ <para>If you do not start the server during installation, you can use
+ the <command>/path/to/opendj/bin/start-ds</command> command later.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </step>
+
+ <step>
+ <para>Run the <command>status</command> command to make sure your OpenDJ
+ server is working as expected.</para>
+
+ <screen>$ /path/to/opendj/bin/status
+
+>>>> Specify OpenDJ LDAP connection parameters
+
+Administrator user bind DN [cn=Directory Manager]:
+
+Password for user 'cn=Directory Manager':
+
+ --- Server Status ---
+Server Run Status: Started
+Open Connections: 1
+
+ --- Server Details ---
+Host Name: opendj.example.com
+Administrative Users: cn=Directory Manager
+Installation Path: /path/to/opendj
+Version: OpenDJ <?eval ${docTargetVersion}?>
+Java Version: <replaceable>version</replaceable>
+Administration Connector: Port 4444 (LDAPS)
+
+ --- Connection Handlers ---
+Address:Port : Protocol : State
+-------------:----------:---------
+-- : LDIF : Disabled
+0.0.0.0:161 : SNMP : Disabled
+0.0.0.0:636 : LDAPS : Disabled
+0.0.0.0:1389 : LDAP : Enabled
+0.0.0.0:1689 : JMX : Disabled
+
+ --- Data Sources ---
+Base DN: dc=example,dc=com
+Backend ID: userRoot
+Entries: 160
+Replication: Disabled</screen>
+ </step>
+ </procedure>
+
+ <note>
+ <para>You can install OpenDJ in unattended and silent fashion, too. See
+ the procedure, <xref linkend="install-properties-file" />.</para>
+ </note>
+
+ <procedure xml:id="install-deb">
+ <title>To Install From the Debian Package</title>
+ <indexterm><primary>Debian (.deb) package</primary></indexterm>
+
+ <para>On Debian and related Linux distributions such as Ubuntu, you can
+ install OpenDJ directory server from the Debian package.</para>
+
+ <step performance="optional">
+ <para>Before you install OpenDJ, install a Java runtime environment if none
+ is installed yet.</para>
+
+ <screen>$ sudo apt-get install default-jre</screen>
+ </step>
+
+ <step>
+ <para>Install the OpenDJ directory server package.</para>
+
+ <screen>$ sudo dpkg -i opendj_<?eval ${docTargetVersion}?>-1_all.deb
+Selecting previously unselected package opendj.
+(Reading database ... 185569 files and directories currently installed.)
+Unpacking opendj (from opendj_<?eval ${docTargetVersion}?>-1_all.deb) ...
+
+Setting up opendj (<?eval ${docTargetVersion}?>) ...
+$</screen>
+
+ <para>The .deb installs OpenDJ directory server in the directory
+ <filename>/opt/opendj</filename>.</para>
+
+ <para>The files are owned by root by default, making it easier to have OpenDJ
+ listen on ports 389 and 636.</para>
+ </step>
+
+ <step>
+ <para>Configure OpenDJ directory server by using the command
+ <command>sudo /opt/opendj/setup</command>.</para>
+
+ <screen>$ sudo /opt/opendj/setup --cli
+...
+To see basic server configuration status and configuration you can launch
+ /opt/opendj/bin/status</screen>
+ </step>
+
+ <step performance="optional">
+ <para>Check OpenDJ directory server status.</para>
+
+ <screen>$ sudo /opt/opendj/bin/status
+
+
+>>>> Specify OpenDJ LDAP connection parameters
+
+Administrator user bind DN [cn=Directory Manager]:
+
+Password for user 'cn=Directory Manager':
+
+ --- Server Status ---
+Server Run Status: Started
+Open Connections: 1
+
+ --- Server Details ---
+Host Name: ubuntu.example.com
+Administrative Users: cn=Directory Manager
+Installation Path: /opt/opendj
+Version: OpenDJ <?eval ${docTargetVersion}?>
+Java Version: <replaceable>version</replaceable>
+Administration Connector: Port 4444 (LDAPS)
+
+ --- Connection Handlers ---
+Address:Port : Protocol : State
+-------------:------------------------:---------
+-- : LDIF : Disabled
+0.0.0.0:161 : SNMP : Disabled
+0.0.0.0:389 : LDAP (allows StartTLS) : Enabled
+0.0.0.0:636 : LDAPS : Enabled
+0.0.0.0:1689 : JMX : Disabled
+0.0.0.0:8080 : HTTP : Disabled
+
+ --- Data Sources ---
+Base DN: dc=example,dc=com
+Backend ID: userRoot
+Entries: 2002
+Replication: </screen>
+ </step>
+
+ <step performance="optional">
+ <para>If you want to run OpenDJ when the system starts, see <link
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#create-rc-script-1">create-rc-script</link>.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="install-rpm">
+ <title>To Install From the RPM Package</title>
+ <indexterm><primary>Red Hat (.rpm) package</primary></indexterm>
+
+ <para>On Red Hat and related Linux distributions such as Fedora and CentOS,
+ you can install OpenDJ directory server from the RPM package.</para>
+
+ <step>
+ <para>Log in as superuser to install the software.</para>
+
+ <screen>$ su
+Password:
+# </screen>
+ </step>
+
+ <step performance="optional">
+ <para>Before you install OpenDJ, install a Java runtime environment if none
+ is installed yet.</para>
+
+ <para>You might need to download an .rpm to install the Java runtime
+ environment, and then install it using the <command>rpm</command>
+ command.</para>
+
+ <screen># rpm -ivh jre-*.rpm</screen>
+ </step>
+
+ <step>
+ <para>Install the OpenDJ directory server package.</para>
+
+ <screen># rpm -i opendj-<?eval ${docTargetVersion}?>-1.noarch.rpm
+Pre Install - initial install
+Post Install - initial install
+
+#</screen>
+
+ <para>The .rpm installs OpenDJ directory server in the directory
+ <filename>/opt/opendj</filename>.</para>
+
+ <para>The files are owned by root by default, making it easier to have OpenDJ
+ listen on ports 389 and 636.</para>
+ </step>
+
+ <step>
+ <para>Configure OpenDJ directory server by using the command
+ <command>/opt/opendj/setup</command>.</para>
+
+ <screen># /opt/opendj/setup --cli
+...
+To see basic server configuration status and configuration you can launch
+ /opt/opendj/bin/status</screen>
+ </step>
+
+ <step performance="optional">
+ <para>Check OpenDJ directory server status.</para>
+
+ <screen># /opt/opendj/bin/status
+
+
+>>>> Specify OpenDJ LDAP connection parameters
+
+Administrator user bind DN [cn=Directory Manager]:
+
+Password for user 'cn=Directory Manager':
+
+ --- Server Status ---
+Server Run Status: Started
+Open Connections: 1
+
+ --- Server Details ---
+Host Name: fedora.example.com
+Administrative Users: cn=Directory Manager
+Installation Path: /opt/opendj
+Version: OpenDJ <?eval ${docTargetVersion}?>
+Java Version: <replaceable>version</replaceable>
+Administration Connector: Port 4444 (LDAPS)
+
+ --- Connection Handlers ---
+Address:Port : Protocol : State
+-------------:------------------------:---------
+-- : LDIF : Disabled
+0.0.0.0:161 : SNMP : Disabled
+0.0.0.0:389 : LDAP (allows StartTLS) : Enabled
+0.0.0.0:636 : LDAPS : Enabled
+0.0.0.0:1689 : JMX : Disabled
+0.0.0.0:8080 : HTTP : Disabled
+
+ --- Data Sources ---
+Base DN: dc=example,dc=com
+Backend ID: userRoot
+Entries: 2002
+Replication: </screen>
+ </step>
+
+ <step performance="optional">
+ <para>If you want to run OpenDJ when the system starts, see <link
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ xlink:href="admin-guide#create-rc-script-1">create-rc-script</link>.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="install-properties-file">
+ <title>To Install OpenDJ Directory Server With a Properties File</title>
+
+ <para>You can install OpenDJ directory server by using the
+ <command>setup</command> command with a properties file.</para>
+
+ <para>Property names correspond to the option names, but without leading
+ dashes. Options that take no arguments become boolean properties as in the
+ following example.</para>
+
+ <programlisting language="ini">enableStartTLS=true</programlisting>
+
+ <para>If you use a properties file with multiple tools, prefix the property
+ name with the tool name followed by a dot (<literal>.</literal>), as in the
+ following example.</para>
+
+ <programlisting language="ini">setup.rootUserPasswordFile=/tmp/pwd.txt</programlisting>
+
+ <para>The following steps demonstrate use of a properties file as part of a
+ scripted installation process.</para>
+
+ <step>
+ <para>Prepare your properties file.</para>
+
+ <para>This procedure uses the following example properties file.</para>
+
+ <programlisting language="ini">#
+# Sample properties file to set up OpenDJ directory server
+#
+hostname =opendj.example.com
+ldapPort =1389
+generateSelfSignedCertificate =true
+enableStartTLS =true
+ldapsPort =1636
+jmxPort =1689
+adminConnectorPort =4444
+rootUserDN =cn=Directory Manager
+rootUserPassword =password
+baseDN =dc=example,dc=com
+ldifFile =/net/install/dj/Example.ldif
+#sampleData =2000</programlisting>
+
+ <para>If you have multiple servers to install, consider scripting creation
+ of the properties files.</para>
+ </step>
+
+ <step>
+ <para>Prepare an installation script.</para>
+
+ <screen>$ cat /net/install/dj/1/setup.sh
+#!/bin/sh
+
+unzip -d /path/to /net/install/dj/OpenDJ-<?eval ${docTargetVersion}?>.zip && cd /path/to/opendj
+./setup --cli --propertiesFilePath /net/install/dj/1/setup.props \
+ --acceptLicense --no-prompt</screen>
+ </step>
+
+ <step>
+ <para>Run your installation script.</para>
+
+ <screen>$ /net/install/dj/1/setup.sh
+Archive: /net/install/dj/OpenDJ-<?eval ${docTargetVersion}?>.zip
+ creating: /path/to/opendj
+...
+ inflating: /path/to/opendj/setup
+ inflating: /path/to/opendj/uninstall
+ inflating: /path/to/opendj/upgrade
+
+READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
+THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
+BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
+TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.
+
+...
+
+Do you accept the License Agreement?yes
+See /var/folders/.../opendj-setup-....log for a detailed log of this operation.
+
+Configuring Directory Server ..... Done.
+Configuring Certificates ..... Done.
+Importing LDIF file /net/install/dj/Example.ldif ....... Done.
+Starting Directory Server ....... Done.
+
+To see basic server configuration status and configuration you can launch
+ /path/to/opendj/bin/status</screen>
+
+ <para>At this point you can use OpenDJ directory server, or you can perform
+ additional configuration.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="install-rest2ldap-servlet">
+ <title>To Install OpenDJ REST LDAP Gateway</title>
+ <indexterm><primary>REST LDAP gateway</primary></indexterm>
+
+ <para>The OpenDJ REST LDAP gateway functions as a web application in a web
+ application container, running independently of OpenDJ. Alternatively,
+ you can use the HTTP connection handler in OpenDJ directory server. See the
+ procedure, <link xlink:href="admin-guide#setup-rest2ldap-connection-handler"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>To Set Up REST
+ Access to OpenDJ Directory Server</citetitle></link>, for instructions.</para>
+
+ <para>You configure the gateway to access your directory service by editing
+ <filename>opendj-rest2ldap-servlet.json</filename> where you deploy the
+ gateway web application.</para>
+
+ <step>
+ <para>Deploy
+ <filename>opendj-rest2ldap-servlet-<?eval ${sdkDocTargetVersion}?>-servlet.war</filename>
+ according to the instructions for your application server.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>opendj-rest2ldap-servlet.json</filename> where you
+ deployed the gateway web application.</para>
+
+ <para>The default JSON resource for the configuration includes both
+ connection and authentication information, and also
+ <literal>mappings</literal>. The <literal>mappings</literal> describe how
+ the gateway translates between JSON and LDAP representations of your
+ data. The default <literal>mappings</literal> are built to work with
+ generated example data and also the sample content in <link xlink:show="new"
+ xlink:href="http://opendj.forgerock.org/Example.ldif"
+ >Example.ldif</link>.</para>
+
+ <para>At minimum, make sure that the host name and port numbers for
+ <literal>primaryLDAPServers</literal> are properly configured, that
+ <literal>authentication</literal> reflects the correct simple bind
+ credentials, and that the <literal>mappings</literal> for the endpoints
+ correctly match your directory data.</para>
+
+ <para>For details on the configuration, see <link
+ xlink:href="admin-guide#appendix-rest2ldap" xlink:show="new"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
+ Configuration</citetitle></link>.</para>
+
+ <para>When connecting to directory servers over LDAPS or LDAP and StartTLS,
+ you can configure the trust manager to use a file-based trust store for
+ server certificates that the gateway should trust. This allows the gateway to
+ validate server certificates signed for example by a Certificate Authority
+ not recognized by the Java environment when setting up LDAPS or StartTLS
+ connections. See <link xlink:show="new"
+ xlink:href="admin-guide#setup-server-cert"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Preparing For
+ Secure Communications</citetitle></link> for an example showing how to use
+ the <command>keytool</command> command to support a server certificate into
+ a trust store file.</para>
+ </step>
+
+ <step>
+ <para>Restart the REST LDAP gateway or the application server to make
+ sure the changes are taken into account.</para>
+ </step>
+
+ <step>
+ <para>Make sure that your directory server is running, and then check that
+ the gateway is connecting correctly.</para>
+
+ <para>The following command reads Babs Jensen's entry through the gateway
+ to the backend holding data from <filename>Example.ldif</filename>.</para>
+
+ <screen
+ >$ curl http://bjensen:hifalutin@opendj.example.com:8080/rest2ldap/users/bjensen
+ ?_prettyPrint=true
+{
+ "_rev" : "000000002ee3b764",
+ "schemas" : [ "urn:scim:schemas:core:1.0" ],
+ "contactInformation" : {
+ "telephoneNumber" : "+1 408 555 1862",
+ "emailAddress" : "bjensen@example.com"
+ },
+ "_id" : "bjensen",
+ "name" : {
+ "familyName" : "Jensen",
+ "givenName" : "Barbara"
+ },
+ "userName" : "bjensen@example.com",
+ "displayName" : "Barbara Jensen",
+ "manager" : [ {
+ "_id" : "trigden",
+ "displayName" : "Torrey Rigden"
+ } ]
+}</screen>
+
+ <para>If you generated example data, Babs Jensen's entry is not included.
+ Try a URL such as
+ <literal>http://user.0:password@opendj.example.com:8080/rest2ldap/users/user.0</literal>
+ instead.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="install-dsml-gateway">
+ <title>To Install OpenDJ DSML gateway</title>
+ <indexterm><primary>DSML gateway</primary></indexterm>
+
+ <para>The OpenDJ DSML gateway functions as a web application located in a
+ web application container. The DSML gateway runs independently of OpenDJ
+ directory server. You configure the gateway to access your directory service
+ by editing the <literal>ldap.host</literal> and <literal>ldap.port</literal>
+ parameters in the <filename>WEB-INF/web.xml</filename> configuration
+ file.</para>
+
+ <step>
+ <para>Deploy <filename>OpenDJ-<?eval ${docTargetVersion}?>-DSML.war</filename>
+ according to the instructions for your application server.</para>
+ </step>
+
+ <step>
+ <para>Edit <filename>WEB-INF/web.xml</filename> to ensure the values for
+ <literal>ldap.host</literal> and <literal>ldap.port</literal> are
+ correct.</para>
+ </step>
+
+ <step>
+ <para>Restart the web application container according to the instructions
+ for your application server.</para>
+ </step>
+ </procedure>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-gui.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-gui.xml
new file mode 100644
index 0000000..56b46de
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-install-gui.xml
@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-install-gui'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Installing OpenDJ With the QuickSetup Wizard</title>
+ <indexterm><primary>Downloading OpenDJ</primary></indexterm>
+ <indexterm><primary>Quick install</primary></indexterm>
+
+ <para>If you want only to try OpenDJ server software, and you do not plan to
+ store any real or important data that you want to keep, then read only this
+ chapter, or just try out installation without reading any further.</para>
+
+ <xinclude:include href="../shared/itemizedlist-download.xml" />
+
+ <para>QuickSetup uses Java WebStart to let you perform an installation of
+ OpenDJ directory server starting with a click in your web browser, which can
+ be a great way to try OpenDJ directory server for the first time, or to do a
+ quick test installation.</para>
+
+ <note>
+ <para>OpenDJ directory server relies on Java 6 or later, so if your browser
+ picks up an old installation of Java 5 for example, installation can
+ fail. You might see an application error message such as this:</para>
+
+ <mediaobject xml:id="figure-missing-java6">
+ <alt>Application error due to old Java version</alt>
+ <imageobject>
+ <imagedata fileref="images/missing-java6.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>Message showing the browser is unable to launch the application</para>
+ </textobject>
+ </mediaobject>
+ </note>
+
+ <para>If the WebStart installation does not work in your browser, copy
+ the WebStart URL, ending in <literal>QuickSetup.jnlp</literal>, from the
+ OpenDJ download page. Next, pass the link as an argument to the
+ <command>javaws</command> command in a terminal window to start the
+ installer.</para>
+
+ <screen>$ export PATH=/path/to/java/bin:$PATH
+$ javaws <replaceable>URL-to-QuickSetup-Installer</replaceable></screen>
+
+ <para>The WebStart installer corresponds to what you start if you download
+ OpenDJ-<?eval ${docTargetVersion}?>.zip, unzip the file, and then run
+ <command>opendj/setup</command> (UNIX), <command>opendj\setup.bat</command>
+ (Windows), or <command>opendj/QuickSetup.app</command> (Mac OS X).</para>
+
+ <para>Java WebStart launches the the QuickSetup wizard, and soon the
+ Welcome screen appears.</para>
+
+ <mediaobject xml:id="figure-quicksetup-welcome">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-welcome.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>The Welcome screen summarizes the setup process.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-license">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-license.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>Accept the license to install OpenDJ directory server if QuickSetup
+ presents a license text.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-svrconf">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-svrconf.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>In the Server Settings screen that the default ports
+ are 389 or 1389 for LDAP, 4444 for administrative access.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-replopts">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-replopts.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>You can replicate data for high availability through the
+ Topology Options screen.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-gendata">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-gendata.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>You can generate test data as part of server setup in the Directory
+ Data screen.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-jvmopts">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-jvmopts.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>For a real installation, you can adjust JVM parameters for
+ your server, for example to allow OpenDJ to use more memory.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-review">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-review.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>You can opt to start your server when setup completes.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-finished">
+ <imageobject>
+ <imagedata fileref="images/QuickSetup-finished.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>Click the Launch Control Panel button to check your newly
+ installed server.</para>
+ </textobject>
+ </mediaobject>
+
+ <mediaobject xml:id="figure-quicksetup-control-panel">
+ <imageobject>
+ <imagedata fileref="images/OpenDJ-Control-Panel.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>OpenDJ Control Panel offers basic administration capabilities.</para>
+ </textobject>
+ </mediaobject>
+
+ <itemizedlist>
+ <para>To launch OpenDJ Control Panel again later, you can run one of the
+ following, depending on your host system.</para>
+
+ <listitem>
+ <para>(Mac OS X) <command>opendj/bin/ControlPanel.app</command></para>
+ </listitem>
+ <listitem>
+ <para>(UNIX) <command>opendj/bin/control-panel</command></para>
+ </listitem>
+ <listitem>
+ <para>(Windows) <command>opendj\bat\control-panel.bat</command></para>
+ </listitem>
+ </itemizedlist>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-jvm-opts.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-jvm-opts.xml
new file mode 100644
index 0000000..0fb52c9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-jvm-opts.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-jvm-opts'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Tuning JVM Options</title>
+
+ <para>By default, OpenDJ installs with options appropriate for evaluation, not
+ for production.</para>
+
+ <indexterm><primary>Java</primary><secondary>Settings</secondary></indexterm>
+
+ <variablelist>
+ <para>You can change JVM options for the server in the QuickStart installer,
+ and alternatively using the Control Panel (Runtime Options > Java Settings),
+ or with the <command>dsjavaproperties</command> command after editing the
+ <filename>config/java.properties</filename> file.</para>
+
+ <varlistentry>
+ <term>Heap size</term>
+ <listitem>
+ <para>The JVM heap size by default is either 256 MB or 1 GB.</para>
+ <para>In production, use at least a 2 GB heap (-Xms2G -Xmx2G).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Server optimizations</term>
+ <listitem>
+ <para>Use -server to select the HotSpot Server VM.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>32-bit vs. 64-bit</term>
+ <listitem>
+ <para>For heap sizes over 4 GB on 64-bit systems use -d64.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Garbage collection</term>
+ <listitem>
+ <para>Use -XX:+UseConcMarkSweepGC to select the CMS garbage collector
+ for low GC pause times.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>New generation size</term>
+ <listitem>
+ <para>If your directory handles high throughput, set the new generation
+ size large enough for the JVM to avoid promoting short-lived objects
+ into the old gen space (-XX:NewSize=512M).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-uninstall.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-uninstall.xml
new file mode 100644
index 0000000..7a44a73
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-uninstall.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-uninstall'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Removing OpenDJ Servers</title>
+ <indexterm><primary>Uninstalling</primary></indexterm>
+
+ <para>Remove OpenDJ directory server software with the
+ <command>uninstall</command> command.</para>
+
+ <procedure xml:id="uninstall-gui">
+ <title>To Uninstall OpenDJ From the Graphical Uninstaller</title>
+ <step>
+ <para>(UNIX) Run <command>opendj/uninstall</command>.</para>
+ <para>(Windows) Double-click <filename>opendj\uninstall.bat</filename>.</para>
+ <para>(Mac OS X) Double-click <filename>opendj/Uninstall.app</filename>.</para>
+
+ <mediaobject xml:id="figure-uninstall-start">
+ <imageobject>
+ <imagedata fileref="images/uninstall-start.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>Select what to remove in the initial screen.</para>
+ </textobject>
+ </mediaobject>
+ </step>
+
+ <step>
+ <para>When the process is finished, you might still have some files
+ to remove manually.</para>
+
+ <mediaobject xml:id="figure-uninstall-finished">
+ <imageobject>
+ <imagedata fileref="images/uninstall-finished.png" format="PNG" />
+ </imageobject>
+ <textobject>
+ <para>The final screen indicates what must be removed manually.</para>
+ </textobject>
+ </mediaobject>
+ </step>
+ </procedure>
+
+ <procedure xml:id="uninstall-cli">
+ <title>To Uninstall OpenDJ On the Command Line</title>
+
+ <step>
+ <para>Login as the user who installed and runs the server.</para>
+ </step>
+
+ <step>
+ <para>Run the <command>opendj/uninstall --cli</command> command.</para>
+
+ <para>This command starts the removal program in interactive mode on the
+ command line, prompting you for each option. Alternatively, use additional
+ <command>uninstall</command> options to specify choices for the options.
+ See <command>uninstall --help</command> for more information.</para>
+
+ <screen>$ cd /path/to/opendj
+$ ./uninstall --cli
+Do you want to remove all components of the server or select the components to
+remove?
+
+ 1) Remove all components
+ 2) Select the components to be removed
+
+ q) quit
+
+Enter choice [1]:
+
+The server is currently running and must be stopped before uninstallation can
+continue.
+Stop the Server and permanently delete the files? (yes / no) [yes]:
+
+Stopping Directory Server ..... Done.
+Deleting Files under the Installation Path ..... Done.
+
+The Uninstall Completed Successfully.
+To complete the uninstallation, you must delete manually the following files
+and directories:
+/path/to/opendj/lib
+See /var/....log for a detailed log of this operation.</screen>
+ </step>
+
+ <step>
+ <para>If the command output tells you to delete files manually, then remove
+ those remaining files to complete the process.</para>
+
+ <screen>$ rm -rf /path/to/opendj</screen>
+ </step>
+ </procedure>
+
+ <procedure xml:id="uninstall-deb">
+ <title>To Uninstall the Debian Package</title>
+ <indexterm><primary>Debian (.deb) package</primary></indexterm>
+
+ <para>When you uninstall the Debian package from the command line, OpenDJ
+ directory server is stopped if it is running.</para>
+
+ <step>
+ <para>Remove the package from your system.</para>
+
+ <screen>$ sudo dpkg -r opendj
+(Reading database ... 185725 files and directories currently installed.)
+Removing opendj ...
+*Stopping OpenDJ server...
+Stopping Server...
+[03/Jun/2013:10:00:49 +0200] category=BACKEND severity=NOTICE
+ msgID=9896306 msg=The backend userRoot is now taken offline
+[03/Jun/2013:10:00:49 +0200] category=CORE severity=NOTICE
+ msgID=458955 msg=The Directory Server is now stopped
+
+*OpenDJ successfully removed
+
+$ </screen>
+
+ <para>Removing the package does not remove your data or configuration.
+ You must remove <filename>/opt/opendj</filename> manually to get rid of
+ all files.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="uninstall-rpm">
+ <title>To Uninstall the RPM Package</title>
+ <indexterm><primary>Red Hat (.rpm) package</primary></indexterm>
+
+ <para>When you uninstall the RPM package from the command line, OpenDJ
+ directory server is stopped if it is running.</para>
+
+ <step>
+ <para>Remove the package from your system.</para>
+
+ <screen># rpm -e opendj
+Pre Uninstall - uninstall
+Stopping Server...
+[03/Jun/2013:10:42:46 +0200] category=BACKEND severity=NOTICE
+ msgID=9896306 msg=The backend userRoot is now taken offline
+[03/Jun/2013:10:42:46 +0200] category=CORE severity=NOTICE
+ msgID=458955 msg=The Directory Server is now stopped
+Post Uninstall - uninstall
+OpenDJ successfully removed.
+# </screen>
+
+ <para>Removing the package does not remove your data or configuration.
+ You must remove <filename>/opt/opendj</filename> manually to get rid of
+ all files.</para>
+ </step>
+ </procedure>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-upgrade.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-upgrade.xml
new file mode 100644
index 0000000..7206379
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/chap-upgrade.xml
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-upgrade'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Upgrading to OpenDJ <?eval ${docTargetVersion}?></title>
+ <indexterm><primary>Upgrading</primary></indexterm>
+
+ <para>This chapter covers upgrade from OpenDJ 2.4.5 and later versions.</para>
+
+ <para>For upgrades from earlier versions, upgrade first to at least OpenDJ
+ 2.4.5, and then follow the procedures in this chapter. See <link xlink:show="new"
+ xlink:href="https://wikis.forgerock.org/confluence/display/OPENDJ/OpenDJ+Installation+Guide#OpenDJInstallationGuide-UpgradingOpenDJDirectoryServer"
+ >Upgrading OpenDJ Directory Server</link> in the OpenDJ Wiki for details on
+ upgrading to OpenDJ 2.4.5 from earlier versions.</para>
+
+ <procedure xml:id="before-you-upgrade">
+ <title>Before You Upgrade</title>
+
+ <step>
+ <para>Prepare to perform the upgrade procedure as the user who owns the
+ OpenDJ server files. </para>
+
+ <para>Make sure you have the credentials to run commands as the user who
+ owns the server.</para>
+ </step>
+
+ <step>
+ <xinclude:include href="../shared/itemizedlist-download.xml" />
+ </step>
+
+ <step>
+ <para>In order to revert if the upgrade fails, make sure you perform a
+ full backup of your current OpenDJ installation.</para>
+
+ <para>It might be most expedient to back up the file system directory where
+ the current OpenDJ server is installed as part of the upgrade process.</para>
+
+ <para>Alternatively, see <link xlink:href="admin-guide#chap-backup-restore"
+ xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
+ ><citetitle>Backing Up & Restoring Data</citetitle></link> for
+ instructions.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="upgrade-zip">
+ <title>To Upgrade an OpenDJ Directory Server</title>
+
+ <para>To upgrade OpenDJ directory server installed from native packages (.deb,
+ .rpm), use the command-line package management tools provided by the system.</para>
+
+ <para>The following steps describe how to upgrade OpenDJ directory server
+ installed from the cross-platform (.zip) delivery.</para>
+
+ <step>
+ <para>Login as the user who owns the current OpenDJ server.</para>
+ </step>
+
+ <step>
+ <para>Stop the current OpenDJ server.</para>
+ </step>
+
+ <step performance="optional">
+ <para>If you have not already backed up the current OpenDJ server, make a
+ back up copy of the directory where OpenDJ is installed.</para>
+ </step>
+
+ <step performance="optional">
+ <para>If OpenDJ is currently installed in a directory such as
+ <filename>OpenDJ-2.4.5</filename>, you can change the directory name to
+ <filename>opendj</filename> to make it easier to unpack subsequent .zip
+ deliveries for future upgrades.</para>
+ </step>
+
+ <step>
+ <para>Unpack the new files from the .zip delivery over the current server
+ files.</para>
+
+ <para>If your directory is not named <filename>opendj</filename>, then
+ you can first unpack the files, then copy everything in the
+ <filename>opendj</filename> over the current server files.</para>
+ </step>
+
+ <step>
+ <para>Run the <command>upgrade</command> command to bring OpenDJ
+ configuration and application data up to date with the new binary and
+ script files that you copied over the current server files.</para>
+
+ <para>By default, the <command>upgrade</command> command requests
+ confirmation before making important configuration changes. You can use
+ the <option>--no-prompt</option> option to run the command
+ non-interactively, with the <option>--acceptLicense</option> option to
+ accept the license terms non-interactively.</para>
+
+ <para>When using the <option>--no-prompt</option> option, if the
+ <command>upgrade</command> command 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 <option>--force</option> option to force a non-interactive upgrade
+ to continue in this case, also performing long running and critical
+ tasks.</para>
+ </step>
+
+ <step>
+ <para>When you upgrade from OpenDJ 2.5.0-Xpress1, you must rebuild the
+ <literal>ds-sync-hist</literal> ordering index before you restart the
+ server, as indicated in the message from the upgrade tool.</para>
+
+ <programlisting language="none"
+> OpenDJ 2.5.0-Xpress1 introduced a regression in the ds-sync-hist ordering
+ index. This index must be rebuilt after the upgrade has completed and before
+ restarting OpenDJ. Do you wish to continue? (yes/no) [no]: yes</programlisting>
+
+ <para>To rebuild the index, use the <command>rebuild-index</command>
+ command after upgrade but before starting the server as in the following
+ example.</para>
+
+ <screen>$ ./opendj/bin/rebuild-index --baseDN dc=example,dc=com --index ds-sync-hist
+... msg=Rebuild of index(es) ds-sync-hist started ...
+... msg=Rebuild complete. Processed XXX entries in YYY seconds...</screen>
+ </step>
+
+ <step>
+ <para>Start the upgraded OpenDJ server.</para>
+
+ <para>At this point the upgrade process is complete. See the resulting
+ <filename>upgrade.log</filename> file for a full list of operations
+ performed.</para>
+ </step>
+ </procedure>
+
+ <example xml:id="upgrade-zip-example"><?dbfo keep-together="auto"?>
+ <title>Upgrading From OpenDJ 2.4.5</title>
+
+ <para>The following example upgrades an OpenDJ 2.4.5 directory server
+ installed in <filename>/path/to/OpenDJ-2.4.5</filename>, backing up the
+ current server directory in case the upgrade process fails, and changing
+ the directory name to <filename>/path/to/opendj</filename> to simplify
+ future upgrades.</para>
+
+ <xinclude:include href="../shared/screen-upgrade.xml" />
+ </example>
+
+ <procedure xml:id="upgrade-repl">
+ <title>To Upgrade Replicated Servers</title>
+ <step>
+ <para>Upgrade each server sequentially, as described above.</para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="upgrade-dsml">
+ <title>To Upgrade OpenDJ DSML Gateway</title>
+ <step>
+ <para>Replace the gateway web application with the newer version,
+ as for a fresh installation.</para>
+ </step>
+ </procedure>
+
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/OpenDJ-Control-Panel.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/OpenDJ-Control-Panel.png
new file mode 100644
index 0000000..a227df7
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/OpenDJ-Control-Panel.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-finished.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-finished.png
new file mode 100644
index 0000000..fbedbe6
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-finished.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-gendata.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-gendata.png
new file mode 100644
index 0000000..2d8ae38
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-gendata.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-jvmopts.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-jvmopts.png
new file mode 100644
index 0000000..ed5aeb2
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-jvmopts.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-license.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-license.png
new file mode 100644
index 0000000..9304569
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-license.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-replopts.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-replopts.png
new file mode 100644
index 0000000..51dab98
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-replopts.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-review.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-review.png
new file mode 100644
index 0000000..0925ad9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-review.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-svrconf.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-svrconf.png
new file mode 100644
index 0000000..cec86af
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-svrconf.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-welcome.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-welcome.png
new file mode 100644
index 0000000..ceef256
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/QuickSetup-welcome.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/missing-java6.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/missing-java6.png
new file mode 100644
index 0000000..fb03bb0
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/missing-java6.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-finished.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-finished.png
new file mode 100644
index 0000000..a176a4a
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-finished.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-start.png b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-start.png
new file mode 100644
index 0000000..cb21761
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/images/uninstall-start.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/index.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/index.xml
new file mode 100644
index 0000000..a1bc761
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/index.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2014 ForgeRock AS
+ !
+-->
+<book xml:id='install-guide'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info>
+ <xinclude:include href="../shared/mediaobject-fr-logo.xml" />
+ <title>OpenDJ Installation Guide</title>
+ <subtitle>Version ${docTargetVersion}</subtitle>
+ <abstract>
+ <para>This guide shows you how to install OpenDJ directory services. The
+ OpenDJ project offers open source LDAP directory services in Java.</para>
+ </abstract>
+ <copyright>
+ <year>2011-2014</year>
+ <holder>ForgeRock AS</holder>
+ </copyright>
+ <authorgroup>
+ <author>
+ <personname><firstname>Mark </firstname><surname>Craig</surname></personname>
+ <xinclude:include href="../shared/affiliation-fr.xml"/>
+ </author>
+ </authorgroup>
+ <xinclude:include href='../legal.xml' />
+ <date>${publicationDate}</date>
+ <pubdate>${publicationDate}</pubdate>
+ <releaseinfo>${softwareReleaseDate}</releaseinfo>
+ </info>
+
+ <toc />
+
+ <xinclude:include href="preface.xml" />
+
+ <xinclude:include href='chap-install-gui.xml' />
+ <xinclude:include href='chap-install-cli.xml' />
+ <xinclude:include href='chap-jvm-opts.xml' />
+ <xinclude:include href='chap-upgrade.xml' />
+ <xinclude:include href='chap-uninstall.xml' />
+
+ <index />
+</book>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/install-guide/preface.xml b/opendj-doc-generated-ref/src/main/docbkx/install-guide/preface.xml
new file mode 100644
index 0000000..20bc903
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/install-guide/preface.xml
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<preface xml:id='preface'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Preface</title>
+
+ <para>This guide shows you how to install, upgrade, and remove OpenDJ
+ software. Unless you are planning a throwaway evaluation or test
+ installation, read the <link xlink:href="release-notes#release-notes"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Release
+ Notes</citetitle></link> before you get started.</para>
+
+ <para>If you want only to try OpenDJ server software, and you
+ do not plan to store any real or important data that you want to keep,
+ then you need not read this entire guide. Instead, try <link
+ xlink:href="install-guide#chap-install-gui"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing OpenDJ
+ With the QuickSetup Wizard</citetitle></link>.</para>
+
+ <section>
+ <title>Who Should Read this Guide</title>
+
+ <para>This guide is written for anyone installing OpenDJ who plans to
+ maintain directory services for client applications. Basic OpenDJ
+ installation, especially using Java WebStart, can be simple and
+ straightforward, particularly if you are already acquainted with directory
+ services. Upgrading a running directory service without a single point of
+ failure that can cause downtime requires at least a little thought
+ and planning. Also, even in the case of basic installation, you may
+ find yourself wanting more background about what you are doing.</para>
+
+ <para>This guide covers the install, upgrade, and removal (a.k.a. uninstall)
+ procedures that you theoretically perform only once per version. This guide
+ aims to provide you with at least some idea of what happens behind the
+ scenes when you perform the steps.</para>
+
+ <para>You do not need to be an LDAP wizard to learn something from this
+ guide, though a background in directory services and maintaining server
+ software can help. You do need some background in managing servers and
+ services on your operating system of choice. You can nevertheless get
+ started with this guide, and then learn more as you go along.</para>
+ </section>
+
+ <xinclude:include href="../shared/sec-formatting-conventions.xml" />
+ <xinclude:include href="../shared/sec-accessing-doc-online.xml" />
+ <xinclude:include href="../shared/sec-joining-the-community.xml" />
+</preface>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-before-you-install.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-before-you-install.xml
new file mode 100644
index 0000000..813e374
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-before-you-install.xml
@@ -0,0 +1,275 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-before-you-install'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>Before You Install OpenDJ Software</title>
+
+ <note>
+ <para>
+ This chapter has not changed since the release of OpenDJ 2.6.2.
+ </para>
+ </note>
+
+ <para>This chapter covers requirements to consider before you run OpenDJ,
+ especially before you run OpenDJ in your production environment.</para>
+
+ <note xml:id="requirements-changes">
+ <para>
+ OpenDJ 2.6.2 adds support for Java 8.
+ </para>
+ </note>
+
+ <para>If you have a special request to support a combination not listed here,
+ contact ForgeRock at <link xlink:href='mailto:info@forgerock.com'
+ >info@forgerock.com</link>.</para>
+
+ <section xml:id="prerequisites-java">
+ <title>Java Environment</title>
+ <indexterm>
+ <primary>Java</primary>
+ <secondary>Requirements</secondary>
+ </indexterm>
+
+ <para>OpenDJ software consists of pure Java applications. OpenDJ servers
+ and clients therefore should run on any system with full Java support.
+ OpenDJ is tested on a variety of operating systems, including Solaris
+ SPARC and x86, various Linux distributions, Microsoft Windows,
+ and Apple Mac OS X.</para>
+
+ <para>OpenDJ software requires Java 6, 7 or 8, specifically at least the Java
+ Standard Edition runtime environment. ForgeRock has tested most with Oracle
+ Java Platform, Standard Edition.</para>
+
+ <para>ForgeRock recommends that you keep your Java installation up to date
+ with the latest security fixes.</para>
+
+ <para>To build applications with the OpenDJ LDAP SDK, you need the
+ corresponding Java SDK.</para>
+ </section>
+
+ <section xml:id="prerequisites-file-descriptors">
+ <title>Maximum Open Files</title>
+ <indexterm>
+ <primary>File descriptors</primary>
+ <secondary>Requirements</secondary>
+ </indexterm>
+
+ <para>OpenDJ needs to be able to open many files, especially when handling
+ many client connections. Linux systems in particular often set a limit of
+ 1024 per user, which is too low for OpenDJ.</para>
+
+ <para>When setting up OpenDJ for production use, make sure OpenDJ can use
+ at least use at least 64K (65536) file descriptors. For example when running
+ OpenDJ as user <literal>opendj</literal> on a Linux system that uses
+ <filename>/etc/security/limits.conf</filename> to set user level limits,
+ you can set soft and hard limits by adding these lines to the file.</para>
+
+ <programlisting language="none">opendj soft nofile 65536
+opendj hard nofile 131072</programlisting>
+
+ <para>The example above assumes the system has enough file descriptors
+ available overall. You can check the Linux system overall maximum as
+ follows.</para>
+
+ <screen>$ cat /proc/sys/fs/file-max
+204252</screen>
+ </section>
+
+ <section xml:id="prerequisites-operating-systems">
+ <title>Operating System</title>
+ <indexterm>
+ <primary>Operating systems</primary>
+ <secondary>Requirements</secondary>
+ </indexterm>
+
+ <para>OpenDJ software depends on the Java environment more than it depends
+ on the underlying operating system. That said, OpenDJ
+ <?eval ${docTargetVersion}?> has been validated on the following operating
+ systems.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Apple Mac OS X 10.7, 10.8</para>
+ </listitem>
+ <listitem>
+ <para>Linux 2.6 and later</para>
+ </listitem>
+ <listitem>
+ <para>Microsoft Windows Server 2008 R2 and Windows Server 2012</para>
+ </listitem>
+ <listitem>
+ <para>Oracle Solaris 11 x86</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In order to avoid directory database file corruption after crashes or
+ power failures on Linux systems, enable file system write barriers and make
+ sure that the file system journaling mode is ordered. For details on how to
+ enable write barriers and how to set the journaling mode for data, see the
+ options for your file system in the <command>mount</command> command manual
+ page.</para>
+ </section>
+
+ <section xml:id="prerequisites-virtualization">
+ <title>Virtualization</title>
+ <indexterm>
+ <primary>Virtualization</primary>
+ <secondary>Requirements</secondary>
+ </indexterm>
+
+ <para>ForgeRock has tested OpenDJ software on systems running atop VMware
+ vSphere Hypervisor (ESXi) 5.1.</para>
+ </section>
+
+ <section xml:id="prerequisites-application-servers">
+ <title>Application Servers</title>
+ <indexterm>
+ <primary>Application servers</primary>
+ <secondary>Requirements</secondary>
+ </indexterm>
+
+ <para>OpenDJ directory server runs as a standalone Java service, and
+ does not depend on an application server.</para>
+
+ <para>OpenDJ DSML gateway has been validated on Apache Tomcat 6 and 7.</para>
+
+ <para>
+ OpenDJ REST LDAP gateway has been validated on Apache Tomcat 6 and Jetty 8.
+ Using Jetty 8 is not supported with Java 8.
+ </para>
+ </section>
+
+ <section xml:id="prerequisites-fqdn">
+ <title>FQDNs For Replication</title>
+
+ <indexterm><primary>Fully qualified domain name requirements</primary></indexterm>
+ <para>OpenDJ replication requires that you use fully qualified domain names,
+ such as <literal>opendj.example.com</literal>.</para>
+
+ <para>Although you can use host names like <literal>my-laptop.local</literal>
+ for evaluation, in production and even in your lab, you must either ensure
+ DNS is set up correctly to provide fully qualified domain names, or set up
+ <filename>/etc/hosts</filename> (or
+ <filename>C:\Windows\System32\drivers\etc\hosts</filename>) to provide
+ fully qualified domain names.</para>
+ </section>
+
+ <section xml:id="prerequisites-hardware">
+ <title>Hardware</title>
+
+ <para>Thanks to the underlying Java platform, OpenDJ software runs well
+ on a variety of processor architectures. Many directory service
+ deployments meet their service-level agreements without the very latest
+ or very fastest hardware.</para>
+
+ <indexterm><primary>Memory requirements</primary></indexterm>
+ <para>For a server evaluation installation, you need 256 MB memory (32-bit)
+ or 1 GB memory (64-bit) available to OpenDJ, with 100 MB free disk space for
+ the software and a small set of sample data. For installation in production,
+ read the rest of this section. You need at least 2 GB memory for OpenDJ and
+ 4 times the disk space needed to house initial production data in LDIF
+ format.<footnote>
+ <para>OpenDJ stores data in Berkeley DB Java Edition, which is implemented
+ as a rolling log. Berkeley DB appends updates to the end of the last log
+ file, and marks old pages as deleted. Berkeley DB cleaner threads monitor
+ the log file occupancy ratio, moving the data to get rid of old log files.
+ Yet, with the default occupancy ratio of 50%, log files are cleaned only
+ when they have less than 50% valid pages. As a result, the database can
+ reach twice its initial size in the worst case.</para>
+ <para>Furthermore, when you import data from LDIF, OpenDJ stores not only
+ the data, but also builds indexes for many of the attributes, resulting in
+ some growth. Replication historical data and other operational attributes
+ can also take up space.</para>
+ <para>Finally, it makes sense to leave space for growth in the database size
+ as you modify and add entries over time.</para></footnote>
+ To get a more accurate estimate of the disk space needed, import a known
+ fraction of the initial LDIF with OpenDJ configured as for production, run
+ tests based on the estimated rates of change and growth in directory data,
+ and then use the actual space used in the test environment to estimate how
+ much disk space you need in production.</para>
+
+ <para>OpenDJ directory servers almost always benefit from having enough
+ system memory to cache all directory database files used. The reason
+ is that reading from and writing to memory is typically much faster
+ than reading from and writing to disk storage. For small data sets,
+ you might not need extra memory. For large directories with millions of
+ user directory entries, the system might not have enough slots to house
+ sufficient memory to cache everything. To improve performance in such
+ cases, one approach is to add solid state drives as an intermediate
+ cache between memory and disk storage.</para>
+
+ <para>Processor architectures that provide fast single thread execution
+ tend to help OpenDJ software deliver the lowest response times. For top end
+ performance in terms both of sub-millisecond response times and also
+ of throughput ranging from tens of thousands to hundreds of thousands
+ of operations per second, the latest x86/x64 architecture chips tend to
+ perform better than others tested. Chip multi-threading (CMT) processors
+ can do very well on directory servers providing pure search throughput,
+ even though response times can be higher. Yet, CMT processors can be slow
+ to absorb hundreds or thousands of write operations per second. Their
+ slower threads get blocked waiting on resources, and thus are not optimal
+ for topologies with high write throughput requirements.</para>
+
+ <indexterm><primary>Network requirements</primary></indexterm>
+ <para>On systems with fast processors and enough memory to cache directory
+ data completely, the network can become a bottleneck. Even if a single
+ 1 Gbit Ethernet interface offers plenty of bandwidth to handle your
+ average traffic load, it can be too small for peak traffic loads.
+ Furthermore, you might choose to use separate interfaces for
+ administrative traffic and application traffic. To estimate what network
+ hardware you need, calculate the size of the data you return to
+ applications during peak load. For example, if you expect to have a
+ peak load of 100,000 searches per second, each returning a full 8 KB
+ entry, you need a network that can handle 800 MB/sec (3.2 Gbit/sec)
+ throughput, not counting any other operations such as writes that
+ result in replication traffic.</para>
+
+ <indexterm><primary>Storage requirements</primary></indexterm>
+ <para>The storage hardware you choose must allow you to house not only
+ directory data including historical data for replication, but also
+ logs. If you choose to retain access logs for auditing purposes on a
+ heavily used directory, dedicate storage for the log archives as well.
+ Furthermore, your storage must also keep pace with the write
+ throughput. Write throughput can arise from modify, modify DN, add,
+ and delete operations, but it can also result from bind operations.
+ Such is the case when the last successful bind is recorded, and when
+ account lockout is configured, for example. In a replicated topology,
+ not only does a directory service write entries to disk when they are
+ changed, but a directory service also writes changelog data and
+ historical information in order to resolve potential replication
+ conflicts. You base your network throughput needs on peak loads. Also
+ base your storage throughput needs on peak loads.</para>
+
+ <note>
+ <para>OpenDJ servers do not currently support network file systems such
+ as NFS for database storage. Provide sufficient disk space on local storage
+ such as internal disk or an attached disk array.</para>
+ </note>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-compatibility.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-compatibility.xml
new file mode 100644
index 0000000..5d3a04b
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-compatibility.xml
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-compatibility'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>OpenDJ Compatibility</title>
+
+ <para>This chapter covers both major changes to existing functionality, and
+ also deprecated and removed functionality.</para>
+
+ <note xml:id="compatibility-not-changed">
+ <para>
+ No incompatible changes have been made since OpenDJ ${stableServerVersion}.
+ This chapter reflects changes made in version ${stableServerVersion}.
+ </para>
+ </note>
+
+ <section xml:id="changed-functionality">
+ <title>Important Changes to Existing Functionality</title>
+
+ <para>OpenDJ <?eval ${stableServerVersion}?> improves on earlier releases
+ introducing many new features. Also take the following into account.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The upgrade process and <command>upgrade</command> command have
+ changed to facilitate native packaging on more platforms.
+ See <link xlink:show="new"
+ xlink:href="https://backstage.forgerock.com/#!/docs/opendj/2.6.0/install-guide#chap-upgrade"
+ ><citetitle>Upgrading to OpenDJ ${stableServerVersion}</citetitle></link>
+ for instructions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The default DB cache size is now 50%, rather than 10%.</para>
+ <para>If you have multiple backends, configure cache sizes
+ accordingly.</para>
+ </listitem>
+
+ <listitem>
+ <para>The number of LDAP request handlers now defaults to half the CPU
+ count.</para>
+ </listitem>
+
+ <listitem>
+ <para>The replication purge delay default has increased from one day to
+ three days.</para>
+ </listitem>
+
+ <listitem>
+ <para>Syntax checking has been added for certificate and country attribute
+ values. This affects applications updating those attribute values.
+ Applications updating country attribute values must now use Country String
+ syntax for example, which uses two-character codes from <link
+ xlink:show="new" xlink:href="http://www.iso.org/iso/country_codes.htm">ISO
+ 3166</link> such as <literal>US</literal> instead of full names such as
+ <literal>United States</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The following global ACI settings have changed.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>OpenDJ directory server now allows any client to use the LDAP
+ Permissive Modify Request control, <literal>1.2.840.113556.1.4.1413</literal>,
+ by default for newly installed servers.</para>
+ </listitem>
+
+ <listitem>
+ <para>The "Anonymous read access" global ACI has changed. The list of
+ attributes that are not allowed has been changed to add
+ <literal>includedAttributes</literal> and to remove
+ <literal>targetUniqueID</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>When you upgrade from earlier versions of OpenDJ, however, the
+ previous <literal>global-aci</literal> settings are not updated. To apply
+ the changes manually, change the relevant <literal>global-aci</literal>
+ settings by using the <command>dsconfig</command> command. An example of
+ how to change a <literal>global-aci</literal> property can be found in the
+ <citetitle>Administration Guide</citetitle>, <link xlink:show="new"
+ xlink:href="https://backstage.forgerock.com/#!/docs/opendj/2.6.0/admin-guide#access-control-disable-anonymous"
+ ><citetitle>ACI: Disable Anonymous Access</citetitle></link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>For the SNMP Connection Handler, the default
+ <literal>security-agent-file</literal> has changed to
+ <filename>opendj-snmp.security</filename> (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-982"
+ >OPENDJ-982</link>), and the upgrade process changes the file name. The
+ <literal>community</literal> has also changed to <literal>OpenDJ</literal>.
+ If the SNMP Connection Handler fails to start after upgrade, use the
+ <command>dsconfig</command> command to make sure that the
+ <literal>security-agent-file</literal> property is correctly set for your
+ installation.</para>
+ </listitem>
+ </itemizedlist>
+
+<!-- Not yet for OpenDJ 2.6.0.
+ <para>The <command>ldif-diff</command> command has been renamed
+ <command>ldifdiff</command>, and the <option>-\-outputLDIF</option>,
+ <option>-\-overwriteExisting</option>, <option>-\-sourceLDIF</option>,
+ <option>-\-targetLDIF</option> options have been dropped in favor of a
+ format closer to that of the <command>diff</command> command.</para>
+-->
+ </section>
+
+ <section xml:id="deprecated-functionality">
+ <title>Deprecated Functionality</title>
+
+ <para>
+ Support for Java 6 is deprecated and likely to be removed in a future release.
+ </para>
+
+ <para>OpenDJ ${stableServerVersion} makes use of new environment
+ variables aligned with the project name to use <literal>OPENDJ</literal>.
+ Use of the old variables is Deprecated. The old variables are likely to be
+ removed in a future release.</para>
+
+ <para>The <command>dsframework</command> command is Deprecated and likely
+ to be removed in a future release.</para>
+
+ <para>
+ The next major version of OpenDJ LDAP SDK includes
+ improvements and changes that are not compatible with the 2.x SDK.
+ </para>
+ </section>
+
+ <section xml:id="removed-functionality">
+ <title>Removed Functionality</title>
+
+ <para>Native packages in SVR4 format for Solaris are not provided at this
+ time.</para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-feedback.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-feedback.xml
new file mode 100644
index 0000000..771bae2
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-feedback.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2014 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-feedback'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>How to Report Problems & Provide Feedback</title>
+
+ <para>If you have questions regarding OpenDJ which are not answered by the
+ documentation, there is a mailing list which can be found at
+ <link xlink:href="https://lists.forgerock.org/mailman/listinfo/opendj"
+ xlink:show="new" /> where you are likely to find an answer.</para>
+
+ <note xml:id="feedback-not-changed">
+ <para>
+ The content of this chapter has not changed in this release.
+ </para>
+ </note>
+
+ <para>If you have found issues or reproducible bugs within OpenDJ
+ <?eval ${docTargetVersion}?>, report them in the <link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ">OpenDJ issue
+ tracker</link>.</para>
+
+ <para>When requesting help with a problem, please include the following
+ information:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Description of the problem, including when the problem occurs and
+ its impact on your operation</para>
+ </listitem>
+ <listitem>
+ <para>Description of the environment, including the following information:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Machine type</para>
+ </listitem>
+ <listitem>
+ <para>Operating system & version</para>
+ </listitem>
+ <listitem>
+ <para>Storage type & version</para>
+ </listitem>
+ <listitem>
+ <para>Java version</para>
+ </listitem>
+ <listitem>
+ <para>Web container & version (if applicable)</para>
+ </listitem>
+ <listitem>
+ <para>OpenDJ release version</para>
+ </listitem>
+ <listitem>
+ <para>Any patches or other software that might be affecting the problem</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>Steps to reproduce the problem</para>
+ </listitem>
+ <listitem>
+ <para>Any relevant access and error logs, stack traces, or core dumps</para>
+ </listitem>
+ </itemizedlist>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-issues.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-issues.xml
new file mode 100644
index 0000000..c0edfd3
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-issues.xml
@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-issues'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>OpenDJ Fixes, Limitations, & Known Issues</title>
+
+ <para>
+ This chapter covers the status of key issues and limitations
+ for OpenDJ ${docTargetVersion} and OpenDJ SDK ${sdkDocTargetVersion}.
+ For details and information on other issues,
+ see the <link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ"
+ >OpenDJ issue tracker</link>.
+ </para>
+
+ <section xml:id="fixes">
+ <title>Key Fixes</title>
+
+ <note>
+ <!-- TODO: reconsider when 2.4.x is no longer supported. -->
+ <para>
+ OpenDJ 2.6.0 and later maintenance releases
+ include important improvements to replication.
+ Replication remains fully compatible with earlier versions.
+ However, some operations that work fine with the current OpenDJ release,
+ such as replicating large groups
+ and replicating high volumes of adds and deletes,
+ can cause issues for earlier versions.
+ Make sure you upgrade all servers to this version
+ before allowing clients to take advantage of write operations
+ that could cause trouble for older servers.
+ </para>
+ </note>
+
+ <para>The following important bugs were fixed in this release.</para>
+
+ <!-- List generated at 10:40:00 20150721 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=project+%3D+OpenDJ+AND+type+%3D+Bug+AND+resolution+%3D+Fixed+AND+fixVersion+%3D+%222.6.3%22+AND+component+not+in+%28Documentation%2C+QA%29+AND+labels+%3D+release-notes&startAt=0&maxResults=500&fields=summary-->
+ <itemizedlist>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-2157" xlink:show="new">OPENDJ-2157</link>: Backport OPENDJ-2152: ldapsearch ignores ldapsearch.useSSL=true in a tools.properties</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1951" xlink:show="new">OPENDJ-1951</link>: Backport OPENDJ-1915 DSMLServlet is not thread-safe</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1947" xlink:show="new">OPENDJ-1947</link>: Backport OPENDJ-1605: Schema is incorrect for ds-base-dn-entry-count attribute used in monitor backend</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1892" xlink:show="new">OPENDJ-1892</link>: Backport OPENDJ-1842: Using SSL with JMX doesn't work</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1890" xlink:show="new">OPENDJ-1890</link>: Backport OPENDJ-1882: currentConnections from cn=monitor is not decremented when JMX connections close</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1764" xlink:show="new">OPENDJ-1764</link>: admin-backend.ldif can end up empty</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1665" xlink:show="new">OPENDJ-1665</link>: performBackendInitializationProcessing takes a very long time when backup.info contains lots of entries</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1610" xlink:show="new">OPENDJ-1610</link>: original password is not put into the password history when reset the password without specify the new password</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1375" xlink:show="new">OPENDJ-1375</link>: Subtree delete control can wait forever for an id2subtree lock</para></listitem>
+ </itemizedlist>
+ <!-- Issue count: 9 -->
+ </section>
+
+ <section xml:id="limitations">
+ <title>Limitations</title>
+
+ <para>Release <?eval ${docTargetVersion}?> has the following limitations,
+ none of which are new since <?eval ${stableServerVersion}?>.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>OpenDJ directory server provides full LDAP v3 support, except for
+ alias dereferencing, and limited support for LDAPv2.</para>
+ </listitem>
+ <listitem>
+ <para>When you configure account lockout as part of password policy,
+ OpenDJ locks an account after the specified number of consecutive
+ authentication failures. Account lockout is not transactional across a
+ replication topology, however. Global account lockout occurs as soon as
+ the authentication failure times have been replicated.</para>
+ </listitem>
+ <listitem>
+ <para>OpenDJ is not fully integrated with Microsoft Windows, yet OpenDJ
+ directory server can be run as a service, and thus displayed in the
+ Windows Services Control Panel.</para>
+ </listitem>
+ <listitem>
+ <para>OpenDJ replication is designed to permit an unlimited number
+ of replication servers in your topology. Project testing has, however,
+ focused only on topologies of up to eight replication servers.</para>
+ </listitem>
+
+ <listitem>
+ <para>OpenDJ plugin extensions must follow the guidelines set forth in
+ the <filename>README</filename> file delivered in
+ <filename>opendj/example-plugin.zip</filename>. When developing your
+ extension, aim to remain loosely coupled with any particular version of
+ OpenDJ. Libraries used must be installed in
+ <filename>opendj/lib/extensions/</filename> (or bundle them in your
+ .jar). Keep your configuration separate from the server configuration.
+ Also, unless you are reusing standard schema definitions, keep your
+ schema definitions separate as well.</para>
+
+ <para>This can affect how your extension works after upgrade. In
+ particular <literal>opendj-accountchange-handler-1.0.0</literal> does
+ not work with OpenDJ 2.6.0 after upgrade (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-991"
+ >OPENDJ-991</link>). See that issue for notes on how make that version
+ of the extension work with OpenDJ 2.6.0.</para>
+ </listitem>
+
+ <!-- This hardware is EOL.
+ <listitem>
+ <para>On Niagara systems such as T2000, hardware SSL crypto acceleration
+ runs more slowly than software crypto acceleration. To work around this
+ issue take the following actions.</para>
+ <orderedlist>
+ <listitem>
+ <para>Add more request handlers to LDAP (for TLS) and LDAPS (for SSL)
+ connection handlers.</para>
+ </listitem>
+ <listitem>
+ <para>Disable hardware acceleration for server's JVM by removing the
+ SunPKCS11 security provider from
+ <filename>jre/lib/security/java.security</filename>.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ -->
+ </itemizedlist>
+ </section>
+
+ <section xml:id="known-issues">
+ <title>Known Issues</title>
+
+ <tip>
+ <para>When deploying for production, make sure that you follow the
+ installation instructions on allowing OpenDJ to use at least 64K (65536)
+ file descriptors, and on tuning the JVM appropriately.</para>
+ </tip>
+
+ <para>The following important issues remained open at the time this release
+ became available.</para>
+
+ <!-- List generated at 10:49:54 20150619 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=project+%3D+OpenDJ+AND+type+%3D+Bug+AND+%28resolution+%3D+unresolved+or+%28fixVersion+not+in+%28%222.6.0%22%2C+%222.6.1%22%2C+%222.6.2%22%2C+%222.6.3%22%29+AND+fixVersion+in+%28%222.8.0%22%2C+%223.0.0%22%29%29%29+AND+component+not+in+%28Documentation%2C+QA%2C+%22opendj+sdk%22%2C+%22next+gen+backend%22%29+AND+labels+%3D+release-notes&startAt=0&maxResults=500&fields=summary-->
+ <itemizedlist>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1969" xlink:show="new">OPENDJ-1969</link>: IdleTimeLimitThread fails with null ConnectionHandlers or null ClientConnections</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1968" xlink:show="new">OPENDJ-1968</link>: NPE in GoverningStructureRuleVirtualAttributeProvider if entry has no structural object classes</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1829" xlink:show="new">OPENDJ-1829</link>: JMX connector listens on a random port number</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1586" xlink:show="new">OPENDJ-1586</link>: Nested Groups fail to return indirect members with db's larger than 10 entries</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1431" xlink:show="new">OPENDJ-1431</link>: Trimming of draftcndb gets stuck, changelog keeps growing in size</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1366" xlink:show="new">OPENDJ-1366</link>: Arguments logged in wrong order for ERROR_REPLAYING_OPERATION</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1325" xlink:show="new">OPENDJ-1325</link>: An error occurred while attempting to perform index rebuild: The database environment could not be opened: (JE 5.0.73)</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1309" xlink:show="new">OPENDJ-1309</link>: First dsreplication enable could warn before replicating schema</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1294" xlink:show="new">OPENDJ-1294</link>: ldappasswordmodify -D <DN> -w - fails without prompting password from stdin</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1290" xlink:show="new">OPENDJ-1290</link>: Nested backends handles hasSubordinates attribute incorrectly</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1239" xlink:show="new">OPENDJ-1239</link>: dsreplication logs warnings for each replication server under cn=monitor</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1213" xlink:show="new">OPENDJ-1213</link>: LDIFReader should reject LDIF that contains trailing space</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1189" xlink:show="new">OPENDJ-1189</link>: Integer overflow while sizing scratch files building indexes</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1172" xlink:show="new">OPENDJ-1172</link>: Deadlock between replication threads during shutdown.</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1169" xlink:show="new">OPENDJ-1169</link>: Exception/error lost when logging ERR_LOOP_REPLAYING_OPERATION</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1158" xlink:show="new">OPENDJ-1158</link>: rebuild-index leaves backend offline if a backup is running</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1151" xlink:show="new">OPENDJ-1151</link>: OpenDJ unable to initialize the SSL context an doesn't start</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1138" xlink:show="new">OPENDJ-1138</link>: searchrate throws java.lang.IndexOutOfBoundsException</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1131" xlink:show="new">OPENDJ-1131</link>: Rest2LDAP fails to start with GlassFish3.1</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1094" xlink:show="new">OPENDJ-1094</link>: ECL virtual lastChangeNumber attribute can decrement</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1087" xlink:show="new">OPENDJ-1087</link>: OpenDJ Console: Validation checks missing</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1056" xlink:show="new">OPENDJ-1056</link>: secure listener should not be created if proper keying material is not available for some reason</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1051" xlink:show="new">OPENDJ-1051</link>: Upgrade: add task to update lastChangeNumber/firstChangeNumber attributes definition when upgrading from 2.4.x</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1043" xlink:show="new">OPENDJ-1043</link>: Worker Thread was interrupted while waiting for new work while shutting down </para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1016" xlink:show="new">OPENDJ-1016</link>: Control panel does not follow static group recommendation from documentation</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1007" xlink:show="new">OPENDJ-1007</link>: InstallHelper: endless loop, etc.</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-948" xlink:show="new">OPENDJ-948</link>: unauthorized disclosure of directory contents</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-934" xlink:show="new">OPENDJ-934</link>: Changes to RS window-size property require a server restart</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-862" xlink:show="new">OPENDJ-862</link>: Strange ds-privilege-name behavior</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-810" xlink:show="new">OPENDJ-810</link>: Non-atomic password state updates</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-737" xlink:show="new">OPENDJ-737</link>: OpenDJ Administration Connector KeyStore Pin File must be defined and non empty</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-640" xlink:show="new">OPENDJ-640</link>: Text Query Against indexed telephoneNumber Attribute Very Slow</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-573" xlink:show="new">OPENDJ-573</link>: mustChangePassword function makes-up password change state</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-557" xlink:show="new">OPENDJ-557</link>: Identical changes recorded in duplicate changelog records</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-527" xlink:show="new">OPENDJ-527</link>: rebuild-index --rebuildAll corrupts the indexes for certain data sets </para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-518" xlink:show="new">OPENDJ-518</link>: Cannot log into the administrative control panel with FIPS-140 enabled in certain cases</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-505" xlink:show="new">OPENDJ-505</link>: dsreplication enable fails when hostname contains an underscore</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-431" xlink:show="new">OPENDJ-431</link>: Server side sort control only works on result sets of less than 100000 entries</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-412" xlink:show="new">OPENDJ-412</link>: Blocked persistent searches may block all worker threads</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-365" xlink:show="new">OPENDJ-365</link>: Potential deadlock in JE backend while performing a mix of update operations</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-270" xlink:show="new">OPENDJ-270</link>: dsreplication disable takes a long time</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-49" xlink:show="new">OPENDJ-49</link>: Replication replay does not take into consideration the server/backend's writability mode.</para></listitem>
+ </itemizedlist>
+ <!-- Issue count: 42 -->
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-support.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-support.xml
new file mode 100644
index 0000000..b3e04a0
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-support.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-support'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>Support</title>
+
+ <para>You can purchase OpenDJ support subscriptions and training courses
+ from ForgeRock and from consulting partners around the world and in your
+ area. To contact ForgeRock, send mail to <link
+ xlink:href='mailto:info@forgerock.com'>info@forgerock.com</link>. To find a
+ partner in your area, see <link xlink:show="new"
+ xlink:href="http://forgerock.com/partners/" />.</para>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-update-install.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-update-install.xml
new file mode 100644
index 0000000..05a4bc5
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-update-install.xml
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-update-install'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>Updating & Installing OpenDJ</title>
+
+ <para>
+ ForgeRock recommends that you update
+ OpenDJ ${stableServerVersion} installations to this release.
+ If you are installing OpenDJ for the first time,
+ you can use the same installation instructions as for ${stableServerVersion}.
+ </para>
+
+ <procedure xml:id="update-software">
+ <title>To Update OpenDJ Software</title>
+
+ <step>
+ <para>
+ Download and unpack OpenDJ ${docTargetVersion} software.
+ </para>
+
+ <para>
+ Find a link to the OpenDJ download page from
+ <link xlink:show="new" xlink:href="https://backstage.forgerock.com/"
+ >backstage.forgerock.com</link>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Follow the instructions in the chapter on <link xlink:show="new"
+ xlink:href="https://backstage.forgerock.com/#!/docs/opendj/2.6.0/install-guide#chap-upgrade"
+ ><citetitle>Upgrading to OpenDJ ${stableServerVersion}</citetitle></link>
+ in the <citetitle>Installation Guide</citetitle>.
+ </para>
+
+ <para>
+ When upgrading from OpenDJ 2.5.0-Xpress1,
+ you no longer need to rebuild the <literal>ds-sync-hist</literal> index
+ as a separate step.
+ </para>
+ </step>
+ </procedure>
+
+ <procedure xml:id="install-software">
+ <title>To Install OpenDJ Software</title>
+
+ <step>
+ <para>
+ Download and unpack OpenDJ ${docTargetVersion} software.
+ </para>
+
+ <para>
+ Find a link to the OpenDJ download page from
+ <link xlink:show="new" xlink:href="https://backstage.forgerock.com/"
+ >backstage.forgerock.com</link>.
+ </para>
+ </step>
+
+ <step>
+ <para>
+ Follow the instructions in the <link xlink:show="new"
+ xlink:href="https://backstage.forgerock.com/#!/docs/opendj/2.6.0/install-guide"
+ ><citetitle>OpenDJ ${stableServerVersion} Installation Guide</citetitle></link>.
+ </para>
+ </step>
+ </procedure>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-whats-new.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-whats-new.xml
new file mode 100644
index 0000000..215c306
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/chap-whats-new.xml
@@ -0,0 +1,291 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-whats-new'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>What's New in OpenDJ <?eval ${docTargetVersion}?></title>
+
+ <para>
+ OpenDJ ${docTargetVersion} is a maintenance release
+ that resolves a number of issues,
+ including security issues in OpenDJ directory server.
+ It is strongly recommended that you update
+ to this release to make your deployment more secure,
+ and to take advantage of important functional fixes.
+ ForgeRock customers can contact support for help and further information.
+ </para>
+
+ <para>
+ Before you install OpenDJ or update your existing OpenDJ installation,
+ read these release notes. Then update or install OpenDJ.
+ </para>
+
+ <section xml:id="security-advisory">
+ <title>Security Advisory</title>
+
+ <para>
+ A security vulnerability has been discovered in OpenDJ.
+ This issue is present in all versions of OpenDJ
+ including 2.6.x, 2.5.0-Xpress1, 2.4.x, and possibly previous versions.
+ </para>
+
+ <para>
+ A security advisory has been issued to provide guidance on
+ how to ensure your deployments can be secured.
+ Workarounds or patches are available for the issue,
+ with fixes included in OpenDJ 2.6.3.
+ </para>
+
+ <para>
+ The severity of the issue in the advisory is High.
+ Deployers should take immediate steps as outlined in the advisory
+ and apply the relevant update at the earliest opportunity.
+ </para>
+
+ <para>
+ The recommendation is to deploy the relevant patch
+ or to upgrade to OpenDJ 2.6.3.
+ </para>
+
+ <para>
+ Customers without existing patches can obtain the relevant patch from
+ <link xlink:href="https://backstage.forgerock.com" xlink:show="new"
+ >BackStage</link>.
+ Customers with deployed patches should contact the support organization
+ to obtain a combo patch.
+ The fix is also present in the community "trunk" nightly builds.
+ </para>
+
+ <itemizedlist>
+ <para>
+ The following security fix has been included in this release:
+ </para>
+
+ <listitem>
+ <para>
+ <emphasis role="strong">Issue #201504-01:
+ Proxied Authorization may allow unexpected escalation
+ of privileges and access.</emphasis>
+ When someone has been granted the privileges to Proxy requests
+ and use the Proxied Authorization control,
+ it is not possible to control who that user can impersonate.
+ It is thus possible to impersonate "cn=Directory Manager"
+ and bypass all access controls.
+ </para>
+
+ <para>
+ Severity: <emphasis role="strong">High</emphasis>
+ </para>
+
+ <para>
+ For more information, see
+ <link
+ xlink:href="https://forgerock.org/2015/06/opendj-security-advisory-201504/"
+ xlink:show="new"
+ >OpenDJ Security Advisory #201504</link>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="product-enhancements">
+ <title>Product Enhancements</title>
+
+ <para>
+ Compared to the OpenDJ ${stableServerVersion} release,
+ OpenDJ ${docTargetVersion} provides these important enhancements.
+ </para>
+
+ <para>
+ OpenDJ ${docTargetVersion} includes no new enhancements
+ beyond those included in OpenDJ 2.6.2.
+ </para>
+
+ <itemizedlist>
+ <para>
+ The following improvement is new in OpenDJ 2.6.2.
+ </para>
+
+ <listitem>
+ <para>
+ OpenDJ server can now bind to a local address
+ when making outgoing connections
+ (<link
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1565"
+ xlink:show="new"
+ >OPENDJ-1565</link>).
+ </para>
+
+ <para>
+ This improvement introduces a new configuration attribute,
+ <literal>source-address</literal>,
+ that you can set for Replication Domains, Replication Servers,
+ and LDAP Pass Through Authentication Policies.
+ If the <literal>source-address</literal> property is set to an IP address,
+ OpenDJ binds to the address before connecting to the remote server.
+ The address must be one assigned to an existing network interface.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <para>
+ The following improvements are new in OpenDJ 2.6.1.
+ </para>
+
+ <listitem>
+ <para>
+ OpenDJ directory server ships with updated Commons REST,
+ OpenDJ LDAP SDK, and Berkeley DB Java Edition components
+ (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1323"
+ >OPENDJ-1323</link>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ OpenDJ directory server now makes it possible
+ to specify password validators in subentry based password policies
+ (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1295"
+ >OPENDJ-1295</link>).
+ </para>
+
+ <para>
+ To configure password validators for a subentry password policy,
+ add the auxiliary object class <literal>pwdValidatorPolicy</literal>
+ and setting the multi-valued attribute,
+ <literal>ds-cfg-password-validator</literal>,
+ to the DNs of the password validator configuration entries.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ OpenDJ directory server now orders attributes
+ according to search request attribute list order
+ (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1082"
+ >OPENDJ-1082</link>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ OpenDJ directory server logs information to help you more effectively
+ determine why a directory server replica switches its connection
+ to a different replication server
+ (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1053"
+ >OPENDJ-1053</link>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The REST LDAP Gateway now supports LDAPS connections and StartTLS
+ (<link xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1033"
+ >OPENDJ-1033</link>).
+ </para>
+
+ <para>
+ For information on configuring the gateway to use LDAPS or StartTLS,
+ see the comments in the configuration file,
+ <filename>opendj-rest2ldap-servlet.json</filename>.
+ Find the settings to change in the configuration for
+ <literal>"ldapConnectionFactories"</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="product-documentation">
+ <title>OpenDJ Documentation</title>
+
+ <para>
+ You can read the following additional product documentation
+ for OpenDJ 2.6 online at ForgeRock
+ <link xlink:show="new" xlink:href="${coreDocBase}">BackStage</link>.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${coreDocBase}/install-guide/"><citetitle
+ >OpenDJ ${stableServerVersion} Installation Guide</citetitle></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${coreDocBase}/admin-guide/"><citetitle
+ >OpenDJ ${stableServerVersion} Administration Guide</citetitle></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${configRefBase}"><citetitle
+ >OpenDJ ${stableServerVersion} Configuration Reference</citetitle></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${coreDocBase}/dev-guide/"><citetitle
+ >OpenDJ ${stableServerVersion} Developer's Guide</citetitle></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${sdkJavadocBase}"><citetitle
+ >OpenDJ ${stableServerVersion} LDAP SDK API Specification</citetitle></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${serverJavadocBase}"><citetitle
+ >OpenDJ ${stableServerVersion} Server Plugin API Specification</citetitle></link>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/release-notes/index.xml b/opendj-doc-generated-ref/src/main/docbkx/release-notes/index.xml
new file mode 100644
index 0000000..5bbfe75
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/release-notes/index.xml
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2015 ForgeRock AS.
+ !
+-->
+<book xml:id='release-notes'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info>
+ <xinclude:include href="../shared/mediaobject-fr-logo.xml" />
+ <title>OpenDJ Release Notes</title>
+ <subtitle>Version ${docTargetVersion}</subtitle>
+ <abstract>
+ <para>Notes covering OpenDJ hardware & software requirements, fixes,
+ known issues. The OpenDJ project offers open source LDAP directory services
+ in Java.</para>
+ </abstract>
+ <copyright>
+ <year>2011-2015</year>
+ <holder>ForgeRock AS.</holder>
+ </copyright>
+ <authorgroup>
+ <author>
+ <personname><firstname>Mark </firstname><surname>Craig</surname></personname>
+ <xinclude:include href="../shared/affiliation-fr.xml"/>
+ </author>
+ </authorgroup>
+ <xinclude:include href='../legal.xml' />
+ <date>${publicationDate}</date>
+ <pubdate>${publicationDate}</pubdate>
+ <releaseinfo>${softwareReleaseDate}</releaseinfo>
+ </info>
+
+ <toc />
+
+ <preface>
+ <title>About OpenDJ</title>
+
+ <para>OpenDJ is an LDAPv3 compliant directory service, developed for
+ the Java platform, providing a high performance, highly available,
+ and secure store for the identities managed by your organization. Its
+ easy installation process, combined with the power of the Java
+ platform makes OpenDJ the simplest, fastest directory to deploy and
+ manage. OpenDJ directory server comes with plenty of tools and a
+ full-featured LDAP SDK for Java. OpenDJ directory server also offers
+ REST access to directory data over HTTP.</para>
+
+ <para>OpenDJ is free to download, evaluate, and use in developing your
+ applications and solutions. You can also check out and modify the source
+ code to build your own version if you prefer. ForgeRock offers training
+ and support subscriptions to help you get the most out of your
+ deployment.</para>
+
+ <para>These release notes are written for everyone working with the
+ OpenDJ <?eval ${docTargetVersion}?> release. Read these notes before you
+ install or upgrade OpenDJ software. These notes cover hardware and software
+ prerequisites for installing and upgrading OpenDJ software. These
+ notes list key features added and changed in this release. They also
+ cover compatibility with previous releases and alert you to potential
+ changes coming up that could affect your scripts and applications.
+ Finally, these notes list both issues fixed since the previous
+ release and known issues open at the time of release.</para>
+
+ <para>
+ See the <link xlink:show="new"
+ xlink:href="https://backstage.forgerock.com/#!/docs/opendj/2.6.0/install-guide"
+ ><citetitle>Installation Guide</citetitle></link> for more
+ after you read these release notes.
+ The installation guide covers installation and upgrade
+ for OpenDJ directory server, OpenDJ REST LDAP gateway, and OpenDJ DSML gateway.
+ </para>
+ </preface>
+
+ <xinclude:include href='chap-whats-new.xml' />
+ <xinclude:include href='chap-before-you-install.xml' />
+ <xinclude:include href='chap-update-install.xml' />
+ <xinclude:include href='chap-compatibility.xml' />
+ <xinclude:include href='chap-issues.xml' />
+ <xinclude:include href='chap-feedback.xml' />
+ <xinclude:include href='chap-support.xml' />
+</book>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-before-you-install.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-before-you-install.xml
new file mode 100644
index 0000000..fd6602a
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-before-you-install.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-before-you-install'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'>
+ <title>Before You Install OpenDJ LDAP SDK Software</title>
+
+ <para>
+ This chapter covers requirements to consider before you run OpenDJ LDAP SDK.
+ </para>
+
+ <note>
+ <para>
+ This chapter has not changed since 2.6.9.
+ </para>
+ </note>
+
+ <section xml:id="prerequisites-java">
+ <title>Java Environment</title>
+
+ <para>
+ OpenDJ LDAP SDK is a pure Java library.
+ OpenDJ LDAP SDK therefore should run on any system with full Java support.
+ OpenDJ software runs on a variety of operating systems,
+ including but not limited to Solaris SPARC and x86,
+ various Linux distributions,
+ Microsoft Windows,
+ and Apple Mac OS X.
+ </para>
+
+ <para>
+ OpenDJ software requires Java 6 or 7,
+ specifically at least the Java Standard Edition runtime environment.
+ To build applications with OpenDJ LDAP SDK,
+ you need the corresponding Java SDK.
+ </para>
+
+ <para>
+ ForgeRock recommends that you keep your Java installation up to date
+ with the latest security fixes.
+ </para>
+ </section>
+
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-compatibility.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-compatibility.xml
new file mode 100644
index 0000000..b6bbdc9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-compatibility.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-compatibility'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>Compatibility</title>
+
+ <para>
+ This chapter covers major changes to existing APIs,
+ and deprecated and removed APIs.
+ </para>
+
+ <note>
+ <para>
+ This chapter has not changed since 2.6.9.
+ </para>
+ </note>
+
+ <section xml:id="changes">
+ <title>Major Changes</title>
+
+ <para>
+ This maintenance release is binary-compatible with
+ OpenDJ LDAP SDK 2.6.9.
+ It does not introduce major changes.
+ </para>
+ </section>
+
+ <section xml:id="deprecation">
+ <title>Deprecation</title>
+
+ <para>
+ Deprecated APIs are listed in the API Specification, on the
+ <link
+ xlink:show="new"
+ xlink:href="${sdkJavadocBase}index.html?deprecated-list.html"
+ >Deprecated list</link> page.
+ </para>
+
+ <para>
+ Deprecated APIs are likely to be removed in a future release.
+ </para>
+ </section>
+
+ <section xml:id="removals">
+ <title>Removals</title>
+
+ <para>
+ Nothing has been removed from the public APIs in this release.
+ </para>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-feedback.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-feedback.xml
new file mode 100644
index 0000000..52509b8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-feedback.xml
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-feedback'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>How to Report Problems & Provide Feedback</title>
+
+ <para>
+ If you have questions regarding OpenDJ LDAP SDK
+ that are not answered by the documentation,
+ there is a mailing list which can be found at
+ <link xlink:href="https://lists.forgerock.org/mailman/listinfo/opendj" xlink:show="new" />
+ where you are likely to find an answer.
+ </para>
+
+ <note>
+ <para>
+ This chapter has not changed since 2.6.9.
+ </para>
+ </note>
+
+ <para>
+ If you have found issues or reproducible bugs
+ within this release of OpenDJ LDAP SDK, report them in the
+ <link
+ xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ"
+ >OpenDJ issue tracker</link>.
+ </para>
+
+ <para>
+ When requesting help with a problem, please include the following information:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Description of the problem, including when the problem occurs
+ and its impact on your operation
+ </para>
+ </listitem>
+
+ <listitem>
+ <itemizedlist>
+ <para>
+ Description of the environment, including the following information:
+ </para>
+
+ <listitem>
+ <para>
+ Machine type
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Operating system & version
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Storage type & version
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Java version
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ OpenDJ LDAP SDK release version
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Any patches or other software that might be affecting the problem
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ Steps to reproduce the problem
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Any relevant access and error logs, and stack traces
+ </para>
+ </listitem>
+ </itemizedlist>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-get-sdk.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-get-sdk.xml
new file mode 100644
index 0000000..2c9b81f
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-get-sdk.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014 ForgeRock AS
+ !
+-->
+<chapter xml:id='chap-get-sdk'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>Getting OpenDJ LDAP SDK</title>
+
+ <para>
+ OpenDJ LDAP SDK is available from the ForgeRock repository,
+ <link xlink:show="new" xlink:href="http://maven.forgerock.org/repo/" />.
+ </para>
+
+ <para>
+ To include OpenDJ LDAP SDK as a Maven dependency,
+ include the ForgeRock repository in your list,
+ and include the SDK as a dependency.
+ </para>
+
+ <programlisting language="xml">
+<xinclude:include href="resources/maven-xml.txt" parse="text">
+ <xinclude:fallback>Failed to include Maven POM sections</xinclude:fallback>
+</xinclude:include>
+ </programlisting>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-issues.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-issues.xml
new file mode 100644
index 0000000..45c7983
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-issues.xml
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-issues'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>OpenDJ LDAP SDK Fixes, Limitations, & Known Issues</title>
+
+ <para>
+ This chapter covers the status of key issues and limitations
+ for this version of OpenDJ LDAP SDK.
+ For detailed information regarding a particular issue, see the
+ <link
+ xlink:show="new"
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ"
+ >OpenDJ issue tracker</link>.
+ </para>
+
+ <section xml:id="fixes">
+ <title>Key Fixes</title>
+
+ <para>
+ The following bugs were fixed in this release.
+ </para>
+
+ <!-- List generated at 16:10:54 20150914 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=project+%3D+OpenDJ+AND+type+%3D+Bug+AND+resolution+%3D+Fixed+AND+%28fixVersion+in+%28%222.6.10-sdk%22%2C+%222.6.11-sdk%22%29%29+AND+component+not+in+%28Documentation%2C+QA%29+AND+labels+%3D+release-notes+AND+NOT+%28issueFunction+in+linkedIssuesOf%28%22project+%3D+OPENDJ%22%2C+%22is+backported+by%22%29%29+OR+%28issueFunction+in+linkedIssuesOf%28%22project+%3D+OPENDJ+AND+fixVersion+in+%28%272.6.10-sdk%27%2C+%272.6.11-sdk%27%29+AND+resolution+%3D+Fixed+AND+type+%3D+Bug%22%2C+%27is+a+backport+of%27%29%29&startAt=0&maxResults=500&fields=summary-->
+ <itemizedlist>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-2240" xlink:show="new">OPENDJ-2240</link>: AttributeTypes parser mishandles characters after usage field</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1909" xlink:show="new">OPENDJ-1909</link>: diffEntries implements an add+delete but should be delete+add</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1597" xlink:show="new">OPENDJ-1597</link>: newOffsetControl passes 'offset' and 'contentCount' to the constructor in the incorrect order</para></listitem>
+ </itemizedlist>
+ <!-- Issue count: 3 -->
+ </section>
+
+ <section xml:id="limitations">
+ <title>Limitations</title>
+
+ <para>
+ No limitations are noted for this release.
+ </para>
+ </section>
+
+ <section xml:id="known-issues">
+ <title>Known Issues</title>
+
+ <para>
+ The following important issues remained open
+ at the time this release became available.
+ </para>
+
+ <!-- List generated at 16:02:23 20150914 using http://bugster.forgerock.org/jira/rest/api/2/search?jql=project+%3D+OpenDJ+AND+type+%3D+Bug+AND+%28resolution+%3D+unresolved+or+%28fixVersion+not+in+%28%222.6.1-sdk%22%2C+%222.6.2-sdk%22%2C+%222.6.3-sdk%22%2C+%222.6.4-sdk%22%2C+%222.6.5-sdk%22%2C+%222.6.6-sdk%22%2C+%222.6.7-sdk%22%2C+%222.6.8-sdk%22%2C+%222.6.9-sdk%22%2C+%222.6.10-sdk%22%2C+%222.6.11-sdk%22%29%29%29+AND+component+%3D+%22opendj+sdk%22+AND+labels+%3D+release-notes+AND+NOT+%28issueFunction+in+linkedIssuesOf%28%22project+%3D+OPENDJ+AND+fixVersion+in+%28%272.6.10-sdk%27%2C+%272.6.11-sdk%27%29+AND+resolution+%3D+Fixed%22%2C+%22is+a+backport+of%22%29%29&startAt=0&maxResults=500&fields=summary-->
+ <itemizedlist>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1276" xlink:show="new">OPENDJ-1276</link>: ModifyDNRequest javadoc should describe deleteOldRDN default value</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1131" xlink:show="new">OPENDJ-1131</link>: Rest2LDAP fails to start with GlassFish3.1</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-627" xlink:show="new">OPENDJ-627</link>: ConnectionPool internal state becomes invalid when stale connections are discarded</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-590" xlink:show="new">OPENDJ-590</link>: ConnectionPool may return already closed/disconnected connections</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-553" xlink:show="new">OPENDJ-553</link>: FailoverLoadBalancingAlgorithm does not appear to fail over</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-514" xlink:show="new">OPENDJ-514</link>: OpenDJ SDK SASL integrity/confidentiality violates protocol</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-464" xlink:show="new">OPENDJ-464</link>: NPE in PasswordPolicyStateExtendedResult results in eternal waiting</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-427" xlink:show="new">OPENDJ-427</link>: AuthenticatedConnectionFactory hides exception with NPE</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-271" xlink:show="new">OPENDJ-271</link>: ExternalSASLBindRequestImpl throws java.lang.IllegalStateException</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-159" xlink:show="new">OPENDJ-159</link>: LDAP connections use stale default schema if it is changed after factory creation.</para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-156" xlink:show="new">OPENDJ-156</link>: Errors when parsing collective attribute definitions </para></listitem>
+ <listitem><para><link xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-155" xlink:show="new">OPENDJ-155</link>: Add support for OpenDJ extended matching rules and syntaxes</para></listitem>
+ </itemizedlist>
+ <!-- Issue count: 12 -->
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-support.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-support.xml
new file mode 100644
index 0000000..fe65c8a
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-support.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-support'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>Support</title>
+
+ <para>
+ You can purchase OpenDJ LDAP SDK support subscriptions from ForgeRock
+ and from consulting partners around the world and in your area.
+ </para>
+
+ <para>
+ To contact ForgeRock, send mail to
+ <link xlink:href='mailto:info@forgerock.com'>info@forgerock.com</link>.
+ </para>
+
+ <para>
+ To find a partner in your area, see
+ <link xlink:show="new" xlink:href="https://forgerock.com/" />.
+ </para>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-whats-new.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-whats-new.xml
new file mode 100644
index 0000000..ec7bef9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/chap-whats-new.xml
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<chapter xml:id='chap-whats-new'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <title>What's New in OpenDJ LDAP SDK ${sdkDocTargetVersion}</title>
+
+ <para>
+ OpenDJ LDAP SDK ${sdkDocTargetVersion} is a maintenance release
+ that resolves a number of issues.
+ It is recommended that you update to this release
+ to take advantage of important functional fixes.
+ ForgeRock customers can contact support for help and further information.
+ </para>
+
+ <para>
+ Before you use the new release, read these release notes.
+ </para>
+
+ <section xml:id="product-enhancements">
+ <title>Product Enhancements</title>
+
+ <itemizedlist>
+ <para>
+ Compared to the OpenDJ LDAP SDK 2.6.9 release,
+ OpenDJ LDAP SDK ${sdkDocTargetVersion} provides these important enhancements.
+ </para>
+
+ <listitem>
+ <para>
+ The PersistentSearchChangeType enum now allows the developer
+ to obtain enum values from the int value representation
+ in order to allow switching on values without having to redefine constants
+ (<link
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-2023"
+ xlink:show="new"
+ >OPENDJ-2023</link>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ OpenDJ LDAP SDK now provides a <literal>TransactionIdControl</literal>
+ to pass a transaction ID for audit logging in LDAP requests
+ (<link
+ xlink:href="https://bugster.forgerock.org/jira/browse/OPENDJ-1926"
+ xlink:show="new"
+ >OPENDJ-1926</link>).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section xml:id="product-documentation">
+ <title>OpenDJ LDAP SDK Documentation</title>
+
+ <para>
+ You can read the following additional product documentation
+ for OpenDJ LDAP SDK 2.6 online at ForgeRock
+ <link xlink:show="new" xlink:href="${coreDocBase}">BackStage</link>.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${coreDocBase}/dev-guide/"><citetitle
+ >OpenDJ 2.6.0 LDAP SDK Developer's Guide</citetitle></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link xlink:show="new"
+ xlink:href="${sdkJavadocBase}"><citetitle
+ >OpenDJ 2.6.0 LDAP SDK API Specification</citetitle></link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/index.xml b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/index.xml
new file mode 100644
index 0000000..6d31f69
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/index.xml
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2014-2015 ForgeRock AS.
+ !
+-->
+<book xml:id='release-notes'
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+ <info>
+ <xinclude:include href="../shared/mediaobject-fr-logo.xml" />
+ <title>OpenDJ LDAP SDK Release Notes</title>
+ <subtitle>Version ${sdkDocTargetVersion}</subtitle>
+ <abstract>
+ <para>
+ Notes covering OpenDJ LDAP SDK software requirements, fixes, known issues.
+ The OpenDJ project offers open source LDAP directory services in Java.
+ </para>
+ </abstract>
+ <copyright>
+ <year>2014-2015</year>
+ <holder>ForgeRock AS.</holder>
+ </copyright>
+ <authorgroup>
+ <author>
+ <personname><firstname>Mark </firstname><surname>Craig</surname></personname>
+ </author>
+ <author>
+ <personname><firstname>Chris </firstname><surname>Ridd</surname></personname>
+ <xinclude:include href="../shared/affiliation-fr.xml"/>
+ </author>
+ </authorgroup>
+ <xinclude:include href='../legal.xml' />
+ <date>${publicationDate}</date>
+ <pubdate>${publicationDate}</pubdate>
+ <releaseinfo>${softwareReleaseDate}</releaseinfo>
+ </info>
+
+ <toc />
+
+ <preface xml:id="preface">
+ <title>Preface</title>
+
+ <para>
+ OpenDJ LDAP SDK provides a set of modern, developer-friendly Java APIs
+ as part of the OpenDJ product suite.
+ The product suite includes the client SDK
+ alongside command-line tools and sample code,
+ a 100% pure Java directory server, and more.
+ You can use OpenDJ LDAP SDK to create client applications
+ for use with any server that complies with the
+ <citetitle>Lightweight Directory Access Protocol (LDAP):
+ Technical Specification Road Map</citetitle>,
+ <link
+ xlink:href="http://tools.ietf.org/html/rfc4510"
+ xlink:show="new"
+ >RFC 4510</link>.
+ </para>
+
+ <para>
+ OpenDJ LDAP SDK brings you easy-to-use connection management,
+ connection pooling, load balancing, and all the standard LDAP operations
+ to read and write directory entries.
+ OpenDJ LDAP SDK also lets you build applications with capabilities
+ defined in additional draft and experimental RFCs
+ that are supported by modern LDAP servers.
+ </para>
+ </preface>
+
+ <xinclude:include href='chap-get-sdk.xml' />
+ <xinclude:include href='chap-whats-new.xml' />
+ <xinclude:include href='chap-before-you-install.xml' />
+ <xinclude:include href='chap-compatibility.xml' />
+ <xinclude:include href='chap-issues.xml' />
+ <xinclude:include href='chap-feedback.xml' />
+ <xinclude:include href='chap-support.xml' />
+</book>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/resources/maven-xml.txt b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/resources/maven-xml.txt
new file mode 100644
index 0000000..45af035
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/sdk-release-notes/resources/maven-xml.txt
@@ -0,0 +1,26 @@
+<repositories>
+ <repository>
+ <id>forgerock-staging-repository</id>
+ <name>ForgeRock Release Repository</name>
+ <url>http://maven.forgerock.org/repo/releases</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ <repository>
+ <id>forgerock-snapshots-repository</id>
+ <name>ForgeRock Snapshot Repository</name>
+ <url>http://maven.forgerock.org/repo/snapshots</url>
+ <releases>
+ <enabled>false</enabled>
+ </releases>
+ </repository>
+</repositories>
+
+<dependencies>
+ <dependency>
+ <groupId>org.forgerock.opendj</groupId>
+ <artifactId>opendj-ldap-sdk</artifactId>
+ <version>2.6.11</version>
+ </dependency>
+</dependencies>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/affiliation-fr.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/affiliation-fr.xml
new file mode 100644
index 0000000..9d13643
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/affiliation-fr.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<affiliation xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+
+ <orgname>ForgeRock AS</orgname>
+ <address>
+ <street>201 Mission St.</street>
+ <otheraddr>Suite 2900</otheraddr>
+ <city>San Francisco</city>, <state>CA</state> <postcode>94105</postcode>
+ <country>USA</country>
+ <phone>+1 415-599-1100 (US)</phone>
+ <uri>www.forgerock.com</uri>
+ </address>
+</affiliation>
\ No newline at end of file
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/glossary.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/glossary.xml
new file mode 100644
index 0000000..ac0a695
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/glossary.xml
@@ -0,0 +1,883 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2012 ForgeRock AS
+ !
+-->
+<glossary xml:id='glossary'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>OpenDJ Glossary</title>
+
+ <glossentry>
+ <glossterm>Abandon operation</glossterm>
+ <glossdef>
+ <para>LDAP operation to stop processing of a request in progress, after
+ which the directory server drops the connection without a reply to the
+ client application.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Access control</glossterm>
+ <glossdef>
+ <para>Control to grant or to deny access to a resource.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="access-control-instruction">
+ <glossterm>Access control instruction (ACI)</glossterm>
+ <glossdef>
+ <para>Instruction added as a directory entry attribute for fine-grained
+ control over what a given user or group member is authorized to do in terms
+ of LDAP operations and access to user data.</para>
+ <para>ACIs are implemented independently from privileges, which apply to
+ administrative operations.</para>
+ <glossseealso otherterm="privilege" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Access control list (ACL)</glossterm>
+ <glossdef>
+ <para>An access control list connects a user or group of users to one or
+ more security entitlements. For example, users in group "sales" are granted
+ the entitlement "read-only" to some financial data.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><filename>access</filename> log</glossterm>
+ <glossdef>
+ <para>Directory server log tracing the operations the server processes
+ including timestamps, connection information, and information about the
+ operation itself.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Account lockout</glossterm>
+ <glossdef>
+ <para>The act of making an account temporarily or permanently inactive
+ after successive authentication failures.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Active user</glossterm>
+ <glossdef>
+ <para>A user that has the ability to authenticate and use the services,
+ having valid credentials.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Add operation</glossterm>
+ <glossdef>
+ <para>LDAP operation to add a new entry or entries to the directory.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Anonymous</glossterm>
+ <glossdef>
+ <para>A user that does not need to authenticate, and is unknown to the
+ system.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Anonymous bind</glossterm>
+ <glossdef>
+ <para>A bind operation using simple authentication with an empty DN and an
+ empty password, allowing "anonymous" access such as reading public
+ information.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="approximate-index">
+ <glossterm>Approximate index</glossterm>
+ <glossdef>
+ <para>Index is used to match values that "sound like" those provided in the
+ filter.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Attribute</glossterm>
+ <glossdef>
+ <para>Properties of a directory entry, stored as one or more key-value pairs.
+ Typical examples include the common name (<literal>cn</literal>) to store
+ the user's full name and variations of the name, user ID
+ (<literal>uid</literal>) to store a unique identifier for the entry, and
+ <literal>mail</literal> to store email addresses.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><filename>audit</filename> log</glossterm>
+ <glossdef>
+ <para>Type of access log that dumps changes in LDIF.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Authentication</glossterm>
+ <glossdef>
+ <para>The process of verifying who is requesting access to a resource; the
+ act of confirming the identity of a principal.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Authorization</glossterm>
+ <glossdef>
+ <para>The process of determining whether access should be granted to an
+ individual based on information about that individual; the act of
+ determining whether to grant or to deny a principal access to a
+ resource.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Backend</glossterm>
+ <glossdef>
+ <para>Repository that a directory server can access to store data. Different
+ implementations with different capabilities exist.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Binary copy</glossterm>
+ <glossdef>
+ <para>Binary backup archive of one directory server that can be restored on
+ another directory server.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Bind operation</glossterm>
+ <glossdef>
+ <para>LDAP authentication operation to determine the client's identity in
+ LDAP terms, the identity which is later used by the server to authorize (or
+ not) access to directory data that the client wants to lookup or
+ change.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Collective attribute</glossterm>
+ <glossdef>
+ <para>A standard mechanism for defining attributes that appear on all the
+ entries in a particular subtree.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Compare operation</glossterm>
+ <glossdef>
+ <para>LDAP operation to compare a specified attribute value with the value
+ stored on an entry in the directory.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Control</glossterm>
+ <glossdef>
+ <para>Information added to an LDAP message to further specify how an LDAP
+ operation should be processed. OpenDJ supports many LDAP controls.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Database cache</glossterm>
+ <glossdef>
+ <para>Memory space set aside to hold database content.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><filename>debug</filename> log</glossterm>
+ <glossdef>
+ <para>Directory server log tracing details needed to troubleshoot a problem
+ in the server.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Delete operation</glossterm>
+ <glossdef>
+ <para>LDAP operation to remove an existing entry or entries from the
+ directory.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="directory">
+ <glossterm>Directory</glossterm>
+ <glossdef>
+ <para>A directory is a network service which lists participants in the
+ network such as users, computers, printers, and groups. The directory
+ provides a convenient, centralized, and robust mechanism for publishing and
+ consuming information about network participants.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Directory hierarchy</glossterm>
+ <glossdef>
+ <para>A directory can be organized into a hierarchy in order to make it
+ easier to browse or manage. Directory hierarchies normally represent
+ something in the physical world, such as organizational hierarchies or
+ physical locations. For example, the top level of a directory may represent
+ a company, the next level down divisions, the next level down departments,
+ and so on. Alternately, the top level may represent the world, the next
+ level down countries, next states or provinces, next cities, and so
+ on.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="directory-manager">
+ <glossterm>Directory manager</glossterm>
+ <glossdef>
+ <para>Default Root DN who has privileges to do full administration of the
+ OpenDJ server, including bypassing access control evaluation, changing
+ access controls, and changing administrative privileges.</para>
+ <glossseealso otherterm="root-dn" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Directory object</glossterm>
+ <glossdef>
+ <para>A directory object is an item in a directory. Example objects include
+ users, user groups, computers and more. Objects may be organized into a
+ hierarchy and contain identifying attributes.</para>
+ <glossseealso otherterm="entry" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Directory server</glossterm>
+ <glossdef>
+ <para>Server application for centralizing information about network participants.
+ A highly available directory service consists of multiple directory servers
+ configured to replicate directory data.</para>
+ <glossseealso otherterm="directory" />
+ <glossseealso otherterm="replication" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Directory Services Markup Language (DSML)</glossterm>
+ <glossdef>
+ <para>Standard language to access directory services using XML. DMSL v1
+ defined an XML mapping of LDAP objects, while DSMLv2 maps the LDAP Protocol
+ and data model to XML.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Distinguished name (DN)</glossterm>
+ <glossdef>
+ <para>Fully qualified name for a directory entry, such as
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>, built by
+ concatenating the entry RDN (<literal>uid=bjensen</literal>) with the DN of
+ the parent entry (<literal>ou=People,dc=example,dc=com</literal>).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Dynamic group</glossterm>
+ <glossdef>
+ <para>Group that specifies members using LDAP URLs.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="entry">
+ <glossterm>Entry</glossterm>
+ <glossdef>
+ <para>As generic and hierarchical data stores, directories always contain
+ different kinds of entries, either nodes (or containers) or leaf entries. An
+ entry is an object in the directory, defined by one of more object classes
+ and their related attributes. At startup, OpenDJ reports the number of entries
+ contained in each suffix.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Entry cache</glossterm>
+ <glossdef>
+ <para>Memory space set aside to hold frequently-accessed, large entries,
+ such as static groups.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="equality-index">
+ <glossterm>Equality index</glossterm>
+ <glossdef>
+ <para>Index used to match values that correspond exactly (though generally
+ without case sensitivity) to the value provided in the search filter.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><filename>errors</filename> log</glossterm>
+ <glossdef>
+ <para>Directory server log tracing server events, error conditions, and
+ warnings, categorized and identified by severity.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Export</glossterm>
+ <glossdef>
+ <para>Save directory data in an LDIF file.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Extended operation</glossterm>
+ <glossdef>
+ <para>Additional LDAP operation not included in the original standards.
+ OpenDJ supports several standard LDAP extended operations.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="extensible-match-index">
+ <glossterm>Extensible match index</glossterm>
+ <glossdef>
+ <para>Index for a matching rule other than approximate, equality, ordering,
+ presence, substring or VLV, such as an index for generalized time.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>External user</glossterm>
+ <glossdef>
+ <para>An individual that accesses company resources or services but is not
+ working for the company. Typically a customer or partner.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="filter">
+ <glossterm>Filter</glossterm>
+ <glossdef>
+ <para>An LDAP search filter is an expression that the server uses to find
+ entries that match a search request, such as
+ <literal>(mail=*@example.com)</literal> to match all entries having an
+ email address in the example.com domain.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Group</glossterm>
+ <glossdef>
+ <para>Entry identifying a set of members whose entries are also in the
+ directory.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Idle time limit</glossterm>
+ <glossdef>
+ <para>Defines how long OpenDJ allows idle connections to remain open.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Import</glossterm>
+ <glossdef>
+ <para>Read in and index directory data from an LDIF file.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Inactive user</glossterm>
+ <glossdef>
+ <para>An entry in the directory that once represented a user but which is
+ now no longer able to be authenticated.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Index</glossterm>
+ <glossdef>
+ <para>Directory server backend feature to allow quick lookup of entries
+ based on their attribute values.</para>
+ <glossseealso otherterm="approximate-index" />
+ <glossseealso otherterm="equality-index" />
+ <glossseealso otherterm="extensible-match-index" />
+ <glossseealso otherterm="ordering-index" />
+ <glossseealso otherterm="presence-index" />
+ <glossseealso otherterm="substring-index" />
+ <glossseealso otherterm="vlv-index" />
+ <glossseealso otherterm="index-entry-limit" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="index-entry-limit">
+ <glossterm>Index entry limit</glossterm>
+ <glossdef>
+ <para>When the number of entries that an index key points to exceeds the
+ index entry limit, OpenDJ stops maintaining the list of entries for that
+ index key.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Internal user</glossterm>
+ <glossdef>
+ <para>An individual who works within the company either as an employee or as
+ a contractor.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>LDAP Data Interchange Format (LDIF)</glossterm>
+ <glossdef>
+ <para>Standard, portable, text-based representation of directory content.
+ See <link xlink:href="http://tools.ietf.org/html/rfc2849"
+ xlink:show="new">RFC 2849</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>LDAP URL</glossterm>
+ <glossdef>
+ <para>LDAP Uniform Resource Locator such as <literal
+ >ldap://directory.example.com:389/dc=example,dc=com??sub?(uid=bjensen)</literal>.
+ See <link xlink:href="http://tools.ietf.org/html/rfc2255"
+ xlink:show="new">RFC 2255</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>LDAPS</glossterm>
+ <glossdef>
+ <para>LDAP over SSL.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Lightweight Directory Access Protocol (LDAP)</glossterm>
+ <glossdef>
+ <para>A simple and standardized network protocol used by applications to
+ connect to a directory, search for objects and add, edit or remove
+ objects. See <link xlink:href="http://tools.ietf.org/html/rfc4510"
+ xlink:show="new">RFC 4510</link>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Lookthrough limit</glossterm>
+ <glossdef>
+ <para>Defines the maximum number of candidate entries OpenDJ considers when
+ processing a search.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Matching rule</glossterm>
+ <glossdef>
+ <para>Defines rules for performing matching operations against assertion
+ values. Matching rules are frequently associated with an attribute syntax
+ and are used to compare values according to that syntax. For example, the
+ <literal>distinguishedNameEqualityMatch</literal> matching rule can be used
+ to determine whether two DNs are equal and can ignore unnecessary spaces
+ around commas and equal signs, differences in capitalization in attribute
+ names, and so on.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Modify DN operation</glossterm>
+ <glossdef>
+ <para>LDAP modification operation to request that the server change the
+ distinguished name of an entry.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Modify operation</glossterm>
+ <glossdef>
+ <para>LDAP modification operation to request that the server change one or
+ more attributes of an entry.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Naming context</glossterm>
+ <glossdef>
+ <para>Base DN under which client applications can look for user data.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Object class</glossterm>
+ <glossdef>
+ <para>Identifies entries that share certain characteristics. Most commonly,
+ an entry's object classes define the attributes that must and may be present
+ on the entry. Object classes are stored on entries as values of the
+ <literal>objectClass</literal> attribute. Object classes are defined in the
+ directory schema, and can be abstract (defining characteristics for other
+ object classes to inherit), structural (defining the basic structure of an
+ entry, one structural inheritance per entry), or auxiliary (for decorating
+ entries already having a structural object class with other required and
+ optional attributes).</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Object identifier (OID)</glossterm>
+ <glossdef>
+ <para>String that uniquely identifies an object, such as
+ <literal>0.9.2342.19200300.100.1.1</literal> for the user ID attribute or
+ <literal>1.3.6.1.4.1.1466.115.121.1.15</literal> for
+ <literal>DirectoryString</literal> syntax. </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Operational attribute</glossterm>
+ <glossdef>
+ <para>An attribute that has a special (operational) meaning for the
+ directory server, such as <literal>pwdPolicySubentry</literal> or
+ <literal>modifyTimestamp</literal>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="ordering-index">
+ <glossterm>Ordering index</glossterm>
+ <glossdef>
+ <para>Index used to match values for a filter that specifies a range.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Password policy</glossterm>
+ <glossdef>
+ <para>A set of rules regarding what sequence of characters constitutes an
+ acceptable password. Acceptable passwords are generally those that would be
+ too difficult for another user or an automated program to guess and thereby
+ defeat the password mechanism. Password policies may require a minimum
+ length, a mixture of different types of characters (lowercase, uppercase,
+ digits, punctuation marks, and so forth), avoiding dictionary words or
+ passwords based on the user's name, and so forth. Password policies may
+ also require that users not reuse old passwords and that users change their
+ passwords regularly.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Password reset</glossterm>
+ <glossdef>
+ <para>Password change performed by a user other than the user who owns the
+ entry.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Password storage scheme</glossterm>
+ <glossdef>
+ <para>Mechanism for encoding user passwords stored on directory entries.
+ OpenDJ implements a number of password storage schemes.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Password validator</glossterm>
+ <glossdef>
+ <para>Mechanism for determining whether a proposed password is acceptable
+ for use. OpenDJ implements a number of password validators.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="presence-index">
+ <glossterm>Presence index</glossterm>
+ <glossdef>
+ <para>Index used to match the fact that an attribute is present on the entry,
+ regardless of the value.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Principal</glossterm>
+ <glossdef>
+ <para>Entity that can be authenticated, such as a user, a device, or an
+ application.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="privilege">
+ <glossterm>Privilege</glossterm>
+ <glossdef>
+ <para>Server configuration settings controlling access to administrative
+ operations such as exporting and importing data, restarting the server,
+ performing password reset, and changing the server configuration.</para>
+ <para>Privileges are implemented independently from access control
+ instructions (ACI), which apply to LDAP operations and user data.</para>
+ <glossseealso otherterm="access-control-instruction" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Referential integrity</glossterm>
+ <glossdef>
+ <para>Ensuring that group membership remains consistent following changes
+ to member entries.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><filename>referint</filename> log</glossterm>
+ <glossdef>
+ <para>Directory server log tracing referential integrity events, with
+ entries similar to the errors log.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Referral</glossterm>
+ <glossdef>
+ <para>Reference to another directory location, which can be another
+ directory server running elsewhere or another container on the same server,
+ where the current operation can be processed.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Relative distinguished name (RDN)</glossterm>
+ <glossdef>
+ <para>Initial portion of a DN that distinguishes the entry from all other
+ entries at the same level, such as <literal>uid=bjensen</literal> in
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="replication">
+ <glossterm>Replication</glossterm>
+ <glossdef>
+ <para>Data synchronization that ensures all directory servers participating
+ eventually share a consistent set of directory data.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><filename>replication</filename> log</glossterm>
+ <glossdef>
+ <para>Directory server log tracing replication events, with entries similar
+ to the errors log.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="root-dn">
+ <glossterm>Root DN</glossterm>
+ <glossdef>
+ <para>A directory superuser, whose account is specific to a directory server
+ under <literal>cn=Root DNs,cn=config</literal>.</para>
+ <para>The default Root DN is Directory Manager. You can create additional
+ Root DN accounts, each with different administrative privileges.</para>
+ <glossseealso otherterm="directory-manager" />
+ <glossseealso otherterm="privilege" />
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Root DSE</glossterm>
+ <glossdef>
+ <para>The directory entry with distinguished name "" (empty string), where
+ DSE stands for DSA-Specific Entry. DSA stands for Directory Server Agent,
+ a single directory server. The root DSE serves to expose information over
+ LDAP about what the directory server supports in terms of LDAP controls,
+ auth password schemes, SASL mechanisms, LDAP protocol versions, naming
+ contexts, features, LDAP extended operations, and so forth.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Schema</glossterm>
+ <glossdef>
+ <para>LDAP schema defines the object classes, attributes types, attribute
+ value syntaxes, matching rules and so on that constrain entries held by the
+ directory server.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Search filter</glossterm>
+ <glossdef>
+ <para>See <xref linkend="filter"/>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Search operation</glossterm>
+ <glossdef>
+ <para>LDAP lookup operation where a client requests that the server return
+ entries based on an LDAP filter and a base DN under which to search.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Simple authentication</glossterm>
+ <glossdef>
+ <para>Bind operation performed with a user's entry DN and user's password.
+ Use simple authentication only if the network connection is secure.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Size limit</glossterm>
+ <glossdef>
+ <para>Sets the maximum number of entries returned for a search.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Static group</glossterm>
+ <glossdef>
+ <para>Group that enumerates member entries.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Subentry</glossterm>
+ <glossdef>
+ <para>An entry, such as a password policy entry, that resides with the user
+ data but holds operational data, and is not visible in search results unless
+ explicitly requested.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="substring-index">
+ <glossterm>Substring index</glossterm>
+ <glossdef>
+ <para>Index used to match values specified with wildcards in the filter.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Task</glossterm>
+ <glossdef>
+ <para>Mechanism to provide remote access to directory server administrative
+ functions. OpenDJ supports tasks to backup and restore backends, to import
+ and export LDIF files, and to stop and restart the server. </para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Time limit</glossterm>
+ <glossdef>
+ <para>Defines the maximum processing time OpenDJ devotes to a search
+ operation.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Unbind operation</glossterm>
+ <glossdef>
+ <para>LDAP operation to release resources at the end of a session.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Unindexed search</glossterm>
+ <glossdef>
+ <para>Search operation for which no matching index is available. If no
+ indexes are applicable, then the directory server potentially has to go
+ through all entries to look for candidate matches. For this reason, the
+ <literal>unindexed-search</literal> privilege, allowing users to request
+ searches for which no applicable index exists, is reserved for the directory
+ manager by default.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>User</glossterm>
+ <glossdef>
+ <para>An entry that represents an individual that can be authenticated
+ through credentials contained or referenced by its attributes. A user may
+ represent an internal user or an external user, and may be an active user
+ or an inactive user.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>User attribute</glossterm>
+ <glossdef>
+ <para>An attribute for storing user data on a directory entry such as
+ <literal>mail</literal> or <literal>givenname</literal>.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Virtual attribute</glossterm>
+ <glossdef>
+ <para>An attribute with dynamically generated values that appear in entries
+ but are not persistently stored in the backend.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Virtual directory</glossterm>
+ <glossdef>
+ <para>An application that exposes a consolidated view of multiple physical
+ directories over an LDAP interface. Consumers of the directory information
+ connect to the virtual directory's LDAP service. Behind the scenes, requests
+ for information and updates to the directory are sent to one or more physical
+ directories where the actual information resides. Virtual directories enable
+ organizations to create a consolidated view of information that for legal or
+ technical reasons cannot be consolidated into a single physical copy.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry xml:id="vlv-index">
+ <glossterm>Virtual list view (VLV) index</glossterm>
+ <glossdef>
+ <para>Browsing index designed to help the directory server respond to client
+ applications that need for example to browse through a long list of results
+ a page at a time in a GUI.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>Virtual static group</glossterm>
+ <glossdef>
+ <para>OpenDJ group that lets applications see dynamic groups as what appear
+ to be static groups.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>X.500</glossterm>
+ <glossdef>
+ <para>A family of standardized protocols for accessing, browsing and
+ maintaining a directory. X.500 is functionally similar to LDAP, but is
+ generally considered to be more complex, and has consequently not been
+ widely adopted.</para>
+ </glossdef>
+ </glossentry>
+</glossary>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/images/forgerock-opendj-logo.png b/opendj-doc-generated-ref/src/main/docbkx/shared/images/forgerock-opendj-logo.png
new file mode 100644
index 0000000..ee4aaf8
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/images/forgerock-opendj-logo.png
Binary files differ
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/itemizedlist-download.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/itemizedlist-download.xml
new file mode 100644
index 0000000..00123fa
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/itemizedlist-download.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+<itemizedlist
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
+
+ <para>Download OpenDJ software from one of the following locations.</para>
+
+ <listitem>
+ <para>The ForgeRock <link xlink:href="http://forgerock.com/download-stack/"
+ xlink:show="new">Enterprise Downloads</link> page has the latest stable,
+ supported release of OpenDJ and the other products in the ForgeRock identity
+ stack.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <link xlink:href="http://forgerock.org/opendj.html"
+ xlink:show="new">Nightly Builds</link> page posts links to the latest nightly
+ builds of OpenDJ software. Note that these builds are the working version
+ from the trunk and are not for use in a production environment.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <link xlink:href="http://forgerock.org/opendj-archive.html"
+ xlink:show="new">Community Archives</link> page includes stable community
+ builds for previous releases of OpenDJ software.</para>
+ </listitem>
+</itemizedlist>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-authrate.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-authrate.xml
new file mode 100644
index 0000000..392dd61
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-authrate.xml
@@ -0,0 +1,371 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011 ForgeRock AS
+ !
+-->
+<refentry xml:id='authrate-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>authrate</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>authrate</refname>
+ <refpurpose>measure bind throughput and response time</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>authrate</command>
+ <arg choice="req">options</arg>
+ <arg choice="opt">filter format string</arg>
+ <arg choice="opt" rep="repeat">attributes</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to measure bind throughput and response time
+ of a directory service using user-defined bind or search-then-bind
+ operations.</para>
+ <para>Format strings may be used in the bind DN option as well as the authid
+ and authzid SASL bind options. A search operation may be used to retrieve the
+ bind DN by specifying the base DN and a filter. The retrieved entry DN will
+ be appended as the last argument in the argument list when evaluating format
+ strings.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --dereferencePolicy {dereferencePolicy}</option></term>
+ <listitem>
+ <para>Alias dereference policy ('never', 'always', 'search', or 'find')</para>
+ <para>Default value: never</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN format string</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --numConnections {numConnections}</option></term>
+ <listitem>
+ <para>Number of connections</para>
+ <para>Default value: 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --percentile {percentile}</option></term>
+ <listitem>
+ <para>Calculate max response time for a percentile of operations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --keepConnectionsOpen</option></term>
+ <listitem>
+ <para>Keep connections open</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-g, --argument {generator function or static string}</option></term>
+ <listitem>
+ <para>Argument used to evaluate the Java style format strings in program
+ parameters (Base DN, Search Filter). The set of all arguments provided
+ form the the argument list in order. Besides static string arguments, they
+ can be generated per iteration with the following functions:</para>
+ <variablelist>
+ <varlistentry>
+ <term>"inc({filename})"</term>
+ <listitem><para>Consecutive, incremental line from file</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"inc({min},{max})"</term>
+ <listitem><para>Consecutive, incremental number</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"rand({filename})"</term>
+ <listitem><para>Random line from file</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"rand({min},{max})"</term>
+ <listitem><para>Random number</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"randstr({length},<replaceable>charSet</replaceable>)"</term>
+ <listitem><para>Random string of specified length and optionally from
+ characters in the charSet string. A range of character can be specified
+ with [start-end] charSet notation. If no charSet is specified,
+ the default charSet of [A-Z][a-z][0-9] will be used.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --statInterval {statInterval}</option></term>
+ <listitem>
+ <para>Display results each specified number of seconds</para>
+ <para>Default value: 5</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --invalidPassword {invalidPassword}</option></term>
+ <listitem>
+ <para>Percent of bind operations with simulated invalid password</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m, --maxIterations {maxIterations}</option></term>
+ <listitem>
+ <para>Max iterations, 0 for unlimited</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-M, --targetThroughput {targetThroughput}</option></term>
+ <listitem>
+ <para>Target average throughput to achieve</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --searchScope {searchScope}</option></term>
+ <listitem>
+ <para>Search scope ('base', 'one', 'sub', or 'subordinate')</para>
+ <para>Default value: sub</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --scriptFriendly</option></term>
+ <listitem>
+ <para>Use script-friendly mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates measuring simple bind
+ performance.</para>
+ <screen>$ authrate -p 1389 -g "rand(names.txt)"
+ -D "uid=%s,ou=people,dc=example,dc=com" -w password -c 10 -f
+-----------------------------------------------------------------
+ Throughput Response Time
+ (ops/second) (milliseconds)
+recent average recent average 99.9% 99.99% 99.999% err/sec
+-----------------------------------------------------------------
+9796.9 9816.6 1.029 1.029 12.413 161.451 161.835 0.0
+14201.1 12028.1 0.704 0.835 9.508 161.456 167.573 0.0
+14450.0 12835.9 0.692 0.782 8.989 161.835 174.518 0.0
+12934.3 12860.6 0.773 0.779 9.253 161.339 174.426 0.0
+14154.5 13121.0 0.706 0.764 9.025 161.451 177.101 0.0
+^C</screen>
+ <para>The <filename>names.txt</filename> contains all the user IDs for the
+ sample suffix, and all user password values have been set to
+ <literal>password</literal> for this example.</para>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-backup.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-backup.xml
new file mode 100644
index 0000000..cac42cd
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-backup.xml
@@ -0,0 +1,358 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='backup-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>backup</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>backup</refname>
+ <refpurpose>back up OpenDJ directory data</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>backup</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to back up one or more directory server
+ backends.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --backUpAll</option></term>
+ <listitem>
+ <para>Back up all backends in the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --hash</option></term>
+ <listitem>
+ <para>Generate a hash of the backup contents</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-B, --incrementalBaseID {backupID}</option></term>
+ <listitem>
+ <para>Backup ID of the source archive for an incremental backup.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --compress</option></term>
+ <listitem>
+ <para>Compress the backup content</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-d, --backupDirectory {backupDir}</option></term>
+ <listitem>
+ <para>Path to the target directory for the backup file(s)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --incremental</option></term>
+ <listitem>
+ <para>Perform an incremental backup rather than a full backup</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --backupID {backupID}</option></term>
+ <listitem>
+ <para>Use the provided identifier for the backup</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --backendID {backendName}</option></term>
+ <listitem>
+ <para>Backend ID for the backend to archive</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --signHash</option></term>
+ <listitem>
+ <para>Sign the hash of the backup contents</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-y, --encrypt</option></term>
+ <listitem>
+ <para>Encrypt the backup contents</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Task Backend Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Task Scheduling Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--completionNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified when the task
+ completes. This option may be specified more than once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--dependency {taskID}</option></term>
+ <listitem>
+ <para>ID of a task upon which this task depends. A task will not start
+ execution until all its dependencies have completed execution.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--errorNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified if an error occurs
+ when this task executes. This option may be specified more than
+ once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--failedDependencyAction {action}</option></term>
+ <listitem>
+ <para>Action this task will take should one if its dependent tasks fail.
+ The value must be one of PROCESS, CANCEL, DISABLE. If not specified
+ defaults to CANCEL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--recurringTask {schedulePattern}</option></term>
+ <listitem>
+ <para>Indicates the task is recurring and will be scheduled according
+ to the value argument expressed in crontab(5) compatible time/date
+ pattern.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --start {startTime}</option></term>
+ <listitem>
+ <para>Indicates the date/time at which this operation will start when
+ scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC
+ time or YYYYMMDDhhmmss for local time. A value of '0' will cause the
+ task to be scheduled for immediate execution. When this option is
+ specified the operation will be scheduled to start at the specified
+ time after which this utility will exit immediately.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>1</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example backs up all user data while the server is
+ online.</para>
+ <screen>$ backup -p 4444 -D "cn=Directory Manager" -w password
+ -a -d /path/to/opendj/bak -t 0
+Backup task 20110613143801866 scheduled to start Jun 13, 2011 2:38:01 PM CEST</screen>
+
+ <para>The following example schedules back up of all user data every night at
+ 2 AM when the server is online, and notifies diradmin@example.com when
+ finished, or on error.</para>
+ <screen>$ backup -p 4444 -D "cn=Directory Manager" -w password -a
+ -d /path/to/opendj/bak --recurringTask "00 02 * * *"
+ --completionNotify diradmin@example.com --errorNotify diradmin@example.com
+Recurring Backup task BackupTask-988d6adf-4d65-44bf-8546-6ea74a2480b0
+scheduled successfully</screen>
+
+ <para>The following example backs up all user data while the server is
+ offline.</para>
+ <screen>$ /path/to/opendj/bin/stop-ds
+Stopping Server...
+...
+$ /path/to/opendj/bin/backup --backupAll --backupDirectory /path/to/opendj/bak
+...
+[28/Sep/2012:12:14:22 +0200] ... msg=The backup process completed successfully
+$ /path/to/opendj/bin/start-ds
+[28/Sep/2012:12:15:48 +0200] ... The Directory Server has started successfully
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-base64.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-base64.xml
new file mode 100644
index 0000000..9a41164
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-base64.xml
@@ -0,0 +1,174 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='base64-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>base64</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>base64</refname>
+ <refpurpose>encode and decode base64 strings</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>base64 <replaceable>subcommand</replaceable></command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to encode and decode information using base64.</para>
+ </refsect1>
+ <refsect1>
+ <title>Subcommands</title>
+ <para>The following subcommands are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><command>base64 decode</command></term>
+ <listitem>
+ <para>Decode base64-encoded information into raw data</para>
+ <para>When no options are specified, this subcommand reads from standard
+ input and writes to standard output.</para>
+ <variablelist>
+ <title>Decode Options</title>
+ <varlistentry>
+ <term><option>-d, --encodedData {data}</option></term>
+ <listitem>
+ <para>The base64-encoded data to be decoded</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --encodedDataFile {path}</option></term>
+ <listitem>
+ <para>The path to a file containing the base64-encoded data to be
+ decoded</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --toRawFile {path}</option></term>
+ <listitem>
+ <para>The path to a file to which the raw base64-decoded data should be
+ written</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>base64 encode</command></term>
+ <listitem>
+ <para>Encode raw data using base64</para>
+ <para>When no options are specified, this subcommand reads from standard
+ input and writes to standard output.</para>
+ <variablelist>
+ <title>Decode Options</title>
+ <varlistentry>
+ <term><option>-d, --rawData {data}</option></term>
+ <listitem>
+ <para>The raw data to be base64 encoded</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --rawDataFile {path}</option></term>
+ <listitem>
+ <para>The path to a file containing the raw data to be base64
+ encoded</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --toEncodedFile {path}</option></term>
+ <listitem>
+ <para>The path to a file to which the base64-encoded data should be
+ written</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following command shows the changes from the external change log
+ in human-readable format.</para>
+ <screen>$ base64 decode -d YWRkOiBkZXNjcmlwdGlvbgpkZXNjcmlwdGlvbjogQSB0aGlyZCBjaGFuZ2UK
+LQpyZXBsYWNlOiBtb2RpZmllcnNOYW1lCm1vZGlmaWVyc05hbWU6IGNuPURpcmVjdG9yeSBNYW5hZ2V
+yLGNuPVJvb3QgRE5zLGNuPWNvbmZpZwotCnJlcGxhY2U6IG1vZGlmeVRpbWVzdGFtcAptb2RpZnlUaW
+1lc3RhbXA6IDIwMTEwNjEzMDcxMjEwWgotCg==
+add: description
+description: A third change
+-
+replace: modifiersName
+modifiersName: cn=Directory Manager,cn=Root DNs,cn=config
+-
+replace: modifyTimestamp
+modifyTimestamp: 20110613071210Z
+-
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-control-panel.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-control-panel.xml
new file mode 100644
index 0000000..24c7989
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-control-panel.xml
@@ -0,0 +1,159 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='control-panel-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>control-panel</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>control-panel</refname>
+ <refpurpose>start the OpenDJ graphical admin interface</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>control-panel</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to display the Control Panel window which
+ displays basic server information and allows to do some basic administration
+ tasks on the server.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-r, --remote</option></term>
+ <listitem>
+ <para>Connect to a remote server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --adminPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Global administrator password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --adminPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password for the global administrator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example starts the Control Panel on a remote host.</para>
+
+ <screen>$ control-panel -r -h opendj.example.com -p 4444 &</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-create-rc-script.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-create-rc-script.xml
new file mode 100644
index 0000000..0ce89b5
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-create-rc-script.xml
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='create-rc-script-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>create-rc-script</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>create-rc-script</refname>
+ <refpurpose>script to manage OpenDJ as a service on UNIX</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>create-rc-script</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>Create an RC script that may be used to start, stop, and restart
+ the directory server on UNIX-based systems.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-f, --outputFile {path}</option></term>
+ <listitem>
+ <para>The path to the output file to create.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --javaHome {path}</option></term>
+ <listitem>
+ <para>The path to the Java installation that should be used to run
+ the server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --javaArgs {args}</option></term>
+ <listitem>
+ <para>A set of arguments that should be passed to the JVM when running
+ the server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --userName {userName}</option></term>
+ <listitem>
+ <para>The name of the user account under which the server should
+ run.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example adds a script to start OpenDJ at boot time
+ on a Debian-based system, and then updates the runlevel system to use the
+ script.</para>
+ <screen>$ sudo create-rc-script -f /etc/init.d/opendj -u mark
+$ sudo update-rc.d opendj</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-dbtest.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dbtest.xml
new file mode 100644
index 0000000..076d3e9
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dbtest.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='dbtest-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>dbtest</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>dbtest</refname>
+ <refpurpose>gather OpenDJ JE database debugging information</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dbtest</command>
+ <command>subcommand</command>
+ <arg>options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to debug the JE database.</para>
+ </refsect1>
+ <refsect1>
+ <title>Subcommands</title>
+ <para>The following subcommands are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><command>dbtest dump-database-container</command></term>
+ <listitem>
+ <para>Dump records from a database container</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dbtest list-database-containers</command></term>
+ <listitem>
+ <para>List the database containers for an entry container</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dbtest list-entry-containers</command></term>
+ <listitem>
+ <para>List the entry containers for a root container</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dbtest list-index-status</command></term>
+ <listitem>
+ <para>List the status of indexes in an entry container</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dbtest list-root-containers</command></term>
+ <listitem>
+ <para>List the root containers used by all JE backends</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following global options are supported.</para>
+ <para>For other options, see <command>dbtest
+ <replaceable>subcommand</replaceable> --help</command>.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example displays debugging information about the
+ equality index for <literal>sudoUser</literal>.</para>
+ <screen>$ dbtest dump-database-container -n userRoot -b dc=example,dc=com
+ -d sudoUser.equality
+Indexed Value (6 bytes): %admin
+Entry ID List (8 bytes): 165
+
+Indexed Value (5 bytes): %sudo
+Entry ID List (8 bytes): 164
+
+Indexed Value (4 bytes): root
+Entry ID List (8 bytes): 163
+
+
+Total Records: 3
+Total / Average Key Size: 13 bytes / 4 bytes
+Total / Average Data Size: 24 bytes / 8 bytes</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsconfig.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsconfig.xml
new file mode 100644
index 0000000..c5a7b5f
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsconfig.xml
@@ -0,0 +1,5560 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='dsconfig-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>dsconfig</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>dsconfig</refname>
+ <refpurpose>manage OpenDJ directory server configuration</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dsconfig [<replaceable>subcommand</replaceable>]</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility serves to configure a running directory server.</para>
+
+ <para>The <command>dsconfig</command> command is the primary command-line tool
+ for viewing and editing OpenDJ configuration. When started without arguments,
+ <command>dsconfig</command> prompts you for administration connection
+ information, including the host name, administration port number,
+ administrator bind DN and administrator password. The
+ <command>dsconfig</command> command then connects securely to the directory
+ server over the administration port. Once connected it presents you with a
+ menu-driven interface to the server configuration.</para>
+
+ <para>When you pass connection information, subcommands, and additional
+ options to <command>dsconfig</command>, the command runs in script mode and
+ so is not interactive, though it can prompt you to ask whether to apply
+ changes and whether to trust certificates (unless you use the
+ <option>--no-prompt</option> and <option>--trustAll</option> options,
+ respectively).</para>
+
+ <para>You can prepare <command>dsconfig</command> batch scripts by running
+ the tool with the <option>--commandFilePath</option> option in interactive
+ mode, then reading from the batch file with the <option>--batchFile</option>
+ option in script mode. Batch files can be useful when you have many
+ <command>dsconfig</command> commands to run and want to avoid starting
+ the JVM and setting up a new connection for each command.</para>
+
+ <para>The <command>dsconfig</command> command categorizes directory server
+ configuration into <firstterm>components</firstterm>, also called
+ <firstterm>managed objects</firstterm>. Actual components often inherit from
+ a parent component type. For example, one component is a Connection Handler.
+ An LDAP Connection Handler is a type of Connection Handler. You configure the
+ LDAP Connection Handler component to specify how OpenDJ directory server
+ handles LDAP connections coming from client applications.</para>
+
+ <para>Configuration components have <firstterm>properties</firstterm>.
+ For example, the LDAP Connection Handler component has properties such as
+ <literal>listen-port</literal> and <literal>allow-start-tls</literal>. You
+ can set the component's <literal>listen-port</literal> property to
+ <literal>389</literal> to use the default LDAP port number. You can set the
+ component's <literal>allow-start-tls</literal> property to
+ <literal>true</literal> to permit LDAP client applications to use StartTLS.
+ Much of the configuration you do with <command>dsconfig</command> involves
+ setting component properties. The <link xlink:show="new"
+ xlink:href="${configRefBase}"
+ ><citetitle>OpenDJ Configuration Reference</citetitle></link> covers all
+ <command>dsconfig</command> component properties in detail, drawing on the
+ documentation you also view when getting help through the
+ <command>dsconfig</command> command.</para>
+ </refsect1>
+ <refsect1 xml:id="dsconfig-getting-help">
+ <title>Getting Help</title>
+
+ <para>The <command>dsconfig</command> command provides many subcommands.
+ Use the following options to view help for subcommands.</para>
+
+ <para>See <link linkend="dsconfig-subcommands-ref"><citetitle>dsconfig
+ Subcommands</citetitle></link> for details of individual subcommands.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><command>dsconfig --help-all</command></term>
+ <listitem>
+ <para>Display all subcommands</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dsconfig --help-core-server</command></term>
+ <listitem>
+ <para>Display subcommands relating to core server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dsconfig --help-database</command></term>
+ <listitem>
+ <para>Display subcommands relating to caching and back-ends</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dsconfig --help-logging</command></term>
+ <listitem>
+ <para>Display subcommands relating to logging</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dsconfig --help-replication</command></term>
+ <listitem>
+ <para>Display subcommands relating to replication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dsconfig --help-security</command></term>
+ <listitem>
+ <para>Display subcommands relating to authentication and authorization</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>dsconfig --help-user-management</command></term>
+ <listitem>
+ <para>Display subcommands relating to user management</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>For help with individual subcommands, either use <command>dsconfig
+ <replaceable>subcommand</replaceable> --help</command>, or start
+ <command>dsconfig</command> in interactive mode, without specifying a
+ subcommand.</para>
+
+ <para>To view component properties, use the <command>dsconfig
+ list-properties</command> command.</para>
+ </refsect1>
+ <refsect1 xml:id="dsconfig-general-options">
+ <title>Generally Applicable Options</title>
+ <para>The following options are supported for all <command>dsconfig</command>
+ subcommands.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--advanced</option></term>
+ <listitem>
+ <para>Allows the configuration of advanced components and properties</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --adminUID {adminUID}</option></term>
+ <listitem>
+ <para>User ID of the global administrator to use to bind to the server.
+ For the <command>enable</command> subcommand, if no global administrator
+ was defined previously for any servers, the global administrator will be
+ created using the UID provided.</para>
+ <para>Default value: admin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --adminPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Global administrator password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ <para>Default value: /path/to/opendj/config/admin-truststore</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --adminPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password for the global administrator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--commandFilePath {path}</option></term>
+ <listitem>
+ <para>The full path to the file where the equivalent non-interactive
+ commands will be written when this command is run in interactive
+ mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--displayCommand</option></term>
+ <listitem>
+ <para>Display the equivalent non-interactive option on standard output
+ when this command is run in interactive mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-F, --batchFilePath {batchFilePath}</option></term>
+ <listitem>
+ <para>Path to a batch file containing a set of dsconfig commands to be
+ executed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the command exits with an error.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Do not write progress information to standard output</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --script-friendly</option></term>
+ <listitem>
+ <para>Use script-friendly mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1 xml:id="dsconfig-subcommands-ref">
+ <title>dsconfig Subcommands</title>
+ <para>This section covers individual <command>dsconfig</command>
+ subcommands.</para>
+
+ <para>Subcommands let you create, list, and delete entire configuration
+ components, and also let you get and set component properties. Subcommands
+ therefore have names that reflect these five actions.</para>
+ <itemizedlist>
+ <listitem><para>create-<replaceable>component</replaceable></para></listitem>
+ <listitem><para>list-<replaceable>component</replaceable>s</para></listitem>
+ <listitem><para>delete-<replaceable>component</replaceable></para></listitem>
+ <listitem><para>get-<replaceable>component</replaceable>-prop</para></listitem>
+ <listitem><para>set-<replaceable>component</replaceable>-prop</para></listitem>
+ </itemizedlist>
+
+ <para>Component properties for the <command>dsconfig</command> command are
+ covered in the <link xlink:show="new" xlink:href="${configRefBase}"
+ ><citetitle>OpenDJ Configuration Reference</citetitle></link>.</para>
+
+ <para>Many subcommands let you set property values. Notice in the reference
+ for the subcommands below that specific options are available for handling
+ multi-valued properties. Whereas you can assign a single property value using
+ the <option>--set</option> option, you assign multiple values to a
+ multi-valued property using the <option>--add</option> option. You can reset
+ the values of the multi-valued property using the <option>--reset</option>
+ option.</para>
+
+ <itemizedlist>
+ <para>Some property values take a time duration. Durations are expressed
+ as numbers followed by units. For example <literal>1 s</literal> means
+ one second, and <literal>2 w</literal> means two weeks. Some durations
+ have minimum granularity or maximum units, so you cannot necessary specify
+ every duration in milliseconds or weeks for example. Some durations allow
+ you to use a special value to mean unlimited. Units are specified as
+ follows.</para>
+ <listitem><para><literal>ms</literal>: milliseconds</para></listitem>
+ <listitem><para><literal>s</literal>: seconds</para></listitem>
+ <listitem><para><literal>m</literal>: minutes</para></listitem>
+ <listitem><para><literal>h</literal>: hours</para></listitem>
+ <listitem><para><literal>d</literal>: days</para></listitem>
+ <listitem><para><literal>w</literal>: weeks</para></listitem>
+ </itemizedlist>
+
+ <!-- Pending https://bugster.forgerock.org/jira/browse/OPENDJ-386
+ Automate generation of the following list of subcommands.
+ Currently, there's a secret setting in dsconfig to produce the content.
+ $ export OPENDJ_JAVA_ARGS="-Dorg.forgerock.opendj.gendoc=true"
+ $ /path/to/opendj/bin/dsconfig -?
+ -->
+ <refsect2 xml:id="dsconfig-create-access-log-filtering-criteria">
+ <title>dsconfig create-access-log-filtering-criteria</title>
+ <para>Creates Access Log Filtering Criteria</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--criteria-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Access Log Filtering Criteria</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Access Log Filtering Criteria which should be created (Default: generic). The value for TYPE can be one of: generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-account-status-notification-handler">
+ <title>dsconfig create-account-status-notification-handler</title>
+ <para>Creates Account Status Notification Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Account Status Notification Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Account Status Notification Handler which should be created. The value for TYPE can be one of: custom | error-log | smtp</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-alert-handler">
+ <title>dsconfig create-alert-handler</title>
+ <para>Creates Alert Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Alert Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Alert Handler which should be created. The value for TYPE can be one of: custom | jmx | smtp</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-attribute-syntax">
+ <title>dsconfig create-attribute-syntax</title>
+ <para>Creates Attribute Syntaxes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--syntax-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Attribute Syntax</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Attribute Syntax which should be created (Default: generic). The value for TYPE can be one of: attribute-type-description | certificate | country-string | directory-string | generic | jpeg | telephone-number</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-backend">
+ <title>dsconfig create-backend</title>
+ <para>Creates Backends</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {STRING}</option></term>
+ <listitem>
+ <para>The name of the new Backend which will also be used as the value of the "backend-id" property: Specifies a name to identify the associated backend.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Backend which should be created. The value for TYPE can be one of: backup | config-file-handler | custom | ldif | local-db | memory | monitor | null | schema | task | trust-store</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-certificate-mapper">
+ <title>dsconfig create-certificate-mapper</title>
+ <para>Creates Certificate Mappers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Certificate Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Certificate Mapper which should be created. The value for TYPE can be one of: custom | fingerprint | subject-attribute-to-user-attribute | subject-dn-to-user-attribute | subject-equals-dn</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-connection-handler">
+ <title>dsconfig create-connection-handler</title>
+ <para>Creates Connection Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Connection Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Connection Handler which should be created. The value for TYPE can be one of: custom | http | jmx | ldap | ldif | snmp</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-debug-target">
+ <title>dsconfig create-debug-target</title>
+ <para>Creates Debug Targets</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--target-name {STRING}</option></term>
+ <listitem>
+ <para>The name of the new Debug Target which will also be used as the value of the "debug-scope" property: Specifies the fully-qualified OpenDJ Java package, class, or method affected by the settings in this target definition. Use the number character (#) to separate the class name and the method name (that is, org.opends.server.core.DirectoryServer#startUp).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Debug Target which should be created (Default: generic). The value for TYPE can be one of: generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-entry-cache">
+ <title>dsconfig create-entry-cache</title>
+ <para>Creates Entry Caches</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--cache-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Entry Cache</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Entry Cache which should be created. The value for TYPE can be one of: custom | fifo | file-system | soft-reference</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-extended-operation-handler">
+ <title>dsconfig create-extended-operation-handler</title>
+ <para>Creates Extended Operation Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Extended Operation Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Extended Operation Handler which should be created. The value for TYPE can be one of: cancel | custom | get-connection-id | get-symmetric-key | password-modify | password-policy-state | start-tls | who-am-i</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-group-implementation">
+ <title>dsconfig create-group-implementation</title>
+ <para>Creates Group Implementations</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--implementation-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Group Implementation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Group Implementation which should be created. The value for TYPE can be one of: custom | dynamic | static | virtual-static</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-identity-mapper">
+ <title>dsconfig create-identity-mapper</title>
+ <para>Creates Identity Mappers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Identity Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Identity Mapper which should be created. The value for TYPE can be one of: custom | exact-match | regular-expression</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-key-manager-provider">
+ <title>dsconfig create-key-manager-provider</title>
+ <para>Creates Key Manager Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Key Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Key Manager Provider which should be created. The value for TYPE can be one of: custom | file-based | pkcs11</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-local-db-index">
+ <title>dsconfig create-local-db-index</title>
+ <para>Creates Local DB Indexes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {OID}</option></term>
+ <listitem>
+ <para>The name of the new Local DB Index which will also be used as the value of the "attribute" property: Specifies the name of the attribute for which the index is to be maintained.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Local DB Index which should be created (Default: generic). The value for TYPE can be one of: generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-local-db-vlv-index">
+ <title>dsconfig create-local-db-vlv-index</title>
+ <para>Creates Local DB VLV Indexes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {STRING}</option></term>
+ <listitem>
+ <para>The name of the new Local DB VLV Index which will also be used as the value of the "name" property: Specifies a unique name for this VLV index.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Local DB VLV Index which should be created (Default: generic). The value for TYPE can be one of: generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-log-publisher">
+ <title>dsconfig create-log-publisher</title>
+ <para>Creates Log Publishers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Log Publisher which should be created. The value for TYPE can be one of: custom-access | custom-debug | custom-error | custom-http-access | file-based-access | file-based-audit | file-based-debug | file-based-error | file-based-http-access</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-log-retention-policy">
+ <title>dsconfig create-log-retention-policy</title>
+ <para>Creates Log Retention Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Log Retention Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Log Retention Policy which should be created. The value for TYPE can be one of: custom | file-count | free-disk-space | size-limit</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-log-rotation-policy">
+ <title>dsconfig create-log-rotation-policy</title>
+ <para>Creates Log Rotation Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Log Rotation Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Log Rotation Policy which should be created. The value for TYPE can be one of: custom | fixed-time | size-limit | time-limit</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-matching-rule">
+ <title>dsconfig create-matching-rule</title>
+ <para>Creates Matching Rules</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--rule-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Matching Rule</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Matching Rule which should be created (Default: generic). The value for TYPE can be one of: collation | generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-monitor-provider">
+ <title>dsconfig create-monitor-provider</title>
+ <para>Creates Monitor Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Monitor Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Monitor Provider which should be created. The value for TYPE can be one of: client-connection | custom | entry-cache | memory-usage | stack-trace | system-info | version</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-password-generator">
+ <title>dsconfig create-password-generator</title>
+ <para>Creates Password Generators</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--generator-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Password Generator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Password Generator which should be created. The value for TYPE can be one of: custom | random</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-password-policy">
+ <title>dsconfig create-password-policy</title>
+ <para>Creates Authentication Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Authentication Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Authentication Policy which should be created. The value for TYPE can be one of: ldap-pass-through | password-policy</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-password-storage-scheme">
+ <title>dsconfig create-password-storage-scheme</title>
+ <para>Creates Password Storage Schemes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--scheme-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Password Storage Scheme</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Password Storage Scheme which should be created. The value for TYPE can be one of: aes | base64 | blowfish | clear | crypt | custom | md5 | pbkdf2 | rc4 | salted-md5 | salted-sha1 | salted-sha256 | salted-sha384 | salted-sha512 | sha1 | triple-des</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-password-validator">
+ <title>dsconfig create-password-validator</title>
+ <para>Creates Password Validators</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--validator-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Password Validator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Password Validator which should be created. The value for TYPE can be one of: attribute-value | character-set | custom | dictionary | length-based | repeated-characters | similarity-based | unique-characters</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-plugin">
+ <title>dsconfig create-plugin</title>
+ <para>Creates Plugins</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--plugin-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Plugin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Plugin which should be created. The value for TYPE can be one of: attribute-cleanup | change-number-control | custom | entry-uuid | fractional-ldif-import | last-mod | ldap-attribute-description-list | password-policy-import | profiler | referential-integrity | samba-password | seven-bit-clean | unique-attribute</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-replication-domain">
+ <title>dsconfig create-replication-domain</title>
+ <para>Creates Replication Domains</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--domain-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Replication Domain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Replication Domain which should be created (Default: generic). The value for TYPE can be one of: generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-replication-server">
+ <title>dsconfig create-replication-server</title>
+ <para>Creates Replication Servers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Replication Server which should be created (Default: generic). The value for TYPE can be one of: generic</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-sasl-mechanism-handler">
+ <title>dsconfig create-sasl-mechanism-handler</title>
+ <para>Creates SASL Mechanism Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the new SASL Mechanism Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of SASL Mechanism Handler which should be created. The value for TYPE can be one of: anonymous | cram-md5 | custom | digest-md5 | external | gssapi | plain</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-synchronization-provider">
+ <title>dsconfig create-synchronization-provider</title>
+ <para>Creates Synchronization Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Synchronization Provider which should be created. The value for TYPE can be one of: custom | replication</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-trust-manager-provider">
+ <title>dsconfig create-trust-manager-provider</title>
+ <para>Creates Trust Manager Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the new Trust Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Trust Manager Provider which should be created. The value for TYPE can be one of: blind | custom | file-based</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-create-virtual-attribute">
+ <title>dsconfig create-virtual-attribute</title>
+ <para>Creates Virtual Attributes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--name {name}</option></term>
+ <listitem>
+ <para>The name of the new Virtual Attribute</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of Virtual Attribute which should be created. The value for TYPE can be one of: collective-attribute-subentries | custom | entity-tag | entry-dn | entry-uuid | governing-structure-rule | has-subordinates | is-member-of | member | num-subordinates | password-expiration-time | password-policy-subentry | structural-object-class | subschema-subentry | user-defined</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-access-log-filtering-criteria">
+ <title>dsconfig delete-access-log-filtering-criteria</title>
+ <para>Deletes Access Log Filtering Criteria</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--criteria-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Filtering Criteria</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Access Log Filtering Criteria</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-account-status-notification-handler">
+ <title>dsconfig delete-account-status-notification-handler</title>
+ <para>Deletes Account Status Notification Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Account Status Notification Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Account Status Notification Handlers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-alert-handler">
+ <title>dsconfig delete-alert-handler</title>
+ <para>Deletes Alert Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Alert Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Alert Handlers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-attribute-syntax">
+ <title>dsconfig delete-attribute-syntax</title>
+ <para>Deletes Attribute Syntaxes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--syntax-name {name}</option></term>
+ <listitem>
+ <para>The name of the Attribute Syntax</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Attribute Syntaxes</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-backend">
+ <title>dsconfig delete-backend</title>
+ <para>Deletes Backends</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Backends</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-certificate-mapper">
+ <title>dsconfig delete-certificate-mapper</title>
+ <para>Deletes Certificate Mappers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the Certificate Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Certificate Mappers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-connection-handler">
+ <title>dsconfig delete-connection-handler</title>
+ <para>Deletes Connection Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Connection Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Connection Handlers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-debug-target">
+ <title>dsconfig delete-debug-target</title>
+ <para>Deletes Debug Targets</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--target-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Target</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Debug Targets</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-entry-cache">
+ <title>dsconfig delete-entry-cache</title>
+ <para>Deletes Entry Caches</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--cache-name {name}</option></term>
+ <listitem>
+ <para>The name of the Entry Cache</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Entry Caches</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-extended-operation-handler">
+ <title>dsconfig delete-extended-operation-handler</title>
+ <para>Deletes Extended Operation Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Extended Operation Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Extended Operation Handlers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-group-implementation">
+ <title>dsconfig delete-group-implementation</title>
+ <para>Deletes Group Implementations</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--implementation-name {name}</option></term>
+ <listitem>
+ <para>The name of the Group Implementation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Group Implementations</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-identity-mapper">
+ <title>dsconfig delete-identity-mapper</title>
+ <para>Deletes Identity Mappers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the Identity Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Identity Mappers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-key-manager-provider">
+ <title>dsconfig delete-key-manager-provider</title>
+ <para>Deletes Key Manager Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Key Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Key Manager Providers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-local-db-index">
+ <title>dsconfig delete-local-db-index</title>
+ <para>Deletes Local DB Indexes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Local DB Indexes</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-local-db-vlv-index">
+ <title>dsconfig delete-local-db-vlv-index</title>
+ <para>Deletes Local DB VLV Indexes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB VLV Index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Local DB VLV Indexes</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-log-publisher">
+ <title>dsconfig delete-log-publisher</title>
+ <para>Deletes Log Publishers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Log Publishers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-log-retention-policy">
+ <title>dsconfig delete-log-retention-policy</title>
+ <para>Deletes Log Retention Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Retention Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Log Retention Policies</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-log-rotation-policy">
+ <title>dsconfig delete-log-rotation-policy</title>
+ <para>Deletes Log Rotation Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Rotation Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Log Rotation Policies</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-matching-rule">
+ <title>dsconfig delete-matching-rule</title>
+ <para>Deletes Matching Rules</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--rule-name {name}</option></term>
+ <listitem>
+ <para>The name of the Matching Rule</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Matching Rules</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-monitor-provider">
+ <title>dsconfig delete-monitor-provider</title>
+ <para>Deletes Monitor Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Monitor Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Monitor Providers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-password-generator">
+ <title>dsconfig delete-password-generator</title>
+ <para>Deletes Password Generators</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--generator-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Generator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Password Generators</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-password-policy">
+ <title>dsconfig delete-password-policy</title>
+ <para>Deletes Authentication Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Authentication Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Authentication Policies</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-password-storage-scheme">
+ <title>dsconfig delete-password-storage-scheme</title>
+ <para>Deletes Password Storage Schemes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--scheme-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Storage Scheme</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Password Storage Schemes</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-password-validator">
+ <title>dsconfig delete-password-validator</title>
+ <para>Deletes Password Validators</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--validator-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Validator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Password Validators</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-plugin">
+ <title>dsconfig delete-plugin</title>
+ <para>Deletes Plugins</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--plugin-name {name}</option></term>
+ <listitem>
+ <para>The name of the Plugin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Plugins</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-replication-domain">
+ <title>dsconfig delete-replication-domain</title>
+ <para>Deletes Replication Domains</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--domain-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Domain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Replication Domains</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-replication-server">
+ <title>dsconfig delete-replication-server</title>
+ <para>Deletes Replication Servers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Replication Servers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-sasl-mechanism-handler">
+ <title>dsconfig delete-sasl-mechanism-handler</title>
+ <para>Deletes SASL Mechanism Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the SASL Mechanism Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent SASL Mechanism Handlers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-synchronization-provider">
+ <title>dsconfig delete-synchronization-provider</title>
+ <para>Deletes Synchronization Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Synchronization Providers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-trust-manager-provider">
+ <title>dsconfig delete-trust-manager-provider</title>
+ <para>Deletes Trust Manager Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Trust Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Trust Manager Providers</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-delete-virtual-attribute">
+ <title>dsconfig delete-virtual-attribute</title>
+ <para>Deletes Virtual Attributes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--name {name}</option></term>
+ <listitem>
+ <para>The name of the Virtual Attribute</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f | --force</option></term>
+ <listitem>
+ <para>Ignore non-existent Virtual Attributes</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-access-control-handler-prop">
+ <title>dsconfig get-access-control-handler-prop</title>
+ <para>Shows Access Control Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-access-log-filtering-criteria-prop">
+ <title>dsconfig get-access-log-filtering-criteria-prop</title>
+ <para>Shows Access Log Filtering Criteria properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--criteria-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Filtering Criteria</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-account-status-notification-handler-prop">
+ <title>dsconfig get-account-status-notification-handler-prop</title>
+ <para>Shows Account Status Notification Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Account Status Notification Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-administration-connector-prop">
+ <title>dsconfig get-administration-connector-prop</title>
+ <para>Shows Administration Connector properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-alert-handler-prop">
+ <title>dsconfig get-alert-handler-prop</title>
+ <para>Shows Alert Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Alert Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-attribute-syntax-prop">
+ <title>dsconfig get-attribute-syntax-prop</title>
+ <para>Shows Attribute Syntax properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--syntax-name {name}</option></term>
+ <listitem>
+ <para>The name of the Attribute Syntax</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-backend-prop">
+ <title>dsconfig get-backend-prop</title>
+ <para>Shows Backend properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-certificate-mapper-prop">
+ <title>dsconfig get-certificate-mapper-prop</title>
+ <para>Shows Certificate Mapper properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the Certificate Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-connection-handler-prop">
+ <title>dsconfig get-connection-handler-prop</title>
+ <para>Shows Connection Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Connection Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-crypto-manager-prop">
+ <title>dsconfig get-crypto-manager-prop</title>
+ <para>Shows Crypto Manager properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-debug-target-prop">
+ <title>dsconfig get-debug-target-prop</title>
+ <para>Shows Debug Target properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--target-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Target</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-entry-cache-prop">
+ <title>dsconfig get-entry-cache-prop</title>
+ <para>Shows Entry Cache properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--cache-name {name}</option></term>
+ <listitem>
+ <para>The name of the Entry Cache</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-extended-operation-handler-prop">
+ <title>dsconfig get-extended-operation-handler-prop</title>
+ <para>Shows Extended Operation Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Extended Operation Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-external-changelog-domain-prop">
+ <title>dsconfig get-external-changelog-domain-prop</title>
+ <para>Shows External Changelog Domain properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--domain-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Domain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-global-configuration-prop">
+ <title>dsconfig get-global-configuration-prop</title>
+ <para>Shows Global Configuration properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-group-implementation-prop">
+ <title>dsconfig get-group-implementation-prop</title>
+ <para>Shows Group Implementation properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--implementation-name {name}</option></term>
+ <listitem>
+ <para>The name of the Group Implementation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-identity-mapper-prop">
+ <title>dsconfig get-identity-mapper-prop</title>
+ <para>Shows Identity Mapper properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the Identity Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-key-manager-provider-prop">
+ <title>dsconfig get-key-manager-provider-prop</title>
+ <para>Shows Key Manager Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Key Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-local-db-index-prop">
+ <title>dsconfig get-local-db-index-prop</title>
+ <para>Shows Local DB Index properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-local-db-vlv-index-prop">
+ <title>dsconfig get-local-db-vlv-index-prop</title>
+ <para>Shows Local DB VLV Index properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB VLV Index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-log-publisher-prop">
+ <title>dsconfig get-log-publisher-prop</title>
+ <para>Shows Log Publisher properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-log-retention-policy-prop">
+ <title>dsconfig get-log-retention-policy-prop</title>
+ <para>Shows Log Retention Policy properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Retention Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-log-rotation-policy-prop">
+ <title>dsconfig get-log-rotation-policy-prop</title>
+ <para>Shows Log Rotation Policy properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Rotation Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-matching-rule-prop">
+ <title>dsconfig get-matching-rule-prop</title>
+ <para>Shows Matching Rule properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--rule-name {name}</option></term>
+ <listitem>
+ <para>The name of the Matching Rule</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-monitor-provider-prop">
+ <title>dsconfig get-monitor-provider-prop</title>
+ <para>Shows Monitor Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Monitor Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-password-generator-prop">
+ <title>dsconfig get-password-generator-prop</title>
+ <para>Shows Password Generator properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--generator-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Generator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-password-policy-prop">
+ <title>dsconfig get-password-policy-prop</title>
+ <para>Shows Authentication Policy properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Authentication Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-password-storage-scheme-prop">
+ <title>dsconfig get-password-storage-scheme-prop</title>
+ <para>Shows Password Storage Scheme properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--scheme-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Storage Scheme</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-password-validator-prop">
+ <title>dsconfig get-password-validator-prop</title>
+ <para>Shows Password Validator properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--validator-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Validator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-plugin-prop">
+ <title>dsconfig get-plugin-prop</title>
+ <para>Shows Plugin properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--plugin-name {name}</option></term>
+ <listitem>
+ <para>The name of the Plugin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-plugin-root-prop">
+ <title>dsconfig get-plugin-root-prop</title>
+ <para>Shows Plugin Root properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-replication-domain-prop">
+ <title>dsconfig get-replication-domain-prop</title>
+ <para>Shows Replication Domain properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--domain-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Domain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-replication-server-prop">
+ <title>dsconfig get-replication-server-prop</title>
+ <para>Shows Replication Server properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-root-dn-prop">
+ <title>dsconfig get-root-dn-prop</title>
+ <para>Shows Root DN properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-root-dse-backend-prop">
+ <title>dsconfig get-root-dse-backend-prop</title>
+ <para>Shows Root DSE Backend properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-sasl-mechanism-handler-prop">
+ <title>dsconfig get-sasl-mechanism-handler-prop</title>
+ <para>Shows SASL Mechanism Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the SASL Mechanism Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-synchronization-provider-prop">
+ <title>dsconfig get-synchronization-provider-prop</title>
+ <para>Shows Synchronization Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-trust-manager-provider-prop">
+ <title>dsconfig get-trust-manager-provider-prop</title>
+ <para>Shows Trust Manager Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Trust Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-virtual-attribute-prop">
+ <title>dsconfig get-virtual-attribute-prop</title>
+ <para>Shows Virtual Attribute properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--name {name}</option></term>
+ <listitem>
+ <para>The name of the Virtual Attribute</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-get-work-queue-prop">
+ <title>dsconfig get-work-queue-prop</title>
+ <para>Shows Work Queue properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E | --record</option></term>
+ <listitem>
+ <para>Modifies the display output to show one property value per line</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-access-log-filtering-criteria">
+ <title>dsconfig list-access-log-filtering-criteria</title>
+ <para>Lists existing Access Log Filtering Criteria</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-account-status-notification-handlers">
+ <title>dsconfig list-account-status-notification-handlers</title>
+ <para>Lists existing Account Status Notification Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-alert-handlers">
+ <title>dsconfig list-alert-handlers</title>
+ <para>Lists existing Alert Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-attribute-syntaxes">
+ <title>dsconfig list-attribute-syntaxes</title>
+ <para>Lists existing Attribute Syntaxes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-backends">
+ <title>dsconfig list-backends</title>
+ <para>Lists existing Backends</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-certificate-mappers">
+ <title>dsconfig list-certificate-mappers</title>
+ <para>Lists existing Certificate Mappers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-connection-handlers">
+ <title>dsconfig list-connection-handlers</title>
+ <para>Lists existing Connection Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-debug-targets">
+ <title>dsconfig list-debug-targets</title>
+ <para>Lists existing Debug Targets</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-entry-caches">
+ <title>dsconfig list-entry-caches</title>
+ <para>Lists existing Entry Caches</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-extended-operation-handlers">
+ <title>dsconfig list-extended-operation-handlers</title>
+ <para>Lists existing Extended Operation Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-group-implementations">
+ <title>dsconfig list-group-implementations</title>
+ <para>Lists existing Group Implementations</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-identity-mappers">
+ <title>dsconfig list-identity-mappers</title>
+ <para>Lists existing Identity Mappers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-key-manager-providers">
+ <title>dsconfig list-key-manager-providers</title>
+ <para>Lists existing Key Manager Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-local-db-indexes">
+ <title>dsconfig list-local-db-indexes</title>
+ <para>Lists existing Local DB Indexes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-local-db-vlv-indexes">
+ <title>dsconfig list-local-db-vlv-indexes</title>
+ <para>Lists existing Local DB VLV Indexes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-log-publishers">
+ <title>dsconfig list-log-publishers</title>
+ <para>Lists existing Log Publishers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-log-retention-policies">
+ <title>dsconfig list-log-retention-policies</title>
+ <para>Lists existing Log Retention Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-log-rotation-policies">
+ <title>dsconfig list-log-rotation-policies</title>
+ <para>Lists existing Log Rotation Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-matching-rules">
+ <title>dsconfig list-matching-rules</title>
+ <para>Lists existing Matching Rules</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-monitor-providers">
+ <title>dsconfig list-monitor-providers</title>
+ <para>Lists existing Monitor Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-password-generators">
+ <title>dsconfig list-password-generators</title>
+ <para>Lists existing Password Generators</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-password-policies">
+ <title>dsconfig list-password-policies</title>
+ <para>Lists existing Password Policies</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-password-storage-schemes">
+ <title>dsconfig list-password-storage-schemes</title>
+ <para>Lists existing Password Storage Schemes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-password-validators">
+ <title>dsconfig list-password-validators</title>
+ <para>Lists existing Password Validators</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-plugins">
+ <title>dsconfig list-plugins</title>
+ <para>Lists existing Plugins</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-properties">
+ <title>dsconfig list-properties</title>
+ <para>Describes managed objects and their properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-c | --category {category}</option></term>
+ <listitem>
+ <para>The category of components whose properties should be described</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t | --type {type}</option></term>
+ <listitem>
+ <para>The type of components whose properties should be described. The value for TYPE must be one of the component types associated with the CATEGORY specified using the "--category" option</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--inherited</option></term>
+ <listitem>
+ <para>Modifies the display output to show the inherited properties of components</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-replication-domains">
+ <title>dsconfig list-replication-domains</title>
+ <para>Lists existing Replication Domains</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-replication-server">
+ <title>dsconfig list-replication-server</title>
+ <para>Lists existing Replication Server</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-sasl-mechanism-handlers">
+ <title>dsconfig list-sasl-mechanism-handlers</title>
+ <para>Lists existing SASL Mechanism Handlers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-synchronization-providers">
+ <title>dsconfig list-synchronization-providers</title>
+ <para>Lists existing Synchronization Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-trust-manager-providers">
+ <title>dsconfig list-trust-manager-providers</title>
+ <para>Lists existing Trust Manager Providers</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-list-virtual-attributes">
+ <title>dsconfig list-virtual-attributes</title>
+ <para>Lists existing Virtual Attributes</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--property {property}</option></term>
+ <listitem>
+ <para>The name of a property to be displayed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z | --unit-size {unit}</option></term>
+ <listitem>
+ <para>Display size data using the specified unit. The value for UNIT can be one of b, kb, mb, gb, or tb (bytes, kilobytes, megabytes, gigabytes, or terabytes)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m | --unit-time {unit}</option></term>
+ <listitem>
+ <para>Display time data using the specified unit. The value for UNIT can be one of ms, s, m, h, d, or w (milliseconds, seconds, minutes, hours, days, or weeks)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-access-control-handler-prop">
+ <title>dsconfig set-access-control-handler-prop</title>
+ <para>Modifies Access Control Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-access-log-filtering-criteria-prop">
+ <title>dsconfig set-access-log-filtering-criteria-prop</title>
+ <para>Modifies Access Log Filtering Criteria properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--criteria-name {name}</option></term>
+ <listitem>
+ <para>The name of the Access Log Filtering Criteria</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-account-status-notification-handler-prop">
+ <title>dsconfig set-account-status-notification-handler-prop</title>
+ <para>Modifies Account Status Notification Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Account Status Notification Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-administration-connector-prop">
+ <title>dsconfig set-administration-connector-prop</title>
+ <para>Modifies Administration Connector properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-alert-handler-prop">
+ <title>dsconfig set-alert-handler-prop</title>
+ <para>Modifies Alert Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Alert Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-attribute-syntax-prop">
+ <title>dsconfig set-attribute-syntax-prop</title>
+ <para>Modifies Attribute Syntax properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--syntax-name {name}</option></term>
+ <listitem>
+ <para>The name of the Attribute Syntax</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-backend-prop">
+ <title>dsconfig set-backend-prop</title>
+ <para>Modifies Backend properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-certificate-mapper-prop">
+ <title>dsconfig set-certificate-mapper-prop</title>
+ <para>Modifies Certificate Mapper properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the Certificate Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-connection-handler-prop">
+ <title>dsconfig set-connection-handler-prop</title>
+ <para>Modifies Connection Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Connection Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-crypto-manager-prop">
+ <title>dsconfig set-crypto-manager-prop</title>
+ <para>Modifies Crypto Manager properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-debug-target-prop">
+ <title>dsconfig set-debug-target-prop</title>
+ <para>Modifies Debug Target properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--target-name {name}</option></term>
+ <listitem>
+ <para>The name of the Debug Target</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-entry-cache-prop">
+ <title>dsconfig set-entry-cache-prop</title>
+ <para>Modifies Entry Cache properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--cache-name {name}</option></term>
+ <listitem>
+ <para>The name of the Entry Cache</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-extended-operation-handler-prop">
+ <title>dsconfig set-extended-operation-handler-prop</title>
+ <para>Modifies Extended Operation Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the Extended Operation Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-external-changelog-domain-prop">
+ <title>dsconfig set-external-changelog-domain-prop</title>
+ <para>Modifies External Changelog Domain properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--domain-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Domain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-global-configuration-prop">
+ <title>dsconfig set-global-configuration-prop</title>
+ <para>Modifies Global Configuration properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-group-implementation-prop">
+ <title>dsconfig set-group-implementation-prop</title>
+ <para>Modifies Group Implementation properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--implementation-name {name}</option></term>
+ <listitem>
+ <para>The name of the Group Implementation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-identity-mapper-prop">
+ <title>dsconfig set-identity-mapper-prop</title>
+ <para>Modifies Identity Mapper properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--mapper-name {name}</option></term>
+ <listitem>
+ <para>The name of the Identity Mapper</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-key-manager-provider-prop">
+ <title>dsconfig set-key-manager-provider-prop</title>
+ <para>Modifies Key Manager Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Key Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-local-db-index-prop">
+ <title>dsconfig set-local-db-index-prop</title>
+ <para>Modifies Local DB Index properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-local-db-vlv-index-prop">
+ <title>dsconfig set-local-db-vlv-index-prop</title>
+ <para>Modifies Local DB VLV Index properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--backend-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB Backend</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--index-name {name}</option></term>
+ <listitem>
+ <para>The name of the Local DB VLV Index</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-log-publisher-prop">
+ <title>dsconfig set-log-publisher-prop</title>
+ <para>Modifies Log Publisher properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--publisher-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Publisher</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-log-retention-policy-prop">
+ <title>dsconfig set-log-retention-policy-prop</title>
+ <para>Modifies Log Retention Policy properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Retention Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-log-rotation-policy-prop">
+ <title>dsconfig set-log-rotation-policy-prop</title>
+ <para>Modifies Log Rotation Policy properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Log Rotation Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-matching-rule-prop">
+ <title>dsconfig set-matching-rule-prop</title>
+ <para>Modifies Matching Rule properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--rule-name {name}</option></term>
+ <listitem>
+ <para>The name of the Matching Rule</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-monitor-provider-prop">
+ <title>dsconfig set-monitor-provider-prop</title>
+ <para>Modifies Monitor Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Monitor Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-password-generator-prop">
+ <title>dsconfig set-password-generator-prop</title>
+ <para>Modifies Password Generator properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--generator-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Generator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-password-policy-prop">
+ <title>dsconfig set-password-policy-prop</title>
+ <para>Modifies Authentication Policy properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--policy-name {name}</option></term>
+ <listitem>
+ <para>The name of the Authentication Policy</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-password-storage-scheme-prop">
+ <title>dsconfig set-password-storage-scheme-prop</title>
+ <para>Modifies Password Storage Scheme properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--scheme-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Storage Scheme</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-password-validator-prop">
+ <title>dsconfig set-password-validator-prop</title>
+ <para>Modifies Password Validator properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--validator-name {name}</option></term>
+ <listitem>
+ <para>The name of the Password Validator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-plugin-prop">
+ <title>dsconfig set-plugin-prop</title>
+ <para>Modifies Plugin properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--plugin-name {name}</option></term>
+ <listitem>
+ <para>The name of the Plugin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-plugin-root-prop">
+ <title>dsconfig set-plugin-root-prop</title>
+ <para>Modifies Plugin Root properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-replication-domain-prop">
+ <title>dsconfig set-replication-domain-prop</title>
+ <para>Modifies Replication Domain properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--domain-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Domain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-replication-server-prop">
+ <title>dsconfig set-replication-server-prop</title>
+ <para>Modifies Replication Server properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Replication Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-root-dn-prop">
+ <title>dsconfig set-root-dn-prop</title>
+ <para>Modifies Root DN properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-root-dse-backend-prop">
+ <title>dsconfig set-root-dse-backend-prop</title>
+ <para>Modifies Root DSE Backend properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-sasl-mechanism-handler-prop">
+ <title>dsconfig set-sasl-mechanism-handler-prop</title>
+ <para>Modifies SASL Mechanism Handler properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--handler-name {name}</option></term>
+ <listitem>
+ <para>The name of the SASL Mechanism Handler</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-synchronization-provider-prop">
+ <title>dsconfig set-synchronization-provider-prop</title>
+ <para>Modifies Synchronization Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Synchronization Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-trust-manager-provider-prop">
+ <title>dsconfig set-trust-manager-provider-prop</title>
+ <para>Modifies Trust Manager Provider properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--provider-name {name}</option></term>
+ <listitem>
+ <para>The name of the Trust Manager Provider</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-virtual-attribute-prop">
+ <title>dsconfig set-virtual-attribute-prop</title>
+ <para>Modifies Virtual Attribute properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--name {name}</option></term>
+ <listitem>
+ <para>The name of the Virtual Attribute</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+<refsect2 xml:id="dsconfig-set-work-queue-prop">
+ <title>dsconfig set-work-queue-prop</title>
+ <para>Modifies Work Queue properties</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--set {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Assigns a value to a property where PROP is the name of the property and VALUE is the single value to be assigned. Specify the same property multiple times in order to assign more than one value to it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--reset {property}</option></term>
+ <listitem>
+ <para>Resets a property back to its default values where PROP is the name of the property to be reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--add {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Adds a single value to a property where PROP is the name of the property and VALUE is the single value to be added</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--remove {PROP:VALUE}</option></term>
+ <listitem>
+ <para>Removes a single value from a property where PROP is the name of the property and VALUE is the single value to be removed</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>Much of the <citetitle>OpenDJ Administration Guide</citetitle> consists
+ of <command>dsconfig</command> examples with text in between. This section
+ therefore remains short.</para>
+
+ <para>The following example starts <command>dsconfig</command> in interactive,
+ menu-driven mode on the default port of the current host.</para>
+ <screen>$ dsconfig -h `hostname` -p 4444 -D "cn=Directory Manager" -w password
+
+>>>> OpenDJ configuration console main menu
+
+What do you want to configure?
+
+ 1) Access Control Handler 21) Log Publisher
+ 2) Access Log Filtering Criteria 22) Log Retention Policy
+ 3) Account Status Notification Handler 23) Log Rotation Policy
+ 4) Administration Connector 24) Matching Rule
+ 5) Alert Handler 25) Monitor Provider
+ 6) Attribute Syntax 26) Password Generator
+ 7) Backend 27) Password Policy
+ 8) Certificate Mapper 28) Password Storage Scheme
+ 9) Connection Handler 29) Password Validator
+ 10) Crypto Manager 30) Plugin
+ 11) Debug Target 31) Plugin Root
+ 12) Entry Cache 32) Replication Domain
+ 13) Extended Operation Handler 33) Replication Server
+ 14) External Changelog Domain 34) Root DN
+ 15) Global Configuration 35) Root DSE Backend
+ 16) Group Implementation 36) SASL Mechanism Handler
+ 17) Identity Mapper 37) Synchronization Provider
+ 18) Key Manager Provider 38) Trust Manager Provider
+ 19) Local DB Index 39) Virtual Attribute
+ 20) Local DB VLV Index 40) Work Queue
+
+ q) quit
+
+Enter choice: </screen>
+
+ <para>The following examples demonstrates generating a batch file that
+ corresponds to an interactive session enabling the debug log. The example
+ then demonstates using a modified batch file to disable the debug log.</para>
+ <screen>$ dsconfig
+ --hostname `hostname`
+ --port 4444
+ --bindDN "cn=Directory Manager"
+ --bindPassword password
+ --commandFilePath ~/enable-debug-log.batch
+ ...
+$ cat ~/enable-debug-log.batch
+# dsconfig session start date: 19/Oct/2011:08:52:22 +0000
+
+# Session operation number: 1
+# Operation date: 19/Oct/2011:08:55:06 +0000
+dsconfig set-log-publisher-prop \
+ --publisher-name File-Based\ Debug\ Logger \
+ --set enabled:true \
+ --hostname opendj.example.com \
+ --port 4444 \
+ --trustStorePath /path/to/opendj/config/admin-truststore \
+ --bindDN cn=Directory\ Manager \
+ --bindPassword ****** \
+ --no-prompt
+
+$ cp ~/enable-debug-log.batch ~/disable-debug-log.batch
+$ vi ~/disable-debug-log.batch
+$ cat ~/disable-debug-log.batch
+set-log-publisher-prop \
+ --publisher-name File-Based\ Debug\ Logger \
+ --set enabled:false \
+ --hostname opendj.example.com \
+ --port 4444 \
+ --trustStorePath /path/to/opendj/config/admin-truststore \
+ --bindDN cn=Directory\ Manager \
+ --bindPassword password \
+ --no-prompt
+
+$ dsconfig --batchFilePath ~/disable-debug-log.batch --no-prompt
+set-log-publisher-prop
+--publisher-name
+File-Based Debug Logger
+--set
+enabled:false
+--hostname
+opendj.example.com
+--port
+4444
+--trustStorePath
+/path/to/opendj/config/admin-truststore
+--bindDN
+cn=Directory Manager
+--bindPassword
+password
+--no-prompt
+
+$</screen>
+ <para>Notice that the original command file looks like a shell script with
+ the bind password value replaced by asterisks. To pass the content as a batch
+ file to <command>dsconfig</command>, strip <literal>dsconfig</literal>
+ itself, and include the bind password for the administrative user (or
+ replace that option with an alternative, such as reading the password from
+ a file).</para>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsframework.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsframework.xml
new file mode 100644
index 0000000..131cb09
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsframework.xml
@@ -0,0 +1,295 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='dsframework-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>dsframework</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>dsframework</refname>
+ <refpurpose>manage OpenDJ administration framework</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dsframework</command>
+ <command><replaceable>subcommand</replaceable></command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform operations in the directory server
+ administration framework.</para>
+ <para>This utility has no interactive mode. Consider using <option>-X</option>
+ if you authenticate over a secure connection protected with a self-signed
+ certificate.</para>
+ </refsect1>
+ <refsect1>
+ <title>Subcommands</title>
+
+ <para>The <command>dsconfig</command> command provides many subcommands.
+ Use the following options to view help for subcommands.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--help-all</option></term>
+ <listitem>
+ <para>Display all subcommands</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--help-admin-user</option></term>
+ <listitem>
+ <para>Display subcommands relating to admin-user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--help-server</option></term>
+ <listitem>
+ <para>Display subcommands relating to server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--help-server-group</option></term>
+ <listitem>
+ <para>Display subcommands relating to server-group</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>For help with individual subcommands, use <command>dsframework
+ <replaceable>subcommand</replaceable> --help</command>.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --adminUID {adminUID}</option></term>
+ <listitem>
+ <para>User ID of the global administrator to use to bind to the server.
+ For the <command>enable</command> subcommand, if no global administrator
+ was defined previously for any servers, the global administrator will be
+ created using the UID provided.</para>
+ <para>Default value: admin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --adminPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Global administrator password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ <para>Default value: /path/to/opendj/config/admin-truststore</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --adminPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password for the global administrator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>This example lists server properties.</para>
+ <screen>
+$ dsframework -p 4444 -h opendj.example.com -D "cn=Directory Manager"
+ -w password -X list-server-properties
+Option Types:
+
+ r -- Property value(s) are readable
+ w -- Property value(s) are writable
+ m -- The property is mandatory
+ s -- The property is single-valued
+
+Property Options Syntax Default value
+-------------------------------------------------------------------------
+ldapsport rw-- INTEGER -
+certificate rw-s STRING -
+hostname r-ms STRING localhost
+ldapport rwm- INTEGER 389
+jmxsEnabled rw-s BOOLEAN false
+instancepath rw-s STRING -
+ldapsEnabled rw-s BOOLEAN false
+jmxsport rw-- INTEGER -
+os rw-s STRING -
+ds-cfg-key-id rw-s STRING -
+jmxport rw-- INTEGER -
+description rw-s STRING -
+id rw-s STRING -
+startTLSEnabled rw-s BOOLEAN false
+jmxEnabled rw-s BOOLEAN false
+ds-cfg-public-key-certificate rw-s CERTIFICATE_BINARY -
+location rw-s STRING -
+ldapEnabled rw-s BOOLEAN false</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsjavaproperties.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsjavaproperties.xml
new file mode 100644
index 0000000..88ca722
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsjavaproperties.xml
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='dsjavaproperties-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>dsjavaproperties</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>dsjavaproperties</refname>
+ <refpurpose>apply OpenDJ Java home and JVM settings</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dsjavaproperties</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to change the Java arguments and Java home
+ that are used by other server commands.</para>
+ <para>Before launching the command, edit the properties file located in
+ <filename>/path/to/opendj/config/java.properties</filename> to specify the
+ Java arguments and Java home. When you have edited the properties file, run
+ this command for the changes to be taken into account.</para>
+ <para>Changes apply to the current server installation. No modifications
+ are made to your environment variables.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Run the tool in quiet mode. Quiet mode will not output progress
+ information to standard output.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>This command depends on the content of the
+ <filename>config/java.properties</filename> file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>$ dsjavaproperties
+The operation was successful. The server commands will use the java arguments
+ and java home specified in the properties file located in
+ /path/to/opendj/config/java.properties</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsreplication.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsreplication.xml
new file mode 100644
index 0000000..100668e
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-dsreplication.xml
@@ -0,0 +1,403 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='dsreplication-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>dsreplication</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>dsreplication</refname>
+ <refpurpose>manage OpenDJ directory data replication</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>dsreplication</command>
+ <command><replaceable>subcommand</replaceable></command>
+ <arg>options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to configure replication between servers so
+ that the data of the servers is synchronized. For replication to work you
+ must first enable replication using the <command>enable</command> subcommand
+ and then initialize the contents of one of the servers with the contents of
+ the other using the <command>initialize</command> subcommand.</para>
+ </refsect1>
+ <refsect1>
+ <title>Subcommands</title>
+ <para>The following subcommands are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><command>disable</command></term>
+ <listitem>
+ <para>Disable replication on the specified server for the provided base
+ DN and removes references in the other servers with which it is
+ replicating data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>enable</command></term>
+ <listitem>
+ <para>Update the configuration of the servers to replicate the data
+ under the specified base DN. If one of the specified servers is already
+ replicating the data under the base DN with other servers, executing this
+ subcommand will update the configuration of all the servers. Thus it is
+ sufficient to execute the command line once for each server added to the
+ replication topology.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>initialize</command></term>
+ <listitem>
+ <para>Initialize the contents of the data under the specified base DN
+ on the destination server with the contents on the source server. This
+ operation is required after enabling replication in order replication to
+ work. <command>initialize-all</command> can also be used for this
+ purpose.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>initialize-all</command></term>
+ <listitem>
+ <para>Initialize the contents of the data under the specified base DN
+ on all the servers whose contents are being replicated with the contents
+ on the specified server. This operation is required after enabling
+ replication for replication to work. Run <command>initialize</command>
+ for each server to achieve the same effect.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>post-external-initialization</command></term>
+ <listitem>
+ <para>This subcommand must be called after initializing the contents of
+ all the replicated servers using the <command>import-ldif</command>
+ command, or by copying the database. You must specify the list of base DNs
+ that have been initialized, and you must provide the credentials of any
+ of the servers that are being replicated. See
+ <command>pre-external-initialization --help</command> for more
+ information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>pre-external-initialization</command></term>
+ <listitem>
+ <para>This subcommand must be called before initializing the contents
+ of all the replicated servers using the <command>import-ldif</command>
+ command, or by copying the database. You must specify the list of base DNs
+ that have been initialized, and you must provide the credentials of any
+ of the servers that are being replicated. After calling this subcommand,
+ initialize the contents of all the servers in the topology, either by
+ using the same LDIF file or by copying the database to each of the
+ servers, then call the <command>post-external-initialization</command>
+ subcommand.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>purge-historical</command></term>
+ <listitem>
+ <para>Launch a purge processing of the historical information stored
+ in the user entries by replication. Since this processing may take a
+ while, you must specify a maximum duration.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>status</command></term>
+ <listitem>
+ <para>Display a list with the basic replication configuration of the
+ base DNs of the servers defined in the registration information. If
+ no base DNs are specified as parameter, information for all base DNs
+ is displayed.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--advanced</option></term>
+ <listitem>
+ <para>Access advanced settings when running this command in interactive
+ mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN of the data to be replicated, initialized or for which you
+ want to disable replication. Multiple base DNs can be provided by using
+ this option multiple times.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --adminUID {adminUID}</option></term>
+ <listitem>
+ <para>User ID of the global administrator to use to bind to the server.
+ For the <command>enable</command> subcommand, if no global administrator
+ was defined previously for any servers, the global administrator will be
+ created using the UID provided.</para>
+ <para>Default value: admin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --adminPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Global administrator password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ <para>Default value: /path/to/opendj/config/admin-truststore</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --adminPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password for the global administrator</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--commandFilePath {path}</option></term>
+ <listitem>
+ <para>The full path to the file where the equivalent non-interactive
+ commands will be written when this command is run in interactive
+ mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--displayCommand</option></term>
+ <listitem>
+ <para>Display the equivalent non-interactive option on standard output
+ when this command is run in interactive mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the command exits with an error.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Do not write progress information to standard output</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example enables and then initializes replication
+ for a new replica on <literal>opendj2.example.com</literal> from an existing
+ replica on <literal>opendj.example.com</literal>.</para>
+
+ <screen>$ dsreplication enable -I admin -w password -X -n -b dc=example,dc=com
+ --host1 opendj.example.com --port1 4444 --bindDN1 "cn=Directory Manager"
+ --bindPassword1 password --replicationPort1 8989
+ --host2 opendj2.example.com --port2 4444 --bindDN2 "cn=Directory Manager"
+ --bindPassword2 password --replicationPort2 8989
+
+Establishing connections ..... Done.
+Checking registration information ..... Done.
+Updating remote references on server opendj.example.com:4444 ..... Done.
+Configuring Replication port on server opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN dc=example,dc=com on server
+ opendj2.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj.example.com:4444 ..... Done.
+Updating registration configuration on server
+ opendj2.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj.example.com:4444 ..... Done.
+Updating replication configuration for baseDN cn=schema on server
+ opendj2.example.com:4444 ..... Done.
+Initializing registration information on server opendj2.example.com:4444 with
+ the contents of server opendj.example.com:4444 ..... Done.
+Initializing schema on server opendj2.example.com:4444 with the contents of
+ server opendj.example.com:4444 ..... Done.
+
+Replication has been successfully enabled. Note that for replication to
+ work you must initialize the contents of the base DN's that are being
+ replicated (use dsreplication initialize to do so).
+
+See
+/var/.../opends-replication-7958637258600693490.log
+for a detailed log of this operation.
+$ dsreplication initialize-all -I admin -w password -X -n -b dc=example,dc=com
+ -h opendj.example.com -p 4444
+
+Initializing base DN dc=example,dc=com with the contents from
+ opendj.example.com:4444: 160 entries processed (100 % complete).
+Base DN initialized successfully.
+
+See
+/var/.../opends-replication-5020375834904394170.log
+for a detailed log of this operation.</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-encode-password.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-encode-password.xml
new file mode 100644
index 0000000..b5546bc
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-encode-password.xml
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='encode-password-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>encode-password</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>encode-password</refname>
+ <refpurpose>encode a password with an OpenDJ storage scheme</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>encode-password</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to encode user passwords with a specified
+ storage scheme, or to determine whether a given clear-text value matches a
+ provided encoded password.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following global options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --authPasswordSyntax</option></term>
+ <listitem>
+ <para>Use the authentication password syntax rather than the user
+ password syntax.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --clearPassword {clearPW}</option></term>
+ <listitem>
+ <para>Clear-text password to encode or to compare against an encoded
+ password.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --encodedPassword {encodedPW}</option></term>
+ <listitem>
+ <para>Encoded password to compare against the clear-text password.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --encodedPasswordFile {file}</option></term>
+ <listitem>
+ <para>Encoded password file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --clearPasswordFile {file}</option></term>
+ <listitem>
+ <para>Clear-text password file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --interactivePassword</option></term>
+ <listitem>
+ <para>The password to encode or to compare against an encoded password is
+ interactively asked to the user.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --listSchemes</option></term>
+ <listitem>
+ <para>List available password storage schemes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --useCompareResultCode</option></term>
+ <listitem>
+ <para>Use the LDAP compare result as an exit code for the password
+ comparison.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --storageScheme {scheme}</option></term>
+ <listitem>
+ <para>Scheme to use for the encoded password.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>5</term>
+ <listitem>
+ <para>The <option>-r</option> option was used, and the compare did not
+ match.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>6</term>
+ <listitem>
+ <para>The <option>-r</option> option was used, and the compare did
+ match.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>other</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example encodes a password, and also shows comparison
+ of a password with the encoded value.</para>
+ <screen>$ encode-password -l
+3DES
+AES
+BASE64
+BLOWFISH
+CLEAR
+CRYPT
+MD5
+RC4
+SHA
+SMD5
+SSHA
+SSHA256
+SSHA384
+SSHA512
+$ encode-password -c secret12 -s CRYPT
+Encoded Password: "{CRYPT}ZulJ6Dy3TFnrE"
+$ encode-password -c secret12 -s CRYPT -e "{CRYPT}ZulJ6Dy3TFnrE" -r
+The provided clear-text and encoded passwords match
+$ echo $?
+6</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-export-ldif.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-export-ldif.xml
new file mode 100644
index 0000000..d7fa7a0
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-export-ldif.xml
@@ -0,0 +1,350 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='export-ldif-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>export-ldif</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>export-ldif</refname>
+ <refpurpose>export OpenDJ directory data in LDIF</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>export-ldif</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to export data from a directory server backend
+ in LDIF form.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --appendToLDIF</option></term>
+ <listitem>
+ <para>Append an existing LDIF file rather than overwriting it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --includeBranch {branchDN}</option></term>
+ <listitem>
+ <para>Base DN of a branch to include in the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-B, --excludeBranch {branchDN}</option></term>
+ <listitem>
+ <para>Base DN of a branch to exclude from the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --compress</option></term>
+ <listitem>
+ <para>Compress the LDIF data as it is exported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --excludeAttribute {attribute}</option></term>
+ <listitem>
+ <para>Attribute to exclude from the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --excludeFilter {filter}</option></term>
+ <listitem>
+ <para>Filter to identify entries to exclude from the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --includeAttribute {attribute}</option></term>
+ <listitem>
+ <para>Attribute to include in the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --includeFilter {filter}</option></term>
+ <listitem>
+ <para>Filter to identify entries to include in the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --ldifFile {ldifFile}</option></term>
+ <listitem>
+ <para>Path to the LDIF file to be written.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --backendID {backendName}</option></term>
+ <listitem>
+ <para>Backend ID for the backend to export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-O, --excludeOperational</option></term>
+ <listitem>
+ <para>Exclude operational attributes from the LDIF export.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--wrapColumn {wrapColumn}</option></term>
+ <listitem>
+ <para>Column at which to wrap long lines (0 for no wrapping).</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Task Backend Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Task Scheduling Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--completionNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified when the task
+ completes. This option may be specified more than once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--dependency {taskID}</option></term>
+ <listitem>
+ <para>ID of a task upon which this task depends. A task will not start
+ execution until all its dependencies have completed execution.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--errorNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified if an error occurs
+ when this task executes. This option may be specified more than
+ once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--failedDependencyAction {action}</option></term>
+ <listitem>
+ <para>Action this task will take should one if its dependent tasks fail.
+ The value must be one of PROCESS, CANCEL, DISABLE. If not specified
+ defaults to CANCEL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--recurringTask {schedulePattern}</option></term>
+ <listitem>
+ <para>Indicates the task is recurring and will be scheduled according
+ to the value argument expressed in crontab(5) compatible time/date
+ pattern.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --start {startTime}</option></term>
+ <listitem>
+ <para>Indicates the date/time at which this operation will start when
+ scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC
+ time or YYYYMMDDhhmmss for local time. A value of '0' will cause the
+ task to be scheduled for immediate execution. When this option is
+ specified the operation will be scheduled to start at the specified
+ time after which this utility will exit immediately.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example exports data to a file,
+ <filename>Example.ldif</filename>, with the server offline.</para>
+ <screen>$ export-ldif -b dc=example,dc=com -n userRoot -l ../ldif/Example.ldif
+[21/Jun/2011:13:40:49 +0200] category=BACKEND severity=INFORMATION ...
+...Exported 160 entries and skipped 0 in 0 seconds (average rate 1428.6/sec)</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-import-ldif.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-import-ldif.xml
new file mode 100644
index 0000000..c0c5fb2
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-import-ldif.xml
@@ -0,0 +1,419 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='import-ldif-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>import-ldif</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>import-ldif</refname>
+ <refpurpose>import OpenDJ directory data from LDIF</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>import-ldif</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to import LDIF data into a directory server
+ backend.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --append</option></term>
+ <listitem>
+ <para>Append to an existing database rather than overwriting it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --templateFile {templateFile}</option></term>
+ <listitem>
+ <para>Path to a MakeLDIF template to use to generate the import
+ data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --includeBranch {branchDN}</option></term>
+ <listitem>
+ <para>Base DN of a branch to include in the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-B, --excludeBranch {branchDN}</option></term>
+ <listitem>
+ <para>Base DN of a branch to exclude from the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --isCompressed</option></term>
+ <listitem>
+ <para>LDIF file is compressed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--countRejects</option></term>
+ <listitem>
+ <para>Count the number of entries rejected by the server and return that
+ value as the exit code (values > 255 will be reduced to 255 due to exit
+ code restrictions).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --excludeAttribute {attribute}</option></term>
+ <listitem>
+ <para>Attribute to exclude from the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --excludeFilter {filter}</option></term>
+ <listitem>
+ <para>Filter to identify entries to exclude from the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-F, --clearBackend</option></term>
+ <listitem>
+ <para>Remove all entries for all base DNs in the backend before
+ importing.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --includeAttribute {attribute}</option></term>
+ <listitem>
+ <para>Attribute to include in the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --includeFilter {filter}</option></term>
+ <listitem>
+ <para>Filter to identify entries to include in the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --ldifFile {ldifFile}</option></term>
+ <listitem>
+ <para>Path to the LDIF file to be imported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --backendID {backendName}</option></term>
+ <listitem>
+ <para>Backend ID for the backend to import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-O, --overwrite</option></term>
+ <listitem>
+ <para>Overwrite an existing rejects and/or skip file rather than appending
+ to it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --replaceExisting</option></term>
+ <listitem>
+ <para>Replace existing entries when appending to the database.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-R, --rejectFile {rejectFile}</option></term>
+ <listitem>
+ <para>Write rejected entries to the specified file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --randomSeed {seed}</option></term>
+ <listitem>
+ <para>Seed for the MakeLDIF random number generator.</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --skipSchemaValidation</option></term>
+ <listitem>
+ <para>Skip schema validation during the LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--skipDNValidation</option></term>
+ <listitem>
+ <para>Perform DN validation during later part of LDIF import.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--skipFile {skipFile}</option></term>
+ <listitem>
+ <para>Write skipped entries to the specified file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--threadCount {count}</option></term>
+ <listitem>
+ <para>Number of threads used to read LDIF file during import. Default
+ value (0) equals: 2 x (number of CPUs).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--tmpdirectory {directory}</option></term>
+ <listitem>
+ <para>Path to temporary directory for index scratch files during LDIF
+ import.</para>
+ <para>Default value: <filename>import-tmp</filename></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Task Backend Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Task Scheduling Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--completionNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified when the task
+ completes. This option may be specified more than once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--dependency {taskID}</option></term>
+ <listitem>
+ <para>ID of a task upon which this task depends. A task will not start
+ execution until all its dependencies have completed execution.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--errorNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified if an error occurs
+ when this task executes. This option may be specified more than
+ once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--failedDependencyAction {action}</option></term>
+ <listitem>
+ <para>Action this task will take should one if its dependent tasks fail.
+ The value must be one of PROCESS, CANCEL, DISABLE. If not specified
+ defaults to CANCEL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--recurringTask {schedulePattern}</option></term>
+ <listitem>
+ <para>Indicates the task is recurring and will be scheduled according
+ to the value argument expressed in crontab(5) compatible time/date
+ pattern.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --start {startTime}</option></term>
+ <listitem>
+ <para>Indicates the date/time at which this operation will start when
+ scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC
+ time or YYYYMMDDhhmmss for local time. A value of '0' will cause the
+ task to be scheduled for immediate execution. When this option is
+ specified the operation will be scheduled to start at the specified
+ time after which this utility will exit immediately.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example imports the content of the LDIF file,
+ <filename>Example.ldif</filename>, with the server offline.</para>
+ <screen>
+ $ import-ldif -b dc=example,dc=com -n userRoot -l /path/to/Example.ldif
+ [21/Jun/2011:13:38:03 +0200] category=RUNTIME_INFORMATION severity=NOTICE...
+ ... msg=Import LDIF environment close took 0 seconds</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapcompare.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapcompare.xml
new file mode 100644
index 0000000..c3680bc
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapcompare.xml
@@ -0,0 +1,327 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapcompare-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapcompare</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapcompare</refname>
+ <refpurpose>perform LDAP compare operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapcompare</command>
+ <arg choice="req">options</arg>
+ <group><arg>attribute</arg><arg>:</arg><arg>value</arg></group>
+ <arg choice="opt" rep="repeat">DN</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP compare operations in the
+ directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing one DN per line of entries to compare</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following examples demonstrate comparing Babs Jensen's UID.</para>
+ <para>The following example uses a matching UID value.</para>
+ <screen>$ ldapcompare -p 1389 uid:bjensen uid=bjensen,ou=people,dc=example,dc=com
+Comparing type uid with value bjensen in entry
+uid=bjensen,ou=people,dc=example,dc=com
+Compare operation returned true for entry
+uid=bjensen,ou=people,dc=example,dc=com</screen>
+ <para>The following example uses a UID value that does not match.</para>
+ <screen>$ ldapcompare -p 1389 uid:beavis uid=bjensen,ou=people,dc=example,dc=com
+Comparing type uid with value beavis in entry
+uid=bjensen,ou=people,dc=example,dc=com
+Compare operation returned false for entry
+uid=bjensen,ou=people,dc=example,dc=com</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapdelete.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapdelete.xml
new file mode 100644
index 0000000..7c2c527
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapdelete.xml
@@ -0,0 +1,330 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapdelete-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapdelete</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapdelete</refname>
+ <refpurpose>perform LDAP delete operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapdelete</command>
+ <arg choice="req">options</arg>
+ <arg><replaceable>DN</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP delete operations in the
+ directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing the changes to apply</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-x, --deleteSubtree</option></term>
+ <listitem>
+ <para>Delete the specified entry and all entries below it</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following command deletes a user entry from the directory.</para>
+ <screen>$ ldapdelete -p 1389 -D "cn=Directory Manager" -w password
+ uid=bjensen,ou=people,dc=example,dc=com
+Processing DELETE request for uid=bjensen,ou=people,dc=example,dc=com
+DELETE operation successful for DN uid=bjensen,ou=people,dc=example,dc=com</screen>
+ <para>The following command deletes the ou=Groups entry and all entries
+ underneath ou=Groups.</para>
+ <screen>$ ldapdelete -p 1389 -D "cn=Directory Manager" -w password -x
+ ou=groups,dc=example,dc=com
+Processing DELETE request for ou=groups,dc=example,dc=com
+DELETE operation successful for DN ou=groups,dc=example,dc=com</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapmodify.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapmodify.xml
new file mode 100644
index 0000000..47de6ff
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapmodify.xml
@@ -0,0 +1,397 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapmodify-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapmodify</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapmodify</refname>
+ <refpurpose>perform LDAP modify, add, delete, mod DN operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapmodify</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP modify, add, delete, and
+ modify DN operations in the directory.</para>
+ <para>When not using a file to specify modifications, end your input with
+ EOF (Ctrl+D on UNIX, Ctrl+Z on Windows).</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --defaultAdd</option></term>
+ <listitem>
+ <para>Treat records with no changetype as add operations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing the changes to apply</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--postReadAttributes {attrList}</option></term>
+ <listitem>
+ <para>Use the LDAP ReadEntry post-read control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--preReadAttributes {attrList}</option></term>
+ <listitem>
+ <para>Use the LDAP ReadEntry pre-read control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command to add an entry
+ to the directory.</para>
+ <screen>$ cat newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+facsimileTelephoneNumber: +1 408 555 1213
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+givenName: New
+cn: New User
+cn: Real Name
+telephoneNumber: +1 408 555 1212
+sn: Jensen
+roomNumber: 1234
+homeDirectory: /home/newuser
+uidNumber: 10389
+mail: newuser@example.com
+l: South Pole
+ou: Product Development
+ou: People
+gidNumber: 10636
+
+$ ldapmodify -p 1389 -a -f newuser.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing ADD request for uid=newuser,ou=People,dc=example,dc=com
+ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+
+ <para>The following example demonstrates adding a Description attribute
+ to the new user's entry.</para>
+ <screen>$ cat newdesc.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+add: description
+description: A new user's entry
+
+$ ldapmodify -p 1389 -f newdesc.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing MODIFY request for uid=newuser,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+
+ <para>The following example demonstrates changing the Description attribute
+ for the new user's entry.</para>
+ <screen>$ cat moddesc.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+replace: description
+description: Another description
+
+$ ldapmodify -p 1389 -f moddesc.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing MODIFY request for uid=newuser,ou=People,dc=example,dc=com
+MODIFY operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+
+ <para>The following example demonstrates deleting the new user's entry.</para>
+ <screen>$ cat deluser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: delete
+
+$ ldapmodify -p 1389 -f deluser.ldif
+ -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+Processing DELETE request for uid=newuser,ou=People,dc=example,dc=com
+DELETE operation successful for DN uid=newuser,ou=People,dc=example,dc=com</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldappasswordmodify.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldappasswordmodify.xml
new file mode 100644
index 0000000..3420fc4
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldappasswordmodify.xml
@@ -0,0 +1,335 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldappasswordmodify-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldappasswordmodify</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldappasswordmodify</refname>
+ <refpurpose>perform LDAP password modifications</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldappasswordmodify</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP password modify operations in
+ the directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --authzID {authzID}</option></term>
+ <listitem>
+ <para>Authorization ID for the user entry whose password should be changed</para>
+ <para>The authorization ID is a string having either the prefix
+ <literal>dn:</literal> followed by the user's distinguished name, or
+ the prefix <literal>u:</literal> followed by a user identifier that
+ depends on the identity mapping used to match the user identifier to
+ an entry in the directory. Examples include
+ <literal>dn:uid=bjensen,ou=People,dc=example,dc=com</literal>, and, if
+ we assume that <literal>bjensen</literal> is mapped to Barbara Jensen's
+ entry, <literal>u:bjensen</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --provideDNForAuthzID</option></term>
+ <listitem>
+ <para>Use the bind DN as the authorization ID for the password modify
+ operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --currentPassword {currentPassword}</option></term>
+ <listitem>
+ <para>Current password for the target user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-C, --currentPasswordFile {file}</option></term>
+ <listitem>
+ <para>Path to a file containing the current password for the target user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-F, --newPasswordFile {file}</option></term>
+ <listitem>
+ <para>Path to a file containing the new password to provide for the
+ target user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --newPassword {newPassword}</option></term>
+ <listitem>
+ <para>New password to provide for the target user</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates a user changing the password
+ for her entry.</para>
+ <screen>$ cat /tmp/currpwd.txt /tmp/newpwd.txt
+bribery
+secret12
+$ ldappasswordmodify -p 1389 -C /tmp/currpwd.txt -N /tmp/newpwd.txt
+-A -D uid=kvaughan,ou=people,dc=example,dc=com -w bribery
+The LDAP password modify operation was successful</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapsearch.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapsearch.xml
new file mode 100644
index 0000000..28616a0
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldapsearch.xml
@@ -0,0 +1,513 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldapsearch-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldapsearch</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldapsearch</refname>
+ <refpurpose>perform LDAP search operations</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldapsearch</command>
+ <arg choice="req">options</arg>
+ <arg choice="opt">filter</arg>
+ <arg choice="opt" rep="repeat">attributes</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform LDAP search operations in the
+ directory.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --dereferencePolicy {dereferencePolicy}</option></term>
+ <listitem>
+ <para>Alias dereference policy ('never', 'always', 'search', or 'find')</para>
+ <para>Default value: never</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --typesOnly</option></term>
+ <listitem>
+ <para>Only retrieve attribute names but not their values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--assertionFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP assertion control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN format string</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-C, --persistentSearch ps[:changetype[:changesonly[:entrychgcontrols]]]</option></term>
+ <listitem>
+ <para>Use the persistent search control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--countEntries</option></term>
+ <listitem>
+ <para>Count the number of entries returned by the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --getEffectiveRightsAttribute {attribute}</option></term>
+ <listitem>
+ <para>Specifies geteffectiverights control specific attribute list</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filename {file}</option></term>
+ <listitem>
+ <para>LDIF file containing the changes to apply</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-g, --getEffectiveRightsAuthzid {authzID}</option></term>
+ <listitem>
+ <para>Use geteffectiverights control with the provided authzid</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-G, --virtualListView {before:after:index:count | before:after:value}</option></term>
+ <listitem>
+ <para>Use the virtual list view control to retrieve the specified results page</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-J, --control {controloid[:criticality[:value|::b64value|:<filePath]]}</option></term>
+ <listitem>
+ <para>Use a request control with the provided information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --timeLimit {timeLimit}</option></term>
+ <listitem>
+ <para>Maximum length of time in seconds to allow for the search</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--matchedValuesFilter {filter}</option></term>
+ <listitem>
+ <para>Use the LDAP matched values control with the provided filter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Show what would be done but do not perform any operation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --searchScope {searchScope}</option></term>
+ <listitem>
+ <para>Search scope ('base', 'one', 'sub', or 'subordinate')</para>
+ <para>Default value: sub</para>
+ <para><literal>subordinate</literal> is an LDAP extension that might
+ not work with all LDAP servers.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --sortOrder {sortOrder}</option></term>
+ <listitem>
+ <para>Sort the results using the provided sort order</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--simplePageSize {numEntries}</option></term>
+ <listitem>
+ <para>Use the simple paged results control with the given page size</para>
+ <para>Default value: 1000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z, --sizeLimit {sizeLimit}</option></term>
+ <listitem>
+ <para>Maximum number of entries to return from the search</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --ldapVersion {version}</option></term>
+ <listitem>
+ <para>LDAP protocol version number</para>
+ <para>Default value: 3</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-i, --encoding {encoding}</option></term>
+ <listitem>
+ <para>Use the specified character set for command-line input</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --dontWrap</option></term>
+ <listitem><para>Do not wrap long lines</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Filter</title>
+ <para>The filter argument is a string representation of an LDAP search filter
+ as in <literal>(cn=Babs Jensen)</literal>, <literal
+ >(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))</literal>, or
+ <literal>(cn:caseExactMatch:=Fred Flintstone)</literal>.</para>
+ </refsect1>
+ <refsect1>
+ <title>Attribute</title>
+ <para>The optional attribute list specifies the attributes to return in the
+ entries found by the search. In addition to identifying attributes by name
+ such as <literal>cn sn mail</literal> and so forth, you can use the following
+ notations, too.</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>*</literal></term>
+ <listitem>
+ <para>Return all user attributes such as <literal>cn</literal>,
+ <literal>sn</literal>, and <literal>mail</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>+</literal></term>
+ <listitem>
+ <para>Return all operational attributes such as <literal>etag</literal>
+ and <literal>pwdPolicySubentry</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>@<replaceable>objectclass</replaceable></literal></term>
+ <listitem>
+ <para>Return all attributes of the specified object class, where
+ <replaceable>objectclass</replaceable> is one of the object classes
+ on the entries returned by the search.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><replaceable>ldap-error</replaceable></term>
+ <listitem>
+ <para>An LDAP error occurred while processing the operation.</para>
+ <para>LDAP result codes are described in <link
+ xlink:href="http://tools.ietf.org/html/rfc4511#appendix-A">RFC
+ 4511</link>. Also see the additional information for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Files</title>
+ <para>You can use <filename>~/.opendj/tools.properties</filename> to set
+ the defaults for bind DN, host name, and port number as in the following
+ example.</para>
+ <programlisting language="ini">hostname=directory.example.com
+port=1389
+bindDN=uid=kvaughan,ou=People,dc=example,dc=com
+
+ldapcompare.port=1389
+ldapdelete.port=1389
+ldapmodify.port=1389
+ldappasswordmodify.port=1389
+ldapsearch.port=1389</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example searches for entries with UID containing
+ <literal>jensen</literal>, returning only DNs and uid values.</para>
+ <screen>$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=*jensen*)" uid
+dn: uid=ajensen,ou=People,dc=example,dc=com
+uid: ajensen
+
+dn: uid=bjensen,ou=People,dc=example,dc=com
+uid: bjensen
+
+dn: uid=gjensen,ou=People,dc=example,dc=com
+uid: gjensen
+
+dn: uid=jjensen,ou=People,dc=example,dc=com
+uid: jjensen
+
+dn: uid=kjensen,ou=People,dc=example,dc=com
+uid: kjensen
+
+dn: uid=rjensen,ou=People,dc=example,dc=com
+uid: rjensen
+
+dn: uid=tjensen,ou=People,dc=example,dc=com
+uid: tjensen
+
+
+Result Code: 0 (Success)</screen>
+
+ <para>You can also use <literal>@<replaceable
+ >objectclass</replaceable></literal> notation in the attribute list to return
+ the attributes of a particular object class. The following example shows
+ how to return attributes of the <literal>inetOrgPerson</literal> object
+ class.</para>
+
+ <screen>$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" @inetorgperson
+dn: uid=bjensen,ou=People,dc=example,dc=com
+givenName: Barbara
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+uid: bjensen
+cn: Barbara Jensen
+cn: Babs Jensen
+telephoneNumber: +1 408 555 1862
+sn: Jensen
+roomNumber: 0209
+mail: bjensen@example.com
+l: Cupertino
+ou: Product Development
+ou: People
+facsimileTelephoneNumber: +1 408 555 1992</screen>
+
+ <para>You can use <literal>+</literal> in the attribute list to return
+ all operational attributes, as in the following example.</para>
+
+ <screen>$ ldapsearch -p 1389 -b dc=example,dc=com "(uid=bjensen)" +
+dn: uid=bjensen,ou=People,dc=example,dc=com
+numSubordinates: 0
+structuralObjectClass: inetOrgPerson
+etag: 0000000073c29972
+pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config
+subschemaSubentry: cn=schema
+hasSubordinates: false
+entryDN: uid=bjensen,ou=people,dc=example,dc=com
+entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldif-diff.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldif-diff.xml
new file mode 100644
index 0000000..618ccf0
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldif-diff.xml
@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldif-diff-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldif-diff</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldif-diff</refname>
+ <refpurpose>compare small LDIF files</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldif-diff</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to compare two LDIF files and report the
+ differences in LDIF format.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --ignoreAttrs {file}</option></term>
+ <listitem>
+ <para>File containing a list of attributes to ignore when computing the
+ difference.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--checkSchema</option></term>
+ <listitem>
+ <para>Takes into account the syntax of the attributes as defined in the
+ schema to make the value comparison. The provided LDIF files must conform
+ to the server schema.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --ignoreEntries {file}</option></term>
+ <listitem>
+ <para>File containing a list of entries (DN) to ignore when computing the
+ difference.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --outputLDIF {file}</option></term>
+ <listitem>
+ <para>File to which the output should be written.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-O, --overwriteExisting</option></term>
+ <listitem>
+ <para>Any existing output file should be overwritten rather than appending
+ to it.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --useCompareResultCode</option></term>
+ <listitem>
+ <para>Use the LDAP compare result as an exit code for reporting
+ differences between the two LDIF files.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --sourceLDIF {file}</option></term>
+ <listitem>
+ <para>LDIF file to use as the source data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --singleValueChanges</option></term>
+ <listitem>
+ <para>Each attribute-level change should be written as a separate
+ modification per attribute value rather than one modification per
+ entry.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --targetLDIF {file}</option></term>
+ <listitem>
+ <para>LDIF file to use as the target data.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>5</term>
+ <listitem>
+ <para>The -r option was used, and no differences are reported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>6</term>
+ <listitem>
+ <para>The-r option was used, and differences are reported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>other</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command with two
+ small LDIF files.</para>
+ <screen>$ cat /path/to/newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: changeme
+
+$ cat /path/to/neweruser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: secret12
+description: A new description.
+
+$ ldif-diff -s /path/to/newuser.ldif -t /path/to/neweruser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+add: userPassword
+userPassword: secret12
+-
+delete: userPassword
+userPassword: changeme
+-
+add: description
+description: A new description.
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifdiff.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifdiff.xml
new file mode 100644
index 0000000..473c445
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifdiff.xml
@@ -0,0 +1,165 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldifdiff-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldifdiff</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldifdiff</refname>
+ <refpurpose>compare small LDIF files</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldifdiff</command>
+ <arg choice="opt">options</arg>
+ <arg choice="plain"><replaceable>source</replaceable>.ldif</arg>
+ <arg choice="plain"><replaceable>target</replaceable>.ldif</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to compare two LDIF files and report the
+ differences in LDIF format.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --ignoreAttrs {file}</option></term>
+ <listitem>
+ <para>File containing a list of attributes to ignore when computing the
+ difference.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--checkSchema</option></term>
+ <listitem>
+ <para>Takes into account the syntax of the attributes as defined in the
+ schema to make the value comparison. The provided LDIF files must conform
+ to the server schema.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --ignoreEntries {file}</option></term>
+ <listitem>
+ <para>File containing a list of entries (DN) to ignore when computing the
+ difference.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --singleValueChanges</option></term>
+ <listitem>
+ <para>Each attribute-level change should be written as a separate
+ modification per attribute value rather than one modification per
+ entry.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command with two
+ small LDIF files.</para>
+ <screen>$ cat /path/to/newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: changeme
+
+$ cat /path/to/neweruser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: secret12
+description: A new description.
+
+$ ldifdiff /path/to/newuser.ldif /path/to/neweruser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+add: userPassword
+userPassword: secret12
+-
+delete: userPassword
+userPassword: changeme
+-
+add: description
+description: A new description.
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifmodify.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifmodify.xml
new file mode 100644
index 0000000..8c4ec2d
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifmodify.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldifmodify-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldifmodify</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldifmodify</refname>
+ <refpurpose>apply LDIF changes to LDIF</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldifmodify</command>
+ <arg choice="req">options</arg>
+ <arg choice="plain">source</arg>
+ <arg choice="opt">changes</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to apply a set of modify, add, and delete
+ operations against data in an LDIF file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-c, --continueOnError</option></term>
+ <listitem>
+ <para>Continue processing even if there are errors</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --outputLDIF {file}</option></term>
+ <listitem>
+ <para>Write updated entries to {file} instead of stdout</para>
+ <para>Default value: stdout</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command.</para>
+ <screen>$ cat /path/to/newuser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: changeme
+
+$ cat /path/to/newdiff.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+changetype: modify
+add: userPassword
+userPassword: secret12
+-
+delete: userPassword
+userPassword: changeme
+-
+add: description
+description: A new description.
+
+$ ldifmodify -o neweruser.ldif /path/to/newuser.ldif /path/to/newdiff.ldif
+$ cat neweruser.ldif
+dn: uid=newuser,ou=People,dc=example,dc=com
+uid: newuser
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: top
+cn: New User
+sn: User
+ou: People
+mail: newuser@example.com
+userPassword: secret12
+description: A new description.
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifsearch.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifsearch.xml
new file mode 100644
index 0000000..07c9218
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-ldifsearch.xml
@@ -0,0 +1,226 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='ldifsearch-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>ldifsearch</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>ldifsearch</refname>
+ <refpurpose>search LDIF with LDAP filters</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>ldifsearch</command>
+ <arg choice="req">options</arg>
+ <arg choice="plain">source</arg>
+ <arg choice="opt">filter</arg>
+ <arg choice="opt" rep="repeat">attribute</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to perform search operations against data in
+ an LDIF file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-A, --typesOnly</option></term>
+ <listitem>
+ <para>Only retrieve attribute names but not their values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Search base DN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --filterFile {filterFile}</option></term>
+ <listitem>
+ <para>File containing a list of search filter strings</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --timeLimit {timeLimit}</option></term>
+ <listitem>
+ <para>Maximum length of time in seconds to allow for the search</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --outputFile {File}</option></term>
+ <listitem>
+ <para>Write search results to {file} instead of stdout</para>
+ <para>Default: stdout</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --searchScope {scope}</option></term>
+ <listitem>
+ <para>Search scope ('base', 'one', 'sub', or 'subordinate')</para>
+ <para>Default value: sub</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-z, --sizeLimit {sizeLimit}</option></term>
+ <listitem>
+ <para>Maximum number of matching entries to return from the search</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Filter</title>
+ <para>The filter argument is a string representation of an LDAP search filter
+ as in <literal>(cn=Babs Jensen)</literal>, <literal
+ >(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))</literal>, or
+ <literal>(cn:caseExactMatch:=Fred Flintstone)</literal>.</para>
+ </refsect1>
+ <refsect1>
+ <title>Attribute</title>
+ <para>The optional attribute list specifies the attributes to return in the
+ entries found by the search. In addition to identifying attributes by name
+ such as <literal>cn sn mail</literal> and so forth, you can use the following
+ notations, too.</para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>*</literal></term>
+ <listitem>
+ <para>Return all user attributes such as <literal>cn</literal>,
+ <literal>sn</literal>, and <literal>mail</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>+</literal></term>
+ <listitem>
+ <para>Return all operational attributes such as <literal>etag</literal>
+ and <literal>pwdPolicySubentry</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>@<replaceable>objectclass</replaceable></literal></term>
+ <listitem>
+ <para>Return all attributes of the specified object class, where
+ <replaceable>objectclass</replaceable> is one of the object classes
+ on the entries returned by the search.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command.</para>
+ <screen>$ ldifsearch -b dc=example,dc=com /path/to/Example.ldif uid=bjensen
+dn: uid=bjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+uid: bjensen
+userpassword: hifalutin
+facsimiletelephonenumber: +1 408 555 1992
+givenname: Barbara
+cn: Barbara Jensen
+cn: Babs Jensen
+telephonenumber: +1 408 555 1862
+sn: Jensen
+roomnumber: 0209
+homeDirectory: /home/bjensen
+mail: bjensen@example.com
+l: Cupertino
+ou: Product Development
+ou: People
+uidNumber: 1076
+gidNumber: 1000
+</screen>
+
+ <para>You can also use <literal>@<replaceable
+ >objectclass</replaceable></literal> notation in the attribute list to return
+ the attributes of a particular object class. The following example shows
+ how to return attributes of the <literal>posixAccount</literal> object
+ class.</para>
+
+ <screen>$ ldifsearch --ldifFile /path/to/Example.ldif
+ --baseDN dc=example,dc=com "(uid=bjensen)" @posixaccount
+dn: uid=bjensen,ou=People,dc=example,dc=com
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+objectClass: posixAccount
+objectClass: top
+uid: bjensen
+userpassword: hifalutin
+cn: Barbara Jensen
+cn: Babs Jensen
+homeDirectory: /home/bjensen
+uidNumber: 1076
+gidNumber: 1000</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-list-backends.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-list-backends.xml
new file mode 100644
index 0000000..cee865f
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-list-backends.xml
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='list-backends-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>list-backends</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>list-backends</refname>
+ <refpurpose>list OpenDJ backends and base DNs</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>list-backends</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to list the backends and base DNs configured
+ in the Directory Server.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN for which to list the backend ID.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --backendID {backendName}</option></term>
+ <listitem>
+ <para>Backend ID of the backend for which to list the base DNs.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>$ list-backends
+Backend ID : Base DN
+-------------------:----------------------
+adminRoot : cn=admin data
+ads-truststore : cn=ads-truststore
+backup : cn=backups
+config : cn=config
+monitor : cn=monitor
+myCompanyRoot : "dc=myCompany,dc=com"
+myOrgRoot : o=myOrg
+replicationChanges : dc=replicationChanges
+schema : cn=schema
+tasks : cn=tasks
+userRoot : "dc=example,dc=com"</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif-template.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif-template.xml
new file mode 100644
index 0000000..d4285e5
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif-template.xml
@@ -0,0 +1,452 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2012-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='make-ldif-template-5'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2012-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>make-ldif.template</refentrytitle><manvolnum>5</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>make-ldif.template</refname>
+ <refpurpose>template file for the make-ldif command</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis># Comment lines start with #.
+
+# Optionally include classes that define custom tags.
+# Custom tag classes extend org.opends.server.tools.makeldif.Tag and
+# must be on the class path when you run make-ldif.
+#
+include <replaceable>custom.makeldif.tag.ClassName</replaceable>
+...
+
+# Optionally define constants used in the template.
+# To reference constants later, put brackets around the name: [constant-name]
+#
+define <replaceable>constant-name</replaceable>=<replaceable>value</replaceable>
+...
+
+# Define branches by suffix DN, such as the following:
+#
+# dc=example,dc=com
+# ou=People,dc=example,dc=com
+# ou=Groups,dc=example,dc=com
+#
+# make-ldif generates the necessary object class definitions and RDNs.
+#
+# A branch can have subordinateTemplates that define templates to use for
+# the branch entry.
+#
+# A branch can have additional attributes generated on the branch entry. See
+# the Description below for more information on specifying attribute values.
+#
+branch: <replaceable>suffix-dn</replaceable>
+[subordinateTemplate: <replaceable>template-name</replaceable>:<replaceable>number</replaceable>
+...]
+[<replaceable>attribute</replaceable>: <replaceable>attr-value</replaceable>
+...]
+
+...
+
+# Define entries using templates.
+#
+# A template can extend another template.
+# A template defines the RDN attribute(s) used for generated entries.
+# A template can have a subordinateTemplate that defines a template to use for
+# the generated entries.
+#
+# A template then defines attributes. See the Description below for more
+# information on specifying attribute values.
+#
+template: <replaceable>template-name</replaceable>
+[extends: <replaceable>template-name</replaceable>]
+rdnAttr: <replaceable>attribute</replaceable>[+<replaceable>attribute</replaceable> ...]
+[subordinateTemplate: <replaceable>template-name</replaceable>:<replaceable>number</replaceable>]
+[<replaceable>attribute</replaceable>: <replaceable>attr-value</replaceable>
+...]
+
+...
+</synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+
+ <para>Template files specify how to build LDIF. They allow you to define
+ variables, insert random values from other files, and generally build
+ arbitrarily large LDIF files for testing purposes. You pass template files
+ to the <command>make-ldif</command> command when generating LDIF.</para>
+
+ <para>The Synopsis above shows the layout for a <command>make-ldif</command>
+ template file. This section focuses on what you can do to specify entry
+ attribute values, called <replaceable>attr-value</replaceable> in the Synopsis
+ section.</para>
+
+ <variablelist>
+ <title>Specifying Attribute Values</title>
+
+ <para>When specifying attribute values in <command>make-ldif</command>
+ templates, you can use static text and constants that you have defined,
+ enclosing names for constants in brackets, <literal>[myConstant]</literal>.
+ You can use more than one constant per line, as in the following
+ example.</para>
+
+ <programlisting language="ldif"
+ >description: Description for [org] under [suffix]</programlisting>
+
+ <para>You can also use two kinds of tags when specifying attribute values.
+ One kind of tag gets replaced with the value of another attribute in the
+ generated entry. Such tags are delimited with braces, <literal>{ }</literal>.
+ For example, if your template includes definitions for first name and last
+ name attributes:</para>
+
+ <programlisting language="ldif">givenName: <first>
+sn: <last></programlisting>
+
+ <para>Then you can define a mail attribute that uses the values of both
+ attributes, and an initials attribute that takes the first character
+ of each.</para>
+
+ <programlisting language="ldif">mail: {givenName}.{sn}@[myDomain]
+initials: {givenName:1}{sn:1}</programlisting>
+
+ <para>The other kind of tag is delimited with <literal><</literal>
+ and <literal>></literal>, as shown above in the example with
+ <literal><first></literal> and <literal><last></literal>.
+ Tag names are not case sensitive. Many tags can take arguments separated
+ by colons, <literal>:</literal>, from the tag names within the tag.</para>
+
+ <para>Use backslashes to escape literal start tag characters (<literal
+ >< [ {</literal>) as shown in the following example, and to escape literal
+ end tag characters within tags (<literal>> ] }</literal>).</para>
+
+ <programlisting language="ldif"
+ >scimMail: \{"emails": \[\{"value": "{mail}", "type": "work", "primary": true}]}
+xml: \<id>{uid}\</id></programlisting>
+
+ <para>OpenDJ supports the following tags.</para>
+
+ <varlistentry>
+ <term><DN></term>
+ <listitem>
+ <para>The DN tag gets replaced by the distinguished name of the current
+ entry. An optional integer argument specifies the subcomponents of the DN
+ to generate. For example, if the DN of the entry is
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>
+ <literal><DN:1></literal> gets replaced by
+ <literal>uid=bjensen</literal>, and <literal><DN:-2></literal> gets
+ replaced by <literal>dc=example,dc=com</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><File></term>
+ <listitem>
+ <para>The File tag gets replaced by a line from a text file you specify.
+ The File tag takes a required argument, the path to the text file, and an
+ optional second argument, either <literal>random</literal> or
+ <literal>sequential</literal>. For the file argument, either you specify
+ an absolute path to the file such as
+ <literal><file:/path/to/myDescriptions></literal>, or you specify
+ a path relative to the
+ <filename>/path/to/opendj/config/MakeLDIF/</filename> directory such as
+ <literal><file:streets></literal>. For the second argument,
+ if you specify <literal>sequential</literal> then lines from the file are
+ read in sequential order. Otherwise, lines from the file are read in
+ random order.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><First></term>
+ <listitem>
+ <para>The first name tag gets replaced by a random line from
+ <filename>/path/to/opendj/config/MakeLDIF/first.names</filename>.
+ Combinations of generated first and last names are unique, with integers
+ appended to the name strings if not enough combinations are
+ available.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><GUID></term>
+ <listitem>
+ <para>The GUID tag gets replaced by a 128-bit, type 4 (random) universally
+ unique identifier, such as
+ <literal>f47ac10b-58cc-4372-a567-0e02b2c3d479</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><IfAbsent></term>
+ <listitem>
+ <para>The IfAbsent tag takes as its first argument the name of another
+ attribute, and optionally as its second argument a value to use. This tag
+ causes the attribute to be generated only if the named attribute is not
+ present on the generated entry. Use this tag when you have used
+ <literal><Presence></literal> to define another attribute that is
+ not always present on generated entries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><IfPresent></term>
+ <listitem>
+ <para>The IfPresent takes as its first argument the name of another
+ attribute, and optionally as its second argument a value to use. This tag
+ causes the attribute to be generated only if the named attribute is also
+ present on the generated entry. Use this tag when you have used
+ <literal><Presence></literal> to define another attribute that is
+ sometimes present on generated entries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><Last></term>
+ <listitem>
+ <para>The last name tag gets replaced by a random line from
+ <filename>/path/to/opendj/config/MakeLDIF/last.names</filename>.
+ Combinations of generated first and last names are unique, with integers
+ appended to the name strings if not enough combinations are
+ available.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><List></term>
+ <listitem>
+ <para>The List tag gets replaced by one of the values from the list of
+ arguments you provide. For example,
+ <literal><List:bronze:silver:gold></literal> gets replaced with
+ <literal>bronze</literal>, <literal>silver</literal>, or
+ <literal>gold</literal>.</para>
+ <para>You can weight arguments to ensure some arguments are selected more
+ often than others. For example, if you want two bronze for one silver
+ and one gold, use
+ <literal><List:bronze;2:silver;1:gold;1></literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><ParentDN></term>
+ <listitem>
+ <para>The ParentDN tag gets replaced by the distinguished name of the
+ parent entry. For example, if the DN of the entry is
+ <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>,
+ <literal><ParentDN></literal> gets replaced by
+ <literal>ou=People,dc=example,dc=com</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><Presence></term>
+ <listitem>
+ <para>The Presence tag takes a percent argument. It does not get replaced
+ by a value itself, but instead results in the attribute being generated
+ on the percentage of entries you specify in the argument. For example,
+ <literal>description: <Presence:50>A description</literal> generates
+ <literal>description: A description</literal> on half the entries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><Random></term>
+ <listitem>
+ <para>The Random tag lets you generate a variety of random numbers and
+ strings. The Random tag has the following subtypes, which you include
+ as arguments, that is <literal><Random:<replaceable
+ >subtype</replaceable>></literal>.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>alpha:<replaceable>length</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>alpha:<replaceable>minlength</replaceable>:<replaceable
+ >maxlength</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>numeric:<replaceable>length</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>numeric:<replaceable>minvalue</replaceable>:<replaceable
+ >maxvalue</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>numeric:<replaceable>minvalue</replaceable>:<replaceable
+ >maxvalue</replaceable>:<replaceable>format</replaceable></literal>,
+ where <replaceable>format</replaceable> is a
+ <literal>java.text.DecimalFormat</literal> pattern</para>
+ </listitem>
+ <listitem>
+ <para><literal>alphanumeric:<replaceable>length</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>alphanumeric:<replaceable>minlength</replaceable>:<replaceable
+ >maxlength</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>chars:<replaceable>characters</replaceable>:<replaceable
+ >length</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>chars:<replaceable>characters</replaceable>:<replaceable
+ >minlength</replaceable>:<replaceable>maxlength</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>hex:<replaceable>length</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>hex:<replaceable>minlength</replaceable>:<replaceable
+ >maxlength</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>base64:<replaceable>length</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>base64:<replaceable>minlength</replaceable>:<replaceable
+ >maxlength</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>month</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>month:<replaceable>maxlength</replaceable></literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>telephone</literal>, a telephone number starting with
+ the country code <literal>+1</literal></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><RDN></term>
+ <listitem>
+ <para>The RDN tag gets replaced with the RDN of the entry. Use this
+ in the template after you have specified <literal>rdnAttr</literal> so
+ that the RDN has already been generated when this tag is replaced.</para>
+
+ <para>An optional integer argument specifies the subcomponents of the RDN
+ to generate.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><Sequential></term>
+ <listitem>
+ <para>The Sequential tag gets replaced by a sequentially increasing
+ generated integer. The first optional integer argument specifies the
+ starting number. The second optional boolean argument specifies whether
+ to start over when generating entries for a new parent entry. For example,
+ <literal><Sequential>:42:true</literal> starts counting from 42,
+ and starts over when the parent entry changes from
+ <literal>o=Engineering</literal> to <literal>o=Marketing</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><_DN></term>
+ <listitem>
+ <para>The _DN tag gets replaced by the DN of the current entry with
+ underscores in the place of commas.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><_ParentDN></term>
+ <listitem>
+ <para>The _ParentDN tag gets replaced by the DN the parent entry with
+ underscores in the place of commas.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example generates 10 organization units, each containing
+ 50 entries.</para>
+
+ <programlisting language="ldif">define suffix=dc=example,dc=com
+define maildomain=example.com
+define numusers=50
+define numorgs=10
+
+branch: [suffix]
+
+branch: ou=People,[suffix]
+subordinateTemplate: orgunit:[numorgs]
+description: This is the People container
+telephoneNumber: +33 00010002
+
+template: orgunit
+subordinateTemplate: person:[numusers]
+rdnAttr: ou
+ou: Org-<sequential:0>
+objectClass: top
+objectClass: organizationalUnit
+description: This is the {ou} organizational unit
+
+template: person
+rdnAttr: uid
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+givenName: <first>
+sn: <last>
+cn: {givenName} {sn}
+initials: {givenName:1}<random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1>{sn:1}
+employeeNumber: <sequential:0>
+uid: user.{employeeNumber}
+mail: {uid}@[maildomain]
+userPassword: password
+telephoneNumber: <random:telephone>
+homePhone: <random:telephone>
+pager: <random:telephone>
+mobile: <random:telephone>
+street: <random:numeric:5> <file:streets> Street
+l: <file:cities>
+st: <file:states>
+postalCode: <random:numeric:5>
+postalAddress: {cn}${street}${l}, {st} {postalCode}
+description: This is the description for {cn}.</programlisting>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para><link xlink:href="admin-guide#make-ldif-1"
+ xlink:role="http://docbook.org/xlink/role/olink"><citerefentry><refentrytitle
+ >make-ldif</refentrytitle><manvolnum>1</manvolnum></citerefentry></link
+ >, <filename>/path/to/opendj/config/MakeLDIF/example.template</filename></para>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif.xml
new file mode 100644
index 0000000..d9f94f7
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-make-ldif.xml
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='make-ldif-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>make-ldif</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>make-ldif</refname>
+ <refpurpose>generate test LDIF</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>make-ldif</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to generate LDIF data based on a definition
+ in a template file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-o, --ldifFile {file}</option></term>
+ <listitem>
+ <para>The path to the LDIF file to be written.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --randomSeed {seed}</option></term>
+ <listitem>
+ <para>The seed to use to initialize the random number generator.</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --templateFile {file}</option></term>
+ <listitem>
+ <para>The path to the template file with information about the LDIF data
+ to generate.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example uses the default template to generate LDIF.</para>
+ <screen>$ make-ldif -t ../config/MakeLDIF/example.template -o ../ldif/generated.ldif
+Processed 1000 entries
+Processed 2000 entries
+...
+Processed 10000 entries
+LDIF processing complete. 10003 entries written</screen>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para><link xlink:href="admin-guide#make-ldif-template-5"
+ xlink:role="http://docbook.org/xlink/role/olink"><citerefentry><refentrytitle
+ >make-ldif.template</refentrytitle><manvolnum>5</manvolnum
+ ></citerefentry></link></para>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-account.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-account.xml
new file mode 100644
index 0000000..6f6fcbf
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-account.xml
@@ -0,0 +1,372 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='manage-account-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>manage-account</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>manage-account</refname>
+ <refpurpose>manage state of directory server accounts</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>manage-account</command>
+ <command><replaceable>subcommand</replaceable></command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to retrieve and manipulate the values of
+ password policy state variables.</para>
+ </refsect1>
+ <refsect1>
+ <title>Subcommands</title>
+ <para>The following subcommands are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><command>manage-account clear-account-is-disabled</command></term>
+ <listitem>
+ <para>Clear account disabled state information from the user account</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-account-expiration-time</command></term>
+ <listitem>
+ <para>Display when the user account will expire</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-account-is-disabled</command></term>
+ <listitem>
+ <para>Display information about whether the user account has been
+ administratively disabled</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-all</command></term>
+ <listitem>
+ <para>Display all password policy state information for the user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-authentication-failure-times</command></term>
+ <listitem>
+ <para>Display the authentication failure times for the user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-grace-login-use-times</command></term>
+ <listitem>
+ <para>Display the grace login use times for the user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-last-login-time</command></term>
+ <listitem>
+ <para>Display the time that the user last authenticated to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-password-changed-by-required-time</command></term>
+ <listitem>
+ <para>Display the required password change time with which the user last
+ complied</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-password-changed-time</command></term>
+ <listitem>
+ <para>Display the time that the user's password was last changed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-password-expiration-warned-time</command></term>
+ <listitem>
+ <para>Display the time that the user first received an expiration warning
+ notice</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-password-history</command></term>
+ <listitem>
+ <para>Display password history state values for the user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-password-is-reset</command></term>
+ <listitem>
+ <para>Display information about whether the user will be required to
+ change his or her password on the next successful authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-password-policy-dn</command></term>
+ <listitem>
+ <para>Display the DN of the password policy for the user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-remaining-authentication-failure-count</command></term>
+ <listitem>
+ <para>Display the number of remaining authentication failures until the
+ user's account is locked</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-remaining-grace-login-count</command></term>
+ <listitem>
+ <para>Display the number of grace logins remaining for the user</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-account-expiration</command></term>
+ <listitem>
+ <para>Display the length of time in seconds until the user account
+ expires</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-authentication-failure-unlock</command></term>
+ <listitem>
+ <para>Display the length of time in seconds until the authentication
+ failure lockout expires</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-idle-lockout</command></term>
+ <listitem>
+ <para>Display the length of time in seconds until user's account is locked
+ because it has remained idle for too long</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-password-expiration</command></term>
+ <listitem>
+ <para>Display length of time in seconds until the user's password expires</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-password-expiration-warning</command></term>
+ <listitem>
+ <para>Display the length of time in seconds until the user should start
+ receiving password expiration warning notices</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-password-reset-lockout</command></term>
+ <listitem>
+ <para>Display the length of time in seconds until user's account is locked
+ because the user failed to change the password in a timely manner after an
+ administrative reset</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account get-seconds-until-required-change-time</command></term>
+ <listitem>
+ <para>Display the length of time in seconds that the user has remaining to
+ change his or her password before the account becomes locked due to the
+ required change time</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>manage-account set-account-is-disabled</command></term>
+ <listitem>
+ <para>Specify whether the user account has been administratively disabled</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Global Options</title>
+ <para>The following global options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-b, --targetDN {targetDN}</option></term>
+ <listitem>
+ <para>The DN of the user entry for which to get and set password policy
+ state information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>For the following examples, the directory admin user, Kirsten Vaughan,
+ has <literal>ds-privilege-name: password-reset</literal>, and the following
+ ACI on <literal>ou=People,dc=example,dc=com</literal>.</para>
+ <literallayout class="monospaced">(target="ldap:///ou=People,dc=example,dc=com") (targetattr ="*||+")(
+ version 3.0;acl "Admins can run amok"; allow(all) groupdn =
+ "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)</literallayout>
+ <para>The following command locks a user account.</para>
+ <screen>$ manage-account -p 4444 -D "uid=kvaughan,ou=people,dc=example,dc=com"
+ -w bribery set-account-is-disabled -O true
+ -b uid=bjensen,ou=people,dc=example,dc=com -X
+Account Is Disabled: true</screen>
+ <para>The following command unlocks a user account.</para>
+ <screen>$ manage-account -p 4444 -D "uid=kvaughan,ou=people,dc=example,dc=com"
+ -w bribery clear-account-is-disabled
+ -b uid=bjensen,ou=people,dc=example,dc=com -X
+Account Is Disabled: false</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-tasks.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-tasks.xml
new file mode 100644
index 0000000..474395b
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-manage-tasks.xml
@@ -0,0 +1,253 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='manage-tasks-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>manage-tasks</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>manage-tasks</refname>
+ <refpurpose>manage OpenDJ server administration tasks</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>manage-tasks</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to obtain a list of tasks scheduled to run
+ within the directory server as well as information about individual
+ tasks.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-c, --cancel {taskID}</option></term>
+ <listitem>
+ <para>ID of a particular task to cancel</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --info {taskID}</option></term>
+ <listitem>
+ <para>ID of a particular task about which this tool will display
+ information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --summary</option></term>
+ <listitem>
+ <para>Print a summary of tasks</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the tool will fail</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates use of the command with a server
+ that does daily backups at 2:00 AM.</para>
+ <screen>$ manage-tasks -p 4444 -h opendj.example.com -D "cn=Directory Manager"
+ -w password -s
+
+ ID Type Status
+ ---------------------------------------------------------------
+ example-backup Backup Recurring
+ example-backup-20110622020000000 Backup Waiting on start time
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-modrate.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-modrate.xml
new file mode 100644
index 0000000..2b2f251
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-modrate.xml
@@ -0,0 +1,368 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='modrate-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>modrate</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>modrate</refname>
+ <refpurpose>measure modification throughput and response time</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>modrate</command>
+ <arg choice="req">options</arg>
+ <group choice="opt" rep="repeat">
+ <arg>attribute</arg>
+ <arg>:</arg>
+ <arg>value format string</arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to measure modify throughput and response time
+ of a directory service using user-defined modifications.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-A, --asynchronous</option></term>
+ <listitem>
+ <para>Use asynchronous mode and don't wait for results before sending the
+ next request</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN format string</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --numConnections {numConnections}</option></term>
+ <listitem>
+ <para>Number of connections</para>
+ <para>Default value: 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --percentile {percentile}</option></term>
+ <listitem>
+ <para>Calculate max response time for a percentile of operations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --keepConnectionsOpen</option></term>
+ <listitem>
+ <para>Keep connections open</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-F, --noRebind</option></term>
+ <listitem>
+ <para>Keep connections open and don't rebind</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-g, --argument {generator function or static string}</option></term>
+ <listitem>
+ <para>Argument used to evaluate the Java style format strings in program
+ parameters (Base DN, Search Filter). The set of all arguments provided
+ form the the argument list in order. Besides static string arguments, they
+ can be generated per iteration with the following functions:</para>
+ <variablelist>
+ <varlistentry>
+ <term>"inc({filename})"</term>
+ <listitem><para>Consecutive, incremental line from file</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"inc({min},{max})"</term>
+ <listitem><para>Consecutive, incremental number</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"rand({filename})"</term>
+ <listitem><para>Random line from file</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"rand({min},{max})"</term>
+ <listitem><para>Random number</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"randstr({length},<replaceable>charSet</replaceable>)"</term>
+ <listitem><para>Random string of specified length and optionally from
+ characters in the charSet string. A range of character can be specified
+ with [start-end] charSet notation. If no charSet is specified,
+ the default charSet of [A-Z][a-z][0-9] will be used.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --statInterval {statInterval}</option></term>
+ <listitem>
+ <para>Display results each specified number of seconds</para>
+ <para>Default value: 5</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m, --maxIterations {maxIterations}</option></term>
+ <listitem>
+ <para>Max iterations, 0 for unlimited</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-M, --targetThroughput {targetThroughput}</option></term>
+ <listitem>
+ <para>Target average throughput to achieve</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --scriptFriendly</option></term>
+ <listitem>
+ <para>Use script-friendly mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --numConcurrentTasks {numConcurrentTasks}</option></term>
+ <listitem>
+ <para>Number of concurrent tasks per connection</para>
+ <para>Default value: 1</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates testing directory performance by
+ using the modrate command to write random 16-character description values
+ to all entries in a sample file.</para>
+ <screen>$ grep ^uid: /path/to/Example.ldif | sed -e "s/uid: //" > names.txt
+$ modrate -p 1389 -D "cn=Directory Manager" -w password -A -F -c 4 -t 4
+ -b "uid=%s,ou=people,dc=example,dc=com" -g "rand(names.txt)"
+ -g "randstr(16)" 'description:%2$s'
+--------------------------------------------------------------------------
+ Throughput Response Time
+ (ops/second) (milliseconds)
+recent average recent average 99.9% 99.99% 99.999% err/sec req/res
+--------------------------------------------------------------------------
+1085.9 1088.5 993.849 993.849 2135.220 2510.361 2510.361 0.0 2.3
+2086.7 1648.8 1963.980 1683.038 3015.025 3078.628 3215.050 0.0 1.0
+3097.3 2092.6 1332.930 1524.278 2940.131 3024.811 3215.050 0.0 1.0
+3848.3 2501.4 1045.000 1352.583 2902.235 3015.863 3215.050 0.0 1.0
+3641.2 2717.4 1106.157 1290.003 2901.379 3015.597 3215.050 0.0 1.0
+3759.4 2883.0 1065.732 1243.534 2900.400 3015.501 3215.050 0.0 1.0
+^C</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-rebuild-index.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-rebuild-index.xml
new file mode 100644
index 0000000..b5166df
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-rebuild-index.xml
@@ -0,0 +1,329 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='rebuild-index-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>rebuild-index</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>rebuild-index</refname>
+ <refpurpose>rebuild index after configuration change</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>rebuild-index</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to rebuild index data within a backend based
+ on the Berkeley DB Java Edition.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN of a backend supporting indexing. Rebuild is performed on
+ indexes within the scope of the given base DN.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--clearDegradedState</option></term>
+ <listitem>
+ <para>Indicates that indexes do not need rebuilding because they are known
+ to be empty and forcefully marks them as valid. <emphasis>This is an
+ advanced option which must only be used in cases where a degraded index is
+ known to be empty and does not therefore need rebuilding.</emphasis> This
+ situation typically arises when an index is created for an attribute which
+ has just been added to the schema.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --index {index}</option></term>
+ <listitem>
+ <para>Names of index(es) to rebuild. For an attribute index this is
+ simply an attribute name. At least one index must be specified for
+ rebuild. Cannot be used with the <option>--rebuildAll</option>
+ or <option>--rebuildDegraded</option> options.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--rebuildAll</option></term>
+ <listitem>
+ <para>Rebuild all indexes, including any DN2ID, DN2URI, VLV and
+ extensible indexes. Cannot be used with the <option>--index</option>
+ or <option>--rebuildDegraded</option> options.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--rebuildDegraded</option></term>
+ <listitem>
+ <para>Rebuild all degraded indexes, including any DN2ID, DN2URI, VLV and
+ extensible indexes. Cannot be used with the <option>--index</option>
+ or <option>--rebuildAll</option> options.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--tmpdirectory {directory}</option></term>
+ <listitem>
+ <para>Path to temporary directory for index scratch files during index
+ rebuilding.</para>
+ <para>Default value: import-tmp</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Task Backend Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Task Scheduling Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--completionNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified when the task
+ completes. This option may be specified more than once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--dependency {taskID}</option></term>
+ <listitem>
+ <para>ID of a task upon which this task depends. A task will not start
+ execution until all its dependencies have completed execution.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--errorNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified if an error occurs
+ when this task executes. This option may be specified more than
+ once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--failedDependencyAction {action}</option></term>
+ <listitem>
+ <para>Action this task will take should one if its dependent tasks fail.
+ The value must be one of PROCESS, CANCEL, DISABLE. If not specified
+ defaults to CANCEL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--recurringTask {schedulePattern}</option></term>
+ <listitem>
+ <para>Indicates the task is recurring and will be scheduled according
+ to the value argument expressed in crontab(5) compatible time/date
+ pattern.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --start {startTime}</option></term>
+ <listitem>
+ <para>Indicates the date/time at which this operation will start when
+ scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC
+ time or YYYYMMDDhhmmss for local time. A value of '0' will cause the
+ task to be scheduled for immediate execution. When this option is
+ specified the operation will be scheduled to start at the specified
+ time after which this utility will exit immediately.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>1</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example schedules a task to start immediately that
+ rebuilds the <literal>cn</literal> (common name) index.</para>
+
+ <screen>$ rebuild-index -p 4444 -h opendj.example.com -D "cn=Directory Manager"
+ -w password -b dc=example,dc=com -i cn -t 0
+Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-restore.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-restore.xml
new file mode 100644
index 0000000..fc45468
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-restore.xml
@@ -0,0 +1,322 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='restore-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>restore</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>restore</refname>
+ <refpurpose>restore OpenDJ directory data backups</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>restore</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to restore a backup of a directory server
+ backend.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-d, --backupDirectory {backupDir}</option></term>
+ <listitem>
+ <para>Path to the target directory for the backup file(s)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --backupID {backupID}</option></term>
+ <listitem>
+ <para>Use the provided identifier for the backup</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --listBackups</option></term>
+ <listitem>
+ <para>List available backups in the backup directory</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dry-run</option></term>
+ <listitem>
+ <para>Verify the contents of the backup but do not restore it</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Task Backend Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Task Scheduling Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--completionNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified when the task
+ completes. This option may be specified more than once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--dependency {taskID}</option></term>
+ <listitem>
+ <para>ID of a task upon which this task depends. A task will not start
+ execution until all its dependencies have completed execution.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--errorNotify {emailAddress}</option></term>
+ <listitem>
+ <para>Email address of a recipient to be notified if an error occurs
+ when this task executes. This option may be specified more than
+ once.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--failedDependencyAction {action}</option></term>
+ <listitem>
+ <para>Action this task will take should one if its dependent tasks fail.
+ The value must be one of PROCESS, CANCEL, DISABLE. If not specified
+ defaults to CANCEL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--recurringTask {schedulePattern}</option></term>
+ <listitem>
+ <para>Indicates the task is recurring and will be scheduled according
+ to the value argument expressed in crontab(5) compatible time/date
+ pattern.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --start {startTime}</option></term>
+ <listitem>
+ <para>Indicates the date/time at which this operation will start when
+ scheduled as a server task expressed in YYYYMMDDhhmmssZ format for UTC
+ time or YYYYMMDDhhmmss for local time. A value of '0' will cause the
+ task to be scheduled for immediate execution. When this option is
+ specified the operation will be scheduled to start at the specified
+ time after which this utility will exit immediately.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>1</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example schedules a restore as a task to begin
+ immediately while OpenDJ directory server is online.</para>
+ <screen>$ restore -p 4444 -D "cn=Directory Manager" -w password
+ -d /path/to/opendj/bak -I 20110613080032 -t 0
+Restore task 20110613155052932 scheduled to start Jun 13, 2011 3:50:52 PM CEST</screen>
+
+ <para>The following example restores data while OpenDJ is offline.</para>
+ <screen>$ /path/to/opendj/bin/stop-ds
+Stopping Server...
+...
+$ /path/to/opendj/bin/restore --backupDirectory /path/to/opendj/bak/userRoot
+ --listBackups
+Backup ID: 20120928102414Z
+Backup Date: 28/Sep/2012:12:24:17 +0200
+Is Incremental: false
+Is Compressed: false
+Is Encrypted: false
+Has Unsigned Hash: false
+Has Signed Hash: false
+Dependent Upon: none
+
+$ /path/to/opendj/bin/restore --backupDirectory /path/to/opendj/bak/userRoot
+ --backupID 20120928102414Z
+[28/Sep/2012:12:26:20 +0200] ... msg=Restored: 00000000.jdb (size 355179)
+$ /path/to/opendj/bin/start-ds
+[28/Sep/2012:12:27:29 +0200] ... The Directory Server has started successfully</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-searchrate.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-searchrate.xml
new file mode 100644
index 0000000..69fbcdd
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-searchrate.xml
@@ -0,0 +1,377 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='searchrate-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>searchrate</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${currentSDKversion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>searchrate</refname>
+ <refpurpose>measure search throughput and response time</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>searchrate</command>
+ <arg choice="req">options</arg>
+ <arg choice="opt">filter format string</arg>
+ <arg choice="opt" rep="repeat">attributes</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to measure search throughput and response time
+ of a directory service using user-defined searches.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --dereferencePolicy {dereferencePolicy}</option></term>
+ <listitem>
+ <para>Alias dereference policy ('never', 'always', 'search', or 'find')</para>
+ <para>Default value: never</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-A, --asynchronous</option></term>
+ <listitem>
+ <para>Use asynchronous mode and don't wait for results before sending the
+ next request</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN format string</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --numConnections {numConnections}</option></term>
+ <listitem>
+ <para>Number of connections</para>
+ <para>Default value: 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --percentile {percentile}</option></term>
+ <listitem>
+ <para>Calculate max response time for a percentile of operations</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --keepConnectionsOpen</option></term>
+ <listitem>
+ <para>Keep connections open</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-F, --noRebind</option></term>
+ <listitem>
+ <para>Keep connections open and don't rebind</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-g, --argument {generator function or static string}</option></term>
+ <listitem>
+ <para>Argument used to evaluate the Java style format strings in program
+ parameters (Base DN, Search Filter). The set of all arguments provided
+ form the the argument list in order. Besides static string arguments, they
+ can be generated per iteration with the following functions:</para>
+ <variablelist>
+ <varlistentry>
+ <term>"inc({filename})"</term>
+ <listitem><para>Consecutive, incremental line from file</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"inc({min},{max})"</term>
+ <listitem><para>Consecutive, incremental number</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"rand({filename})"</term>
+ <listitem><para>Random line from file</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"rand({min},{max})"</term>
+ <listitem><para>Random number</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"randstr({length},<replaceable>charSet</replaceable>)"</term>
+ <listitem><para>Random string of specified length and optionally from
+ characters in the charSet string. A range of character can be specified
+ with [start-end] charSet notation. If no charSet is specified,
+ the default charSet of [A-Z][a-z][0-9] will be used.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --statInterval {statInterval}</option></term>
+ <listitem>
+ <para>Display results each specified number of seconds</para>
+ <para>Default value: 5</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-m, --maxIterations {maxIterations}</option></term>
+ <listitem>
+ <para>Max iterations, 0 for unlimited</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-M, --targetThroughput {targetThroughput}</option></term>
+ <listitem>
+ <para>Target average throughput to achieve</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --searchScope {searchScope}</option></term>
+ <listitem>
+ <para>Search scope ('base', 'one', 'sub', or 'subordinate')</para>
+ <para>Default value: sub</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --scriptFriendly</option></term>
+ <listitem>
+ <para>Use script-friendly mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --numConcurrentTasks {numConcurrentTasks}</option></term>
+ <listitem>
+ <para>Number of concurrent tasks per connection</para>
+ <para>Default value: 1</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-E, --reportAuthzID</option></term>
+ <listitem>
+ <para>Use the authorization identity control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para> Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server port number</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --useStartTLS</option></term>
+ <listitem>
+ <para>Use StartTLS to secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePasswordPolicyControl</option></term>
+ <listitem>
+ <para>Use the password policy request control</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --useSSL</option></term>
+ <listitem>
+ <para>Use SSL for secure communication with the server</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>89</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example demonstrates measuring search performance.</para>
+ <screen>$ grep ^uid: /path/to/Example.ldif | sed -e "s/uid: //" > names.txt
+$ searchrate -p 1389 -b dc=example,dc=com -A -F -c 4 -t 4
+ -g "rand(names.txt)" "(uid=%s)"
+-------------------------------------------------------------------------------
+ Throughput Response Time
+ (ops/second) (milliseconds)
+recent average recent average 99.9% 99.99% 99.999% err/sec Entries/Srch
+-------------------------------------------------------------------------------
+1475.9 1475.9 0.423 0.423 6.938 126.236 126.236 0.0 1.0
+2596.5 2038.4 0.254 0.315 6.866 12.980 126.236 0.0 1.0
+3210.7 2428.2 0.205 0.267 5.733 11.710 126.236 0.0 1.0
+3080.5 2591.0 0.215 0.252 5.733 10.541 126.236 0.0 1.0
+3236.9 2720.1 0.203 0.240 5.258 10.514 126.236 0.0 1.0
+3181.1 2796.8 0.207 0.234 5.258 10.384 126.236 0.0 1.0
+3202.5 2854.8 0.206 0.229 4.825 10.384 126.236 0.0 1.0
+^C</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-setup.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-setup.xml
new file mode 100644
index 0000000..aa6d450
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-setup.xml
@@ -0,0 +1,345 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='setup-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>setup</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>setup</refname>
+ <refpurpose>install OpenDJ directory server</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>setup</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to setup the directory server.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --addBaseEntry</option></term>
+ <listitem>
+ <para>Indicates whether to create the base entry in the directory server
+ database</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--adminConnectorPort {port}</option></term>
+ <listitem>
+ <para>Port on which the Administration Connector should listen for
+ communication</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN for user information in the directory server. Multiple base
+ DNs may be provided by using this option multiple times</para>
+ <para>Default value: dc=example,dc=com</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-d, --sampleData {numEntries}</option></term>
+ <listitem>
+ <para>Specifies that the database should be populated with the specified
+ number of sample entries</para>
+ <para>Default value: 0</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --rootUserDN {rootUserDN}</option></term>
+ <listitem>
+ <para>DN for the initial root user for the directory server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--generateSelfSignedCertificate</option></term>
+ <listitem>
+ <para>Generate a self-signed certificate that the server should use when
+ accepting SSL-based connections or performing StartTLS negotiation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>The fully-qualified directory server host name that will be used
+ when generating self-signed certificates for LDAP SSL/StartTLS, the
+ administration connector, and replication</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --cli</option></term>
+ <listitem>
+ <para>Use the command line install. If not specified the graphical
+ interface will be launched. The rest of the options (excluding help and
+ version) will only be taken into account if this option is specified</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --rootUserPasswordFile {rootUserPasswordFile}</option></term>
+ <listitem>
+ <para>Path to a file containing the password for the initial root user for
+ the directory server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --ldifFile {ldifFile}</option></term>
+ <listitem>
+ <para>Path to an LDIF file containing data that should be added to the
+ directory server database. Multiple LDIF files may be provided by using
+ this option multiple times</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of the certificate that the server should use when
+ accepting SSL-based connections or performing StartTLS negotiation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-O, --doNotStart</option></term>
+ <listitem>
+ <para>Do not start the server when the configuration is completed</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --ldapPort {port}</option></term>
+ <listitem>
+ <para>Port on which the Directory Server should listen for LDAP
+ communication</para>
+ <para>Default value: 389</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-q, --enableStartTLS</option></term>
+ <listitem>
+ <para>Enable StartTLS to allow secure communication with the server using
+ the LDAP port</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-R, --rejectFile {rejectFile}</option></term>
+ <listitem>
+ <para>Write rejected entries to the specified file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-S, --skipPortCheck</option></term>
+ <listitem>
+ <para>Skip the check to determine whether the specified ports are
+ usable</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--skipFile {skipFile}</option></term>
+ <listitem>
+ <para>Write skipped entries to the specified file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file. A PIN is required when you specify
+ to use an existing certificate (JKS, JCEKS, PKCS#12 or PKCS#11) as server
+ certificate</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--useJavaKeystore {keyStorePath}</option></term>
+ <listitem>
+ <para>Path of a Java Key Store (JKS) containing a certificate to be used
+ as the server certificate</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--useJCEKS {keyStorePath}</option></term>
+ <listitem>
+ <para>Path of a JCEKS containing a certificate to be used as the server
+ certificate</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePkcs11Keystore</option></term>
+ <listitem>
+ <para>Use a certificate in a PKCS#11 token that the server should use when
+ accepting SSL-based connections or performing StartTLS negotiation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--usePkcs12keyStore {keyStorePath}</option></term>
+ <listitem>
+ <para>Path of a PKCS#12 key store containing the certificate that the
+ server should use when accepting SSL-based connections or performing
+ StartTLS negotiation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --rootUserPassword {rootUserPassword}</option></term>
+ <listitem>
+ <para>Password for the initial root user for the Directory Server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN. A PIN is required when you specify
+ to use an existing certificate (JKS, JCEKS, PKCS#12 or PKCS#11) as server
+ certificate</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-x, --jmxPort {jmxPort}</option></term>
+ <listitem>
+ <para>Port on which the Directory Server should listen for JMX
+ communication</para>
+ <para>Default value: 1689</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Z, --ldapsPort {port}</option></term>
+ <listitem>
+ <para>Port on which the Directory Server should listen for LDAPS
+ communication. The LDAPS port will be configured and SSL will be enabled
+ only if this argument is explicitly specified</para>
+ <para>Default value: 636</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the tool will fail</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Run setup in quiet mode. Quiet mode will not output progress
+ information to standard output</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following command installs OpenDJ directory server, enabling
+ StartTLS and importing 100 example entries without interaction.</para>
+ <screen>$ ./opendj/setup --cli -b dc=example,dc=com -d 100 -D "cn=Directory Manager"
+ -w password -h `hostname` -p 1389
+ --generateSelfSignedCertificate --enableStartTLS -n
+
+OpenDJ <?eval ${docTargetVersion}?>
+Please wait while the setup program initializes...
+
+See /var/.../opends-setup-484...561.log for a detailed log of this operation.
+
+Configuring Directory Server ..... Done.
+Configuring Certificates ..... Done.
+Importing Automatically-Generated Data (100 Entries) ......... Done.
+Starting Directory Server .......... Done.
+
+To see basic server configuration status and configuration you can launch
+ /path/to/opendj/bin/status</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-start-ds.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-start-ds.xml
new file mode 100644
index 0000000..76478e2
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-start-ds.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='start-ds-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>start-ds</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>start-ds</refname>
+ <refpurpose>start OpenDJ directory server</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>start-ds</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to start the directory server, as well as to
+ obtain the server version and other forms of general server
+ information.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-L, --useLastKnownGoodConfig</option></term>
+ <listitem>
+ <para>Attempt to start using the configuration that was in place at the
+ last successful startup (if it is available) rather than using the current
+ active configuration.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --nodetach</option></term>
+ <listitem>
+ <para>Do not detach from the terminal and continue running in the
+ foreground. This option cannot be used with the -t, --timeout
+ option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Use quiet mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --systemInfo</option></term>
+ <listitem>
+ <para>Display general system information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --timeout {seconds}</option></term>
+ <listitem>
+ <para>Maximum time (in seconds) to wait before the command returns (the
+ server continues the startup process, regardless). A value of '0'
+ indicates an infinite timeout, which means that the command returns only
+ when the server startup is completed. The default value is 60 seconds.
+ This option cannot be used with the -N, --nodetach option.</para>
+ <para>Default value: 200</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following command starts the server without displaying
+ information about the startup process.</para>
+ <screen>$ start-ds -Q</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-status.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-status.xml
new file mode 100644
index 0000000..12b9820
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-status.xml
@@ -0,0 +1,255 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='status-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>status</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>status</refname>
+ <refpurpose>display basic OpenDJ server information</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>status</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to display basic server information.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ <para>Default value: cn=Directory Manager</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the tool will fail</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-r, --refresh {period}</option></term>
+ <listitem>
+ <para>When this argument is specified, the status command will display
+ its contents periodically. Used to specify the period (in seconds)
+ between two status displays</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-s, --script-friendly</option></term>
+ <listitem>
+ <para>Use script-friendly mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>$ status -D "cn=Directory Manager" -w password
+
+ --- Server Status ---
+Server Run Status: Started
+Open Connections: 1
+
+ --- Server Details ---
+Host Name: localhost.localdomain
+Administrative Users: cn=Directory Manager
+Installation Path: /path/to/opendj
+Version: OpenDJ <?eval ${docTargetVersion}?>
+Java Version: 1.6.0_29
+Administration Connector: Port 4444 (LDAPS)
+
+ --- Connection Handlers ---
+Address:Port : Protocol : State
+-------------:-------------:---------
+-- : LDIF : Disabled
+8989 : Replication : Enabled
+0.0.0.0:161 : SNMP : Disabled
+0.0.0.0:636 : LDAPS : Disabled
+0.0.0.0:1389 : LDAP : Enabled
+0.0.0.0:1689 : JMX : Disabled
+
+ --- Data Sources ---
+Base DN: dc=example,dc=com
+Backend ID: userRoot
+Entries: 160
+Replication: Enabled
+Missing Changes: 0
+Age of Oldest Missing Change: <not available>
+
+Base DN: dc=myCompany,dc=com
+Backend ID: myCompanyRoot
+Entries: 3
+Replication: Disabled
+
+Base DN: o=myOrg
+Backend ID: myOrgRoot
+Entries: 3
+Replication: Disabled
+</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-stop-ds.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-stop-ds.xml
new file mode 100644
index 0000000..242ed59
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-stop-ds.xml
@@ -0,0 +1,255 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='stop-ds-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>stop-ds</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>stop-ds</refname>
+ <refpurpose>stop OpenDJ directory server</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>stop-ds</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to request that the directory server stop
+ running or perform a restart.</para>
+ <para>When run without connection options, <command>stop-ds</command>
+ sends a signal to the OpenDJ process to stop the server. When run with
+ connection options, the <command>stop-ds</command> connects to the OpenDJ
+ administration port and creates a shutdown task to stop the server.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-r, --stopReason {stopReason}</option></term>
+ <listitem>
+ <para>Reason the server is being stopped or restarted.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-R, --restart</option></term>
+ <listitem>
+ <para>Attempt to automatically restart the server once it has
+ stopped.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-t, --stopTime {stopTime}</option></term>
+ <listitem>
+ <para>Indicates the date/time at which the shutdown operation will begin
+ as a server task expressed in format YYYYMMDDhhmmssZ for UTC time or
+ YYYYMMDDhhmmss for local time. A value of '0' will cause the shutdown to
+ be scheduled for immediate execution. When this option is specified the
+ operation will be scheduled to start at the specified time after which this
+ utility will exit immediately.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Y, --proxyAs {authzID}</option></term>
+ <listitem>
+ <para>Use the proxied authorization control with the given authorization
+ ID.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-D, --bindDN {bindDN}</option></term>
+ <listitem>
+ <para>DN to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --hostname {host}</option></term>
+ <listitem>
+ <para>Directory server hostname or IP address</para>
+ <para>Default value: 127.0.0.1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-p, --port {port}</option></term>
+ <listitem>
+ <para>Directory server administration port number</para>
+ <para>Default value: 4444</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ <para>Use <option>-w -</option> to have the command prompt for the
+ password, rather than enter the password on the command line.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Use quiet mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example restarts OpenDJ directory server.</para>
+ <screen>$ stop-ds --restart
+Stopping Server...
+
+...The Directory Server has started successfully</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-uninstall.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-uninstall.xml
new file mode 100644
index 0000000..f6e40ea
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-uninstall.xml
@@ -0,0 +1,303 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='uninstall-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>uninstall</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>uninstall</refname>
+ <refpurpose>remove OpenDJ directory server software</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>uninstall</command>
+ <arg choice="opt">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to uninstall the directory server.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-a, --remove-all</option></term>
+ <listitem>
+ <para>Remove all components of the server (this option is not compatible
+ with the rest of remove options)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-b, --backup-files</option></term>
+ <listitem>
+ <para>Remove backup files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --configuration-files</option></term>
+ <listitem>
+ <para>Remove configuration files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-d, --databases</option></term>
+ <listitem>
+ <para>Remove database contents</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-e, --ldif-files</option></term>
+ <listitem>
+ <para>Remove LDIF files</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-f, --forceOnError</option></term>
+ <listitem>
+ <para>Specifies whether the uninstall should continue if there is an error
+ updating references to this server in remote server instances or not. This
+ option can only be used with the --no-prompt option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --cli</option></term>
+ <listitem>
+ <para>Specifies to use the command line install. If not specified the
+ graphical interface will be launched. The rest of the options (excluding
+ help and version) will only be taken into account if this option is
+ specified</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-l, --server-libraries</option></term>
+ <listitem>
+ <para>Remove Server Libraries and Administrative Tools</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-L, --log-files</option></term>
+ <listitem>
+ <para>Remove log files</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>LDAP Connection Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>--connectTimeout {timeout}</option></term>
+ <listitem>
+ <para>Maximum length of time (in milliseconds) that can be taken to
+ establish a connection. Use '0' to specify no time out.</para>
+ <para>Default value: 30000</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-h, --referencedHostName {host}</option></term>
+ <listitem>
+ <para>The name of this host (or IP address) as it is referenced in remote
+ servers for replication</para>
+ <para>Default value: localhost.localdomain</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-I, --adminUID {adminUID}</option></term>
+ <listitem>
+ <para>User ID of the Global Administrator to use to bind to the
+ server.</para>
+ <para>Default value: admin</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-j, --bindPasswordFile {bindPasswordFile}</option></term>
+ <listitem>
+ <para>Bind password file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-K, --keyStorePath {keyStorePath}</option></term>
+ <listitem>
+ <para>Certificate key store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-N, --certNickname {nickname}</option></term>
+ <listitem>
+ <para>Nickname of certificate for SSL client authentication</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-o, --saslOption {name=value}</option></term>
+ <listitem>
+ <para>SASL bind options</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-P, --trustStorePath {trustStorePath}</option></term>
+ <listitem>
+ <para>Certificate trust store path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-T, --trustStorePassword {trustStorePassword}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-u, --keyStorePasswordFile {keyStorePasswordFile}</option></term>
+ <listitem>
+ <para>Certificate key store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-U, --trustStorePasswordFile {path}</option></term>
+ <listitem>
+ <para>Certificate trust store PIN file</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-w, --bindPassword {bindPassword}</option></term>
+ <listitem>
+ <para>Password to use to bind to the server</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-W, --keyStorePassword {keyStorePassword}</option></term>
+ <listitem>
+ <para>Certificate key store PIN</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-X, --trustAll</option></term>
+ <listitem>
+ <para>Trust all server SSL certificates</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. If data in the command is missing, the
+ user is not prompted and the tool will fail</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--noPropertiesFile</option></term>
+ <listitem>
+ <para>No properties file will be used to get default command line
+ argument values</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--propertiesFilePath {propertiesFilePath}</option></term>
+ <listitem>
+ <para>Path to the file containing default property values used for
+ command line arguments</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Run setup in quiet mode. Quiet mode will not output progress
+ information to standard output</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>> 0</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following command removes OpenDJ directory server without
+ interaction.</para>
+ <screen>$ ./opendj/uninstall -a --cli -I admin -w password -n
+
+Stopping Directory Server ..... Done.
+Deleting Files under the Installation Path ..... Done.
+
+The Uninstall Completed Successfully.
+To complete the uninstallation, you must delete manually the following files
+and directories:
+/path/to/opendj/lib
+See /var/.../opends-uninstall-3...0.log for a detailed log of this operation.
+$ rm -rf opendj</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-upgrade.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-upgrade.xml
new file mode 100644
index 0000000..b464c90
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-upgrade.xml
@@ -0,0 +1,212 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+<refentry xml:id='upgrade-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2013</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>upgrade</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>upgrade</refname>
+ <refpurpose>upgrade OpenDJ configuration & application data</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>upgrade</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+
+ <para>This utility upgrades OpenDJ configuration (schema, directory server
+ configuration, and other configuration files) and application data (primarily
+ directory data) so that it is compatible with the binary files and scripts
+ that are installed.</para>
+
+ <para>The <command>upgrade</command> command thus performs only part of the
+ upgrade process, which includes the following phases for a single
+ server.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Get and unpack a newer version of OpenDJ directory server
+ software.</para>
+ </listitem>
+ <listitem>
+ <para>Stop the current OpenDJ directory server.</para>
+ </listitem>
+ <listitem>
+ <para>Overwrite existing binary and script files with those of the
+ newer version, and then run this utility, the <command>upgrade</command>
+ command, before restarting OpenDJ.</para>
+ </listitem>
+ <listitem>
+ <para>Start the upgraded OpenDJ directory server.</para>
+ </listitem>
+ </orderedlist>
+
+ <important>
+ <para>The <command>upgrade</command> command <emphasis>does not back up
+ OpenDJ before you upgrade, nor does it restore OpenDJ if the
+ <command>upgrade</command> command fails</emphasis>. In order to revert a
+ failed upgrade, make sure you back up OpenDJ directory server before you
+ overwrite existing binary and script files.</para>
+ </important>
+
+ <para>By default, the <command>upgrade</command> command requests
+ confirmation before making important configuration changes. You can use
+ the <option>--no-prompt</option> option to run the command
+ non-interactively.</para>
+
+ <para>When using the <option>--no-prompt</option> option, if the
+ <command>upgrade</command> command 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 <option>--force</option> option to force a non-interactive upgrade
+ to continue in this case, also performing long running and critical
+ tasks.</para>
+
+ <para>After upgrading, see the resulting <filename>upgrade.log</filename>
+ file for a full list of operations performed.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>--acceptLicense</option></term>
+ <listitem>
+ <para>Automatically accepts the product license if there is one in the
+ delivery.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--force</option></term>
+ <listitem>
+ <para>Forces a non-interactive upgrade to continue even if it requires
+ user interaction. In particular, long running or critical upgrade tasks,
+ such as re-indexing, which require user confirmation will be skipped. This
+ option may only be used with the <option>--no-prompt</option> option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--ignoreErrors</option></term>
+ <listitem>
+ <para>Ignores any errors which occur during the upgrade. This option
+ should be used with caution and may be useful in automated deployments
+ where potential errors are known in advance and resolved after the upgrade
+ has completed.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Utility Input/Output Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-n, --no-prompt</option></term>
+ <listitem>
+ <para>Use non-interactive mode. Prompt for any required information
+ rather than fail.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-Q, --quiet</option></term>
+ <listitem>
+ <para>Use quiet mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-v, --verbose</option></term>
+ <listitem>
+ <para>Use verbose mode.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>2</term>
+ <listitem>
+ <para>The command was run in non-interactive mode, but could not complete
+ because confirmation was required to run a long or critical task.</para>
+ <para>See the error message or the log for details.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Other</term>
+ <listitem>
+ <para>An error occurred.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>See the <citetitle>Installation Guide</citetitle> for an example
+ upgrade process for OpenDJ directory server installed from the cross-platform
+ (.zip) delivery, <link xlink:show="new"
+ xlink:href="install-guide#upgrade-zip-example"
+ xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Upgrading From
+ OpenDJ 2.4.5</citetitle></link>.</para>
+
+ <para>Native packages (.deb, .rpm) perform more of the upgrade process,
+ stopping OpenDJ if it is running, overwriting older files with newer files,
+ running this utility, and starting OpenDJ if it was running when you upgraded
+ the package(s).</para>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/man-verify-index.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/man-verify-index.xml
new file mode 100644
index 0000000..c21d78a
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/man-verify-index.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2012 ForgeRock AS
+ !
+-->
+<refentry xml:id='verify-index-1'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <refmeta>
+ <refentrytitle>verify-index</refentrytitle><manvolnum>1</manvolnum>
+ <refmiscinfo class="software">OpenDJ</refmiscinfo>
+ <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>verify-index</refname>
+ <refpurpose>check index for consistency or errors</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>verify-index</command>
+ <arg choice="req">options</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Description</title>
+ <para>This utility can be used to ensure that index data is consistent
+ within a backend based on the Berkeley DB Java Edition.</para>
+ </refsect1>
+ <refsect1>
+ <title>Options</title>
+ <para>The following options are supported.</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-b, --baseDN {baseDN}</option></term>
+ <listitem>
+ <para>Base DN of a backend supporting indexing. Verification is
+ performed on indexes within the scope of the given base DN.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-c, --clean</option></term>
+ <listitem>
+ <para>Specifies that a single index should be verified to ensure it is
+ clean. An index is clean if each index value references only entries
+ containing that value. Only one index at a time may be verified in this
+ way.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--countErrors</option></term>
+ <listitem>
+ <para>Count the number of errors found during the verification and return
+ that value as the exit code (values > 255 will be reduced to 255 due to
+ exit code restrictions).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-i, --index {index}</option></term>
+ <listitem>
+ <para>Name of an index to be verified. For an attribute index this is
+ simply an attribute name. Multiple indexes may be verified for
+ completeness, or all indexes if no indexes are specified. An index is
+ complete if each index value references all entries containing that
+ value.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>General Options</title>
+ <variablelist>
+ <varlistentry>
+ <term><option>-V, --version</option></term>
+ <listitem>
+ <para>Display version information</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-?, -H, --help</option></term>
+ <listitem>
+ <para>Display usage information</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1>
+ <title>Exit Codes</title>
+ <variablelist>
+ <varlistentry>
+ <term>0</term>
+ <listitem>
+ <para>The command completed successfully.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>1</term>
+ <listitem>
+ <para>An error occurred while parsing the command-line arguments.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>0-255</term>
+ <listitem>
+ <para>The number of errors in the index, as indicated for the
+ <option>--countErrors</option> option.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <para>The following example verifies the <literal>cn</literal> (common
+ name) index for completeness and for errors.</para>
+
+ <screen>$ verify-index -b dc=example,dc=com -i cn --clean --countErrors
+[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
+ msgID=9437595 msg=Local DB backend userRoot does not specify the number of
+ lock tables: defaulting to 97
+[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
+ msgID=9437594 msg=Local DB backend userRoot does not specify the number of
+ cleaner threads: defaulting to 24 threads
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=NOTICE msgID=8847461
+ msg=Checked 1316 records and found 0 error(s) in 0 seconds
+ (average rate 2506.7/sec)
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388710 msg=Number of records referencing more than one entry: 315
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388711 msg=Number of records that exceed the entry limit: 0
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388712 msg=Average number of entries referenced is 1.58/record
+[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
+ msgID=8388713 msg=Maximum number of entries referenced by any
+ record is 32</screen>
+ </refsect1>
+</refentry>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/mediaobject-fr-logo.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/mediaobject-fr-logo.xml
new file mode 100644
index 0000000..f455105
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/mediaobject-fr-logo.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mediaobject xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <imageobject>
+ <imagedata fileref="images/forgerock-opendj-logo.png" role="top"/>
+ </imageobject>
+</mediaobject>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/screen-upgrade.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/screen-upgrade.xml
new file mode 100644
index 0000000..494da88
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/screen-upgrade.xml
@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+ <screen xml:id="upgrade-earliest-supported"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'
+>$ cd /path/to
+$ ls
+OpenDJ-2.4.5
+$ ./OpenDJ-2.4.5/bin/stop-ds --quiet
+... msg=The backend userRoot is now taken offline
+... msg=The Directory Server is now stopped
+$ zip -rq OpenDJ-backup.zip OpenDJ-2.4.5
+$ unzip -q ~/Downloads/OpenDJ-2.6.0.zip
+$ cp -r opendj/* OpenDJ-2.4.5/
+$ rm -rf opendj
+$ mv OpenDJ-2.4.5 opendj
+$ ./opendj/upgrade --no-prompt --acceptLicense
+
+>>>> OpenDJ Upgrade Utility
+
+ * OpenDJ will be upgraded from version 2.4.5.7743 to 2.6.0.9086
+ * See '/path/to/opendj/upgrade.log' for a detailed log of this operation
+
+READ THIS SOFTWARE LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING
+THE FORGEROCK SOFTWARE, YOU, ON BEHALF OF YOURSELF AND YOUR COMPANY, AGREE TO
+BE BOUND BY THIS SOFTWARE LICENSE AGREEMENT. IF YOU DO NOT AGREE TO THESE
+TERMS, DO NOT DOWNLOAD OR INSTALL THE FORGEROCK SOFTWARE.
+
+ ...
+
+Please read the License Agreement above.
+You must accept the terms of the agreement before continuing with the
+installation
+Do you accept the License Agreement? yes
+
+>>>> Preparing to upgrade
+
+ OpenDJ 2.5.0 modified the default configuration of the 'isMemberOf' virtual
+ attribute so that it is included with group entries. This was done in order
+ to make it easier for users to determine which groups a 'nested' group
+ belongs to.
+ Do you want to make this configuration change? (yes/no) yes
+
+ The upgrade is ready to proceed. Do you wish to continue? (yes/no) yes
+
+
+>>>> Performing upgrade
+
+ Fixing de-DE collation matching rule OID............................ 100%
+ Updating password policy configurations............................. 100%
+ Updating audit log publisher configuration.......................... 100%
+ Rename SNMP security config file.................................... 100%
+ Adding 'etag' virtual attribute schema.............................. 100%
+ Configuring 'etag' virtual attribute................................ 100%
+ Configuring 'ds-pwp-password-expiration-time' virtual attribute..... 100%
+ Updating certificate syntax configuration........................... 100%
+ Updating JPEG syntax configuration.................................. 100%
+ Updating country string syntax configuration........................ 100%
+ Modifying filter in 'isMemberOf' virtual attribute configuration.... 100%
+ Updating dictionary password validator configuration................ 100%
+ Updating attribute value password validator configuration........... 100%
+ Adding PBKDF2 password storage scheme configuration................. 100%
+ Adding 'http-config.json' configuration file........................ 100%
+ Adding HTTP connection handler configuration........................ 100%
+ Adding file-based HTTP access logger................................ 100%
+ Adding 'emailAddress' attribute..................................... 100%
+ Updating subject attribute to user attribute configuration.......... 100%
+ Replacing schema file '02-config.ldif'.............................. 100%
+ Archiving concatenated schema....................................... 100%
+
+>>>> OpenDJ was successfully upgraded from version 2.4.5.7743 to 2.6.0.9086
+
+ * See '/path/to/opendj/upgrade.log' for a detailed log of this operation
+$ ./opendj/bin/start-ds --quiet
+$ </screen>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/sec-accessing-doc-online.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-accessing-doc-online.xml
new file mode 100644
index 0000000..d429685
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-accessing-doc-online.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+ <section xml:id="accessing-doc-online"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Accessing OpenDJ Documentation Online</title>
+
+ <para>Core documentation, such as what you are now reading, aims to
+ be technically accurate and complete with respect to the software
+ documented. Core documentation therefore follows a <link xlink:show="new"
+ xlink:href='https://wikis.forgerock.org/confluence/display/devcom/Review+Process'
+ >three-phase review process</link> designed to eliminate errors. The
+ review process should slow authors down enough that documentation you get
+ with a stable release has had time to bake fully.</para>
+
+ <para>Fully baked core documentation is available at <link
+ xlink:href='http://docs.forgerock.org/'>docs.forgerock.org</link>.</para>
+
+ <para>The <link xlink:show="new"
+ xlink:href="https://wikis.forgerock.org/confluence/display/OPENDJ/Home">OpenDJ
+ Wiki</link> regularly brings you more, fresh content. In addition, you are
+ welcome to <link xlink:show="new"
+ xlink:href="https://idp.forgerock.org/openam/UI/Login?service=register">sign
+ up</link> and then edit the Wiki if you notice an error, or if you have
+ something to share.</para>
+</section>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/sec-formatting-conventions.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-formatting-conventions.xml
new file mode 100644
index 0000000..e245e9f
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-formatting-conventions.xml
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+ <section xml:id="formatting-conventions"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Formatting Conventions</title>
+
+ <para>Some items are formatted differently from other text, like
+ <filename>filenames</filename>, <command>commands</command>, and
+ <literal>literal values</literal>.</para>
+
+ <screen>$ echo Command line sessions are formatted with lines folded for easier reading.
+ In HTML documents click the [-] image for a flat, copy-paste version. Click
+ the [+] image for an expanded, line-wrapped version. > /dev/null</screen>
+
+ <para>In many cases, sections pertaining to UNIX, GNU/Linux, Mac OS X, BSD,
+ and so forth are marked (UNIX). Sections pertaining to Microsoft Windows
+ might be marked (Windows). To avoid repetition, however, file system
+ directory names are often given only in UNIX format as in
+ <filename>/path/to/opendj</filename>, even if the text applies to
+ <filename>C:\path\to\opendj</filename> as well.</para>
+
+ <para>Absolute path names usually begin with the placeholder
+ <filename>/path/to/</filename>, which might translate to
+ <filename>/opt/</filename>, <filename>C:\Program Files\</filename>, or
+ somewhere else on your system. Unless you install from native packages,
+ you create this location before you install.</para>
+
+ <programlisting language='java'>class Test {
+ public static void main(String [] args) {
+ System.out.println("This is a program listing.");
+ }
+}</programlisting>
+</section>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/sec-interface-stability.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-interface-stability.xml
new file mode 100644
index 0000000..b743ebe
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-interface-stability.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+ <section xml:id="interface-stability"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Interface Stability</title>
+
+ <para>This should be overwritten at build time.</para>
+</section>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/sec-joining-the-community.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-joining-the-community.xml
new file mode 100644
index 0000000..da52561
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-joining-the-community.xml
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2011-2013 ForgeRock AS
+ !
+-->
+ <section xml:id="joining-the-community"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Joining the OpenDJ Community</title>
+
+ <para>After you <link
+ xlink:href='https://idp.forgerock.org/openam/UI/Login?service=register'
+ >sign up</link> at ForgeRock, you can also login to the Wiki and the issue
+ database to follow what is happening with the project.</para>
+
+ <para>If you have questions regarding OpenDJ which are not answered by the
+ documentation, there is a mailing list which can be found at
+ <link xlink:href='https://lists.forgerock.org/mailman/listinfo/opendj'
+ >https://lists.forgerock.org/mailman/listinfo/opendj</link> where you are
+ likely to find an answer. You can also make suggestions
+ regarding updates at the documentation mailing list
+ (<link xlink:href='https://lists.forgerock.org/mailman/listinfo/docs'
+ xlink:show="new">https://lists.forgerock.org/mailman/listinfo/docs</link>).</para>
+
+ <para>You can join the IRC discussion in the #opendj room at
+ irc.freenode.net.</para>
+
+ <para>The Wiki has information on how to check out OpenDJ source code.
+ There is also a mailing list for OpenDJ development that can be found at
+ <link xlink:href='https://lists.forgerock.org/mailman/listinfo/opendj-dev'
+ >https://lists.forgerock.org/mailman/listinfo/opendj-dev</link>.
+ Should you want to contribute a patch, test, or feature, or want to author
+ part of the core documentation, first have a look on the ForgeRock Community
+ page at <link xlink:href='http://www.forgerock.org/get_involved.html'>
+ how to get involved</link>.</para>
+</section>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/sec-release-levels.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-release-levels.xml
new file mode 100644
index 0000000..24b53fd
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/sec-release-levels.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2013 ForgeRock AS
+ !
+-->
+ <section xml:id="release-levels"
+ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ <title>Release Levels</title>
+
+ <para>This should be overwritten at build time.</para>
+</section>
diff --git a/opendj-doc-generated-ref/src/main/docbkx/shared/table-filter-operators.xml b/opendj-doc-generated-ref/src/main/docbkx/shared/table-filter-operators.xml
new file mode 100644
index 0000000..536ea00
--- /dev/null
+++ b/opendj-doc-generated-ref/src/main/docbkx/shared/table-filter-operators.xml
@@ -0,0 +1,195 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ! CCPL HEADER START
+ !
+ ! This work is licensed under the Creative Commons
+ ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
+ ! To view a copy of this license, visit
+ ! http://creativecommons.org/licenses/by-nc-nd/3.0/
+ ! or send a letter to Creative Commons, 444 Castro Street,
+ ! Suite 900, Mountain View, California, 94041, USA.
+ !
+ ! You can also obtain a copy of the license at
+ ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
+ ! See the License for the specific language governing permissions
+ ! and limitations under the License.
+ !
+ ! If applicable, add the following below this CCPL HEADER, with the fields
+ ! enclosed by brackets "[]" replaced with your own identifying information:
+ ! Portions Copyright [yyyy] [name of copyright owner]
+ !
+ ! CCPL HEADER END
+ !
+ ! Copyright 2012 ForgeRock AS
+ !
+-->
+<table xml:id='filter-operators'
+ xmlns='http://docbook.org/ns/docbook'
+ version='5.0' xml:lang='en'
+ xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
+ xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'
+ xmlns:xinclude='http://www.w3.org/2001/XInclude'
+ pgwide="1" rules="none">
+ <title>LDAP Filter Operators</title>
+
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1*"/>
+ <colspec colnum="2" colwidth="3*" />
+ <colspec colnum="3" colwidth="3*" />
+ <thead>
+ <row>
+ <entry>Operator</entry>
+ <entry>Definition</entry>
+ <entry>Example</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row valign="top">
+ <entry><literal>=</literal></entry>
+ <entry>
+ <para>Equality comparison, as in <literal>(sn=Jensen)</literal>.</para>
+ <para>This can also be used with substring matches. For example, to match
+ last names starting with <literal>Jen</literal>, use the filter
+ <literal>(sn=Jen*)</literal>. Substrings are more expensive for the
+ directory server to index. Substring searches therefore might not be
+ permitted for many attributes.</para>
+ </entry>
+ <entry>
+ <para><literal>"(cn=My App)"</literal> matches entries with common name
+ <literal>My App</literal>.</para>
+ <para><literal>"(sn=Jen*)"</literal> matches entries with surname starting
+ with <literal>Jen</literal>.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal><=</literal></entry>
+ <entry>
+ <para>Less than or equal to comparison, which works
+ alphanumerically.</para>
+ </entry>
+ <entry>
+ <para><literal>"(cn<=App)"</literal> matches entries with
+ <literal>commonName</literal> up to those starting with App
+ (case-insensitive) in alphabetical order.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>>=</literal></entry>
+ <entry>
+ <para>Greater than or equal to comparison, which works
+ alphanumerically.</para>
+ </entry>
+ <entry>
+ <para><literal>"(uidNumber>=1151)"</literal> matches entries with
+ <literal>uidNumber</literal> greater than 1151.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>=*</literal></entry>
+ <entry>
+ <para>Presence comparison. For example, to match all entries having a
+ <literal>userPassword</literal>, use the filter
+ <literal>(userPassword=*)</literal>.</para>
+ </entry>
+ <entry>
+ <para><literal>"(member=*)"</literal> matches entries with a
+ <literal>member</literal> attribute.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>~=</literal></entry>
+ <entry>
+ <para>Approximate comparison, matching attribute values similar to the
+ value you specify.</para>
+ </entry>
+ <entry>
+ <para><literal>"(sn~=jansen)"</literal> matches entries with a surname
+ that sounds similar to <literal>Jansen</literal> (Johnson, Jensen, and
+ so forth).</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>[:dn][:<replaceable>oid</replaceable>]:=</literal></entry>
+ <entry>
+ <para>Extensible match comparison.</para>
+ <itemizedlist>
+ <para>At the end of the OID or language subtype, you further specify the
+ matching rule as follows:</para>
+ <listitem>
+ <para>Add <literal>.1</literal> for less than</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.2</literal> for less than or equal to</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.3</literal> for equal to (default)</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.4</literal> for greater than or equal to</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.5</literal> for greater than</para>
+ </listitem>
+ <listitem>
+ <para>Add <literal>.6</literal> for substring</para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ <entry>
+ <para><literal>(uid:dn:=bjensen)</literal> matches entries where
+ <literal>uid</literal> having the value <literal>bjensen</literal> is
+ a component of the entry DN.</para>
+ <para><literal>(lastLoginTime: 1.3.6.1.4.1.26027.1.4.5:=-13w)</literal>
+ matches entries with a last login time more recent than 13 weeks.</para>
+ <para>You also use extensible match filters with localized values.
+ Directory servers like OpenDJ support a variety of internationalized
+ locales, each of which has an OID for collation order, such as
+ <literal>1.3.6.1.4.1.42.2.27.9.4.76.1</literal> for French. OpenDJ also
+ lets you use the language subtype, such as <literal>fr</literal>, instead
+ of the OID.</para>
+ <para><literal>"(cn:dn:=My App)"</literal> matches entries who have
+ <literal>My App</literal> as the common name and also as the value of a
+ DN component.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>!</literal></entry>
+ <entry>
+ <para>NOT operator, to find entries that do not match the specified filter
+ component.</para>
+ <para>Take care to limit your search when using <literal>!</literal> to
+ avoid matching so many entries that the server treats your search as
+ unindexed.</para>
+ </entry>
+ <entry>
+ <para><literal>'!(objectclass=person)'</literal> matches non-person
+ entries.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>&</literal></entry>
+ <entry>
+ <para>AND operator, to find entries that match all specified filter
+ components.</para>
+ </entry>
+ <entry>
+ <para><literal>'(&(l=Cupertino)(!(uid=bjensen)))'</literal> matches
+ entries for users in Cupertino other than the user with ID
+ <literal>bjensen</literal>.</para>
+ </entry>
+ </row>
+ <row valign="top">
+ <entry><literal>|</literal></entry>
+ <entry>
+ <para>OR operator, to find entries that match one of the specified filter
+ components.</para>
+ </entry>
+ <entry>
+ <para><literal>"|(sn=Jensen)(sn=Johnson)"</literal> matches entries with
+ surname Jensen or surname Johnson.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
--
Gitblit v1.10.0