OPENDJ-1873 Add an OpenDJ developer's guide

Mark Craig

18.27.2015 7d069efa3a4eb29d12977f6f68e2a6de7b9d0101

OPENDJ-1873 Add an OpenDJ developer's guide

This patch builds a container for server documentation
aimed at developers using OpenDJ directory server.

This patch extracts such information from the admin guide,
so that guide focuses instead on
configuring and maintaining directory servers.

This guide does not yet implement, but does leave placeholders for,
chapters for developers extending and embedding OpenDJ
in Java-based applications.

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-admin-tools.xml

@@ -28,7 +28,8 @@
         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:xlink='http://www.w3.org/1999/xlink'
         xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <title>Administration Interfaces &amp; Tools</title>

 <para>OpenDJ server software installs with a cross-platform, Java Swing-based
@@ -168,334 +169,5 @@
   
 </section>

 <section xml:id="cli-overview">
  <title>Command-Line Tools</title>
  <indexterm><primary>Commands</primary></indexterm>
  
  <para>Before you try the examples in this guide, set your PATH to include
  the OpenDJ directory server tools. Where the tools are located depends on
  the operating system and on the packages used to install OpenDJ.</para>

  <table xml:id="cli-path-locations">
   <title>Paths To Administration Tools</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>OpenDJ running on...</entry>
      <entry>OpenDJ installed from...</entry>
      <entry>Default path to tools...</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>Apple Mac OS X, Linux distributions, Oracle Solaris</entry>
      <entry>WebStart, .zip</entry>
      <entry><filename>/path/to/opendj/bin</filename></entry>
     </row>
     <row>
      <entry>Linux distributions</entry>
      <entry>.deb, .rpm</entry>
      <entry><filename>/opt/opendj/bin</filename></entry>
     </row>
     <row>
      <entry>Microsoft Windows</entry>
      <entry>WebStart, .zip</entry>
      <entry><filename>C:\path\to\opendj\bat</filename></entry>
     </row>
     <row>
      <entry>Oracle Solaris</entry>
      <entry>SVR4</entry>
      <entry><filename>/usr/opendj/bin</filename></entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   You find the installation and upgrade tools,
   <command>setup</command>,
   <command>upgrade</command>,
   and <command>uninstall</command>,
   in the parent directory of the other tools,
   as these tools are not used for everyday administration.
   For example, if the path to most tools is
   <filename>/path/to/opendj/bin</filename>
   you can find these tools in
   <filename>/path/to/opendj</filename>.
   For instructions on how to use the installation and upgrade tools, see the
   <link
    xlink:show="new"
    xlink:href="install-guide#install-guide"
    xlink:role="http://docbook.org/xlink/role/olink"
   ><citetitle>Installation Guide</citetitle></link>.
  </para>

  <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>

  <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="reference#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="reference#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="reference#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="reference#dbtest-1"
    xlink:role="http://docbook.org/xlink/role/olink">dbtest</link></term>
    <listitem>
     <para>Debug databases for <literal>local-db</literal> backends.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><link xlink:href="reference#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>--batchFilePath</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>
      Alternatively, you can read commands from standard input
      by using the <option>--batch</option> option.
     </para>

     <para>In addition to the <link xlink:href="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#rebuild-index-1"
    xlink:role="http://docbook.org/xlink/role/olink">rebuild-index</link></term>
    <listitem>
     <para>Rebuild an index stored in an indexed backend.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><link xlink:href="reference#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="reference#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="reference#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="reference#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="reference#verify-index-1"
    xlink:role="http://docbook.org/xlink/role/olink">verify-index</link></term>
    <listitem>
     <para>Verify that an index stored in an indexed backend is not corrupt.</para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><link xlink:href="reference#windows-service"
    xlink:role="http://docbook.org/xlink/role/olink">windows-service</link>
    (Windows only)</term>
    <listitem>
     <para>Register OpenDJ as a Windows Service.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </section>
 <xinclude:include href="../shared/sec-cli-overview.xml" />
</chapter>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-connection-handlers.xml

@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -1185,7 +1184,7 @@

   <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"
   <link xlink:href="server-dev-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>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-privileges-acis.xml

@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -1173,7 +1172,7 @@
  <para>For hints on updating directory entries with
  <command>ldapmodify</command>, see the section on <link xlink:show="new"
  xlink:role="http://docbook.org/xlink/role/olink"
  xlink:href="admin-guide#modify-ldap"><citetitle>Modifying Entry
  xlink:href="server-dev-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>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-pwd-policy.xml

@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -790,7 +789,7 @@
     the parent of the subentry, <literal>dc=example,dc=com</literal>,
     or further restrict the subtree specification
     by adding a <literal>specificationFilter</literal>.
     See <link xlink:show="new" xlink:href="admin-guide#collective-attributes"
     See <link xlink:show="new" xlink:href="server-dev-guide#collective-attributes"
     xlink:role="http://docbook.org/xlink/role/olink"><citetitle
     >Collective Attributes</citetitle></link> for more information.
    </para>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-resource-limits.xml

@@ -8,8 +8,7 @@
  ! 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.
  ! 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.
  !
@@ -19,7 +18,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<chapter xml:id='chap-resource-limits'

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-schema.xml

@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -20,15 +19,16 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 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='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>
 
@@ -181,7 +181,7 @@
    using the <command>dsconfig</command> command.</para>

    <para>As you can read in examples like, <link xlink:show="new"
    xlink:href="admin-guide#extensible-match-search"
    xlink:href="server-dev-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
@@ -481,273 +481,5 @@
  </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 object class definitions
      from the following Internet-Drafts, RFCs, and standards:
     </para>

     <simplelist columns="1">
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-ietf-boreham-numsubordinates">draft-ietf-boreham-numsubordinates</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-findlay-ldap-groupofentries">draft-findlay-ldap-groupofentries</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-furuseth-ldap-untypedobject">draft-furuseth-ldap-untypedobject</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-good-ldap-changelog">draft-good-ldap-changelog</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-ietf-ldup-subentry">draft-ietf-ldup-subentry</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-wahl-ldap-adminaddr">draft-wahl-ldap-adminaddr</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc1274">RFC 1274</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc2079">RFC 2079</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc2256">RFC 2256</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc2798">RFC 2798</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3045">RFC 3045</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3296">RFC 3296</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3671">RFC 3671</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3672">RFC 3672</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4512">RFC 4512</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4519">RFC 4519</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4523">RFC 4523</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4524">RFC 4524</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4530">RFC 4530</member>
      <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc5020">RFC 5020</member>
      <member xlink:show="new" xlink:href="https://www.itu.int/rec/T-REC-X.501">X.501</member>
     </simplelist>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <filename>01-pwpolicy.ldif</filename>
    </term>
    <listitem>
     <para>
      This file contains schema definitions from
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/draft-behera-ldap-password-policy-09"
      >draft-behera-ldap-password-policy</link> (Draft 09),
      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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/draft-good-ldap-changelog"
      >draft-good-ldap-changelog</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc2713"
      >RFC 2713</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc2714"
      >RFC 2714</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc2739"
      >RFC 2739</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc2926"
      >RFC 2926</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc3112"
      >RFC 3112</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc3712"
      >RFC 3712</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc4403"
      >RFC 4403</link>, 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/draft-howard-rfc2307bis"
      >draft-howard-rfc2307bis</link>, which defines a mechanism
      for storing 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
      <link
       xlink:show="new"
       xlink:href="https://tools.ietf.org/html/rfc4876"
      >RFC 4876</link>, 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>
 <xinclude:include href="../shared/sec-standard-schema.xml" />
</chapter>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-understanding-ldap.xml

@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -324,7 +323,7 @@

  <para>For practical examples showing how to perform the key operations using
  the command line tools delivered with OpenDJ directory server, read
  <link xlink:show="new" xlink:href="admin-guide#chap-ldap-operations"
  <link xlink:show="new" xlink:href="server-dev-guide#chap-ldap-operations"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Performing LDAP
  Operations</citetitle></link>.</para>
 </section>
@@ -580,7 +579,7 @@
  access.</para>

  <para>For examples showing how to use RESTful access, see the chapter on
  <link xlink:show="new" xlink:href="admin-guide#chap-rest-operations"
  <link xlink:show="new" xlink:href="server-dev-guide#chap-rest-operations"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Performing
  RESTful Operations</citetitle></link>.</para>
 </section>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/index.xml

@@ -72,19 +72,14 @@
 <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' /> -->

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-groups.xml

File was renamed from opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-groups.xml
@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -20,21 +19,21 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 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='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>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
 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
@@ -42,10 +41,45 @@
 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>
 <itemizedlist>
  <para>
   In this chapter you will learn how to:
  </para>

  <listitem>
   <para>
    Create static (enumerated) groups
   </para>
  </listitem>

  <listitem>
   <para>
    Create dynamic groups based on LDAP URLs
   </para>
  </listitem>

  <listitem>
   <para>
    Create virtual static groups that make dynamic groups look like static groups
   </para>
  </listitem>

  <listitem>
   <para>
    Look up group membership efficiently
   </para>
  </listitem>

  <listitem>
   <para>
    Make sure that when an entry is deleted or modified,
    OpenDJ also updates affected groups appropriately
   </para>
  </listitem>
 </itemizedlist>

 <tip>
  <para>The examples in this chapter assume that an
  <para>The examples in this chapter are written with the assumption 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
@@ -313,8 +347,8 @@
  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
  <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>
@@ -486,7 +520,7 @@
member: uid=tmorris,ou=People,dc=example,dc=com</computeroutput>
  </screen>

 <para>By default the referential integrity plugin is configured to manage
 <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

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-ldap-operations.xml

File was renamed from opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-ldap-operations.xml
@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -24,38 +23,43 @@
  !    
-->
<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'>
         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>
 <para>
  OpenDJ directory server includes the OpenDJ Control Panel browser
  and also command-line tools for performing LDAP operations.
  In this chapter, you will learn how to use the command line tools
  to perform LDAP operations.
 </para>
 
 <xinclude:include href="../shared/sec-cli-overview.xml" />

 <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
  <para>Searching the directory is akin to 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
  <para>Whereas a paper phone book has only one index (alphabetical order
  by name), the directory has many indexes. When performing a search, you 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
  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
  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>
  
@@ -73,7 +77,7 @@
   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.
   and are looking for a printer as shown in the following example.
  </para>
  
  <screen>
@@ -81,11 +85,11 @@
  </screen>
  
  <para>In the example, the LDAP filter indicates to the directory that you
  want to lookup printer entries where the <literal>printerLocation</literal>
  want to look up 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
  and the type of 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
@@ -106,11 +110,11 @@
  </itemizedlist>
  
  <example xml:id="simple-filter-search">
   <title>Search: Simple Filter</title>
   <title>Search: Using Simple Filters</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>
   only DNs and user ID values:</para>
   
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*jensen*)" uid</userinput>
@@ -141,12 +145,10 @@
  </example>
  
  <example xml:id="complex-filter-search">
   <title>Search: Complex Filter</title>
   <title>Search: Using Complex Filters</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>
   containing <literal>jensen</literal> for users located in Santa Clara:</para>
   
   <screen>
$ <userinput>ldapsearch \
@@ -195,6 +197,11 @@
sn: Jensen
</computeroutput>
</screen>

   <para>
    The command returns the attributes associated with
    the <literal>person</literal> object class.
   </para>
   
   <para>Complex filters can use both "and" syntax,
   <literal>(&amp;(<replaceable>filtercomp</replaceable>)(<replaceable>filtercomp</replaceable>))</literal>,
@@ -206,8 +213,7 @@
   <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>
   to return all operational attributes, as in the following example:</para>
   
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen +</userinput>
@@ -220,14 +226,18 @@
entryDN: uid=bjensen,ou=people,dc=example,dc=com
entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c</computeroutput>
   </screen>

   <para>
    Alternatively, specify operational attributes by name.
   </para>
  </example>
  
  <example xml:id="attr-desc-list-search">
   <title>Search: Return Attributes for an Object Class</title>
   <title>Search: Returning 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>
   a particular object class as in the following example:</para>
   
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen @person</userinput>
@@ -276,7 +286,7 @@
   </itemizedlist>

   <para>The following example shows a filter with escaped characters matching
   an actual value.</para>
   an actual value:</para>

   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com \
@@ -287,24 +297,27 @@
  </example>

  <example xml:id="extensible-match-search"><?dbfo keep-together="auto"?>
   <title>Search: List Active Accounts</title>
   <title>Search: Listing 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
   you accomplish 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:show="new"
    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
   an Extensible Match Index</citetitle></link>, which shows 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>
   <para>
    First set up an attribute to store a last login timestamp.
    You can do this by adding a schema file for the attribute
    as in the following example.
   </para>

   <screen>
$ <userinput>ldapmodify \
@@ -330,11 +343,14 @@
MODIFY operation successful for DN cn=schema</computeroutput>
   </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>
   <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>
$ <userinput>dsconfig \
@@ -350,10 +366,13 @@
 --no-prompt</userinput>
   </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>
   <para>
    Wait 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>
$ <userinput>ldapsearch \
@@ -369,7 +388,7 @@
  </example>

  <example xml:id="localized-search"><?dbfo keep-together="auto"?>
   <title>Search: Language Subtype</title>
   <title>Search: Using Language Subtypes</title>

   <para>OpenDJ directory server supports many language subtypes. See the
   chapter on <link xlink:href="reference#appendix-l10n"
@@ -380,7 +399,7 @@
   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>
   decode the attribute value:</para>

   <screen>
$ <userinput>ldapsearch \
@@ -395,7 +414,7 @@
   </screen>

   <itemizedlist>
    <para>At the end of the OID or language subtype, you further specify the
    <para>At the end of the OID or language subtype, further specify the
    matching rule as follows:</para>
    <listitem>
     <para>Add <literal>.1</literal> for less than</para>
@@ -419,7 +438,7 @@
  </example>

  <para>The following table describes the operators you can use in LDAP search
  filters.</para>
  filters:</para>
  <xinclude:include href="../shared/table-filter-operators.xml" />
 </section>

@@ -484,7 +503,7 @@
   and export data.</para>
   
   <example xml:id="add-two-users">
   <title>Add: Two New Users</title>
   <title>Adding Two New Users</title>
   
   <screen>
$ <userinput>cat new-users.ldif</userinput>
@@ -528,8 +547,8 @@
  <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>
   <para>The following example shows you how to add a description and JPEG photo to Sam
   Carter's entry:</para>
   
   <screen>
$ <userinput>cat scarter-mods.ldif</userinput>
@@ -555,7 +574,7 @@
   <title>Modify: Changing an Attribute Value</title>
   
   <para>The following example replaces the description on Sam Carter's
   entry.</para>
   entry:</para>
   
   <screen>
$ <userinput>cat scarter-newdesc.ldif</userinput>
@@ -578,7 +597,7 @@
   <title>Modify: Deleting an Attribute Value</title>
   
   <para>The following example deletes the JPEG photo on Sam Carter's
   entry.</para>
   entry:</para>
   
   <screen>
$ <userinput>cat /path/to/scarter-deljpeg.ldif</userinput>
@@ -597,14 +616,13 @@
  </example>

   <example xml:id="modify-optimistic-concurrency"><?dbfo keep-together="auto"?>
    <title>Modify: Optimistic Concurrency</title>
    <title>Modify: Using 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>
    and updates 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
@@ -613,7 +631,7 @@
    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.
    <para>OpenDJ includes two features to help you in this situation.
    One of the features is the <link
    xlink:role="http://docbook.org/xlink/role/olink"
    xlink:href="reference#assertion-request-control">LDAP Assertion
@@ -624,7 +642,7 @@
    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
    <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
@@ -638,7 +656,7 @@
    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>
    without interruption. Now Babs's entry looks like this.</para>

    <programlisting language="ldif">dn: uid=bjensen,ou=People,dc=example,dc=com
description: Updated by Alice
@@ -648,7 +666,7 @@
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
    assertion control to prevent Bob's update from succeeding although the
    ETag value has changed. Your application tries the equivalent of the
    following commands with Bob's updates.</para>

@@ -676,8 +694,8 @@
 and the associated filter did not match the contents of the that entry</computeroutput>
    </screen>

    <para>Your application therefore reloads Babs's entry, also getting the new
    ETag value, <literal>00000000aec2c1e9</literal>, and lets Bob try again.
    <para>Your application reloads Babs's entry, gets 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>

@@ -691,7 +709,7 @@
  </section>

  <section xml:id="filter-adds-modifies">
   <title>Filtering Add &amp; Modify Operations</title>
   <title>Filtering Add and Modify Operations</title>
   <indexterm>
    <primary>Updating data</primary>
    <secondary>Filtering</secondary>
@@ -702,12 +720,12 @@
   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
   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>
   modify requests, rename attributes in requests using incorrect names,
   and remove attributes that applications should not change.</para>
   
   <example xml:id="attr-cleanup-rename">
    <title>Renaming Incoming Attributes</title>
@@ -731,7 +749,7 @@
 --no-prompt</userinput>
    </screen>
    
    <para>Next, see that it works as expected.</para>
    <para>Next, confirm that it worked as expected.</para>
    
    <screen>$ <userinput>cat email.ldif</userinput>
<computeroutput>dn: uid=newuser,ou=People,dc=example,dc=com
@@ -788,7 +806,7 @@
 --no-prompt</userinput>
    </screen>
    
    <para>Next, see that it works as expected.</para>
    <para>Next, confirm that it worked as expected.</para>
    
    <screen>
$ <userinput>cat badattrs.ldif</userinput>
@@ -837,24 +855,23 @@
   <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
   entry's DN that differentiates 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
   the RDN of the entry with the 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>
   modifying the value of the naming attribute and 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.
    The following example shows you how to rename and change Sam Carter's entry.
    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
@@ -898,11 +915,11 @@
   <title>Moving Entries</title>

   <para>When you rename an entry with child entries, the directory has
   to move all the entries underneath.</para>
   to move all the entries underneath it.</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
    back end, under the same suffix. Also, depending on the number of entries
    you move, this can be a resource-intensive operation.</para>
   </note>
     
@@ -915,14 +932,14 @@
    
    <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
    <literal>ou=People,dc=example,dc=com</literal>, 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>
    under <literal>ou=People,dc=example,dc=com</literal> as well, and finally
    removes 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
    old RDNs, in this case, <literal>uid</literal> attribute values, should
    be preserved.</para>
    
    <screen>
@@ -996,8 +1013,8 @@
   <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>
    <para>The following example shows you how to use the subtree delete option
    to remove all special users from the directory.</para>
    
    <screen>
$ <userinput>ldapdelete \
@@ -1027,7 +1044,7 @@
  </para>
  
  <example xml:id="password-reset">
   <title>Password Reset</title>
   <title>Resetting Passwords</title>
   <indexterm>
    <primary>Resetting passwords</primary>
   </indexterm>
@@ -1053,11 +1070,11 @@
     the LDAP Password Modify extended operation.
     If this extended operation is performed on a connection
     that is already associated with a user
     &#8212;in other words, when a user first does a bind on the connection,
     and then requests the LDAP Password Modify extended operation&#8212;
     (in other words, when a user first does a bind on the connection,
     then requests the LDAP Password Modify extended operation)
     then the operation is performed as the user associated with the connection.
     If the user associated with the connection
     is not the user whose password is being changed,
     is not the same user whose password is being changed,
     then OpenDJ considers it a password reset.
    </para>

@@ -1076,9 +1093,8 @@
    </para>

    <para>
     To change the password as the user, you can
     bind as the user whose password should be changed,
     use the
     To change the password as the user,
     bind as the user whose password should be changed, and use the
     <link
      xlink:show="new"
      xlink:href="http://tools.ietf.org/html/rfc3062"
@@ -1088,14 +1104,14 @@
     For instructions on using proxied authorization, see the section on
     <link
      xlink:show="new"
      xlink:href="admin-guide#proxied-authz"
      xlink:href="server-dev-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
    You could also accomplish a password reset with the
    <link
     xlink:show="new"
     xlink:href="reference#manage-account-1"
@@ -1116,7 +1132,7 @@
  </example>
  
  <example xml:id="change-own-password">
   <title>Change Own Password</title>
   <title>Changing One's 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>
@@ -1144,7 +1160,7 @@
  </example>

  <example xml:id="non-ascii-password">
   <title>Passwords With Special Characters</title>
   <title>Changing Passwords With Special Characters</title>

   <para>OpenDJ expects passwords to be UTF-8 encoded (base64 encoded when
   included in LDIF).</para>
@@ -1200,20 +1216,20 @@

  <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>
  a principal. Authentication is performed 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 &amp; 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>
  implements fine-grained access control for authorization.
  Authorization for an operation depends on who is requesting the operation.
  Directory servers must therefore authenticate a principal
  before they can authorize or deny access for particular operations.
  In LDAP, the bind operation authenticates the principal.
  The first LDAP operation in every LDAP session is generally a bind.</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
  in the directory and also by 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
@@ -1221,8 +1237,9 @@
  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
  client commands default to requesting anonymous binds
  when no credentials are provided,
  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
@@ -1231,14 +1248,14 @@
  <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>
  password because access controls for the sample data only let authorized
  users change directory data.</para>

  <para>Users rarely provide client applications with DNs, however. Instead
  <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
  identity string, or use a session where the bind has been performed 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>
@@ -1249,17 +1266,17 @@
  <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,
  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
  <para>When an identifier string provided by the user can be readily mapped to
  the user's entry DN, OpenDJ directory server can translate 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.
  authentication (Kerberos V5), SASL CRAM MD5, and DIGEST MD5 authentication.
  They also handle authorization IDs during password modify extended operations
  and proxied authorization.</para>

@@ -1290,7 +1307,7 @@
  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
  exact match identity mapper for email addresses, then use that for PLAIN
  SASL authentication as in the following example.</para>

  <screen>
@@ -1330,9 +1347,10 @@
userPassword: {SSHA}7S4Si+vPE513cYQ7otiqb8hjiCzU7XNTv0RPBA==</computeroutput>
  </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
  <para>OpenDJ directory server's Regular Expression identity mapper
  uses a regular expression to extract a substring from the string provided,
  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
@@ -1379,16 +1397,15 @@
  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>
  authorization, for example, to bind your application with its credentials,
  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>
  The default access control for OpenDJ lets authenticated users
  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
@@ -1398,7 +1415,7 @@
  make a change to Babs's entry as Kirsten.</para>
  
  <procedure xml:id="setup-proxied-authz">
   <title>To Set Up Proxied Authorization</title>
   <title>To Configure Proxied Authorization</title>
   <step>
    <para>Grant access to applications that can use proxied authorization.</para>

@@ -1461,10 +1478,11 @@
  <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>
  get user ID values from the client, such as <literal>bjensen</literal>,
  you can configure OpenDJ directory server to 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 determine the settings you need.</para>
 </section>

 <section xml:id="client-cert-auth">
@@ -1474,17 +1492,17 @@
  <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>
  consists of storing a digital certificate on the user entry, 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
  <para>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
  <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
@@ -1528,8 +1546,8 @@
  <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
   <para>Before you try to bind to OpenDJ directory server using a certificate,
   create a certificate, then add the certificate attributes to the
   entry.</para>

   <para><link xlink:href="http://opendj.forgerock.org/Example.ldif"
@@ -1634,13 +1652,13 @@
    <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
    <para>If you want OpenDJ to map the certificate to its fingerprint, use the
    <literal>ds-certificate-fingerprint</literal> attribute. 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>
    entry, use the <literal>ds-certificate-subject-dn</literal> attribute.</para>

    <screen>
$ <userinput>cat addcert.ldif</userinput>
@@ -1711,9 +1729,9 @@
    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>
    must 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>
$ <userinput>keytool \
@@ -1816,7 +1834,7 @@

   <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
    OpenDJ to make sure it reads the updated trust store and recognizes the
    certificate.</para>

    <screen>
@@ -2131,7 +2149,7 @@
    </para>

    <para>
     In the following example the store password is <literal>changeit</literal>.
     In the following example, the store password is <literal>changeit</literal>.
    </para>

    <screen>
@@ -2318,7 +2336,7 @@
    <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
    <para>Client 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>

@@ -2337,12 +2355,12 @@
  </procedure>

  <example xml:id="auth-with-client-cert"><?dbfo keep-together="auto"?>
   <title>Authenticate With Client Certificate</title>
   <title>Authenticating With Client Certificates</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>
   the certificate. As a test with example data, you can try an anonymous search,
   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
@@ -2378,7 +2396,7 @@
   </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>
   not well-known, import the CA certificate into your keystore.</para>

   <screen>
$ <userinput>keytool \

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-referrals.xml

File was renamed from opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-referrals.xml
@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -20,15 +19,15 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 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='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>Working With Referrals</title>
 <indexterm><primary>Referrals</primary></indexterm>
 
@@ -42,14 +41,32 @@
  <command>ldapsearch</command> command does not follow referrals.</para>
 </note>
 
 <para>Referrals are used for example when a some directory data are temporarily
 <para>Referrals are used, for example, when 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>
 <itemizedlist>
  <para>
   In this chapter you will learn how to:
  </para>

  <listitem>
   <para>
    Add referrals with the <command>ldapmodify</command> command
   </para>
  </listitem>

  <listitem>
   <para>
    Remove referrals with the <command>ldapmodify</command> command
   </para>
  </listitem>
 </itemizedlist>

 <para>
  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>
@@ -65,9 +82,9 @@
  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 requesting the affected entry or child entries. Client
  applications must be capable of following the referral returned. When the
  directory server responds for example to your search with referrals to one
  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>
@@ -75,8 +92,8 @@
 <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
  <para>To create an LDAP referral, either create a referral entry,
   or 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>
  

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-rest-operations.xml

File was renamed from opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-rest-operations.xml
@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -28,7 +27,8 @@
         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: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>
@@ -38,9 +38,14 @@
  OpenDJ lets you access directory data as
  <link xlink:show="new" xlink:href="http://json.org">JSON</link>
  resources over HTTP.
  This chapter demonstrates basic RESTful client operations
  by using the default configuration
  and sample directory data
  OpenDJ maps JSON resources onto LDAP entries.
  As a result, REST clients perform many of the same operations as LDAP clients
  with directory data.
 </para>

 <para>
  This chapter demonstrates RESTful client operations
  by using the default configuration and sample directory data
  <link
   xlink:show="new"
   xlink:href="admin-guide#import-ldif"
@@ -53,9 +58,60 @@
  >Example.ldif</link>.
 </para>

 <itemizedlist>
  <para>
   In this chapter, you will learn how to use the OpenDJ REST API
   that provides access to directory data over HTTP.
   In particular, you will learn how to:
  </para>

  <listitem>
   <para>
    <link linkend="create-rest">Create</link> a resource that does not yet exist
   </para>
  </listitem>

  <listitem>
   <para>
    <link linkend="read-rest">Read</link> a single resource
   </para>
  </listitem>

  <listitem>
   <para>
    <link linkend="update-rest">Update</link> an existing resource
   </para>
  </listitem>

  <listitem>
   <para>
    <link linkend="delete-rest">Delete</link> an existing resource
   </para>
  </listitem>

  <listitem>
   <para>
    <link linkend="patch-rest">Patch</link> part of an existing resource
   </para>
  </listitem>

  <listitem>
   <para>
    Perform a predefined <link linkend="action-rest">action</link>
   </para>
  </listitem>

  <listitem>
   <para>
    <link linkend="query-rest">Query</link> a set of resources
   </para>
  </listitem>
 </itemizedlist>

 <para>
  Before trying the examples, enable HTTP access to
  OpenDJ directory server as described in procedure,
  OpenDJ directory server as described in
  the <citetitle>Administration Guide</citetitle> procedure,
  <link
   xlink:show="new"
   xlink:href="admin-guide#setup-rest2ldap-connection-handler"
@@ -65,101 +121,37 @@
  but the procedure also shows how to set up HTTPS access to the server.
 </para>

 <para>Interface stability: <link xlink:href="reference#interface-stability"
 xlink:show="new" xlink:role="http://docbook.org/xlink/role/olink"
 >Evolving</link></para>
 <para>
  Interface stability:
  <link
   xlink:href="reference#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.
   All APIs built on this common layer let you perform the following operations.
  </para>

  <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>[,&#8230;]</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>

     <para>
      This parameter is used though not shown in most examples that follow.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </section>
 <xinclude:include href="../shared/sec-about-crest.xml">
  <xinclude:fallback>
   <para>
    Failed to include common content <filename>../shared/sec-about-crest.xml</filename>.
   </para>
  </xinclude:fallback>
 </xinclude:include>

 <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>
  <para>
   When you first try to read a resource
   that can be read as an LDAP entry with an anonymous search,
   you learn that you must authenticate as shown in the following example.
  </para>

  <screen>
$ <userinput>curl http://opendj.example.com:8080/users/bjensen</userinput>
@@ -170,10 +162,16 @@
}</computeroutput>
  </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>
  <para>
   HTTP status code 401 indicates that the request requires user authentication.
  </para>

  <para>
   To prevent OpenDJ directory server from requiring authentication,
   set the HTTP connection handler property
   <literal>authentication-required</literal> to <literal>false</literal>,
   as in the following example.
  </para>

  <screen>
$ <userinput>dsconfig \
@@ -188,18 +186,24 @@
 --trustAll</userinput>
  </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>
   By default, both the HTTP Connection Handler and also the REST LDAP gateway
   allow HTTP Basic authentication and HTTP header-based authentication
   in the style of OpenIDM.
   The authentication mechanisms translate HTTP authentication
   to LDAP authentication to the directory server.
  </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>
  <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 (DN) attribute for sample user entries
   is the user ID (<literal>uid</literal>) attribute.
   For example, the DN and user ID for Babs Jensen are:
  </para>

  <programlisting language="ldif">
dn: uid=bjensen,ou=People,dc=example,dc=com
@@ -208,9 +212,9 @@

  <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 directly under
   the default REST to LDAP configuration translates
   the HTTP user name to the LDAP user ID.
   User entries are found directly under
   <literal>ou=People,dc=example,dc=com</literal>.<footnote>
    <para>
     In general, REST to LDAP mappings require
@@ -220,11 +224,13 @@
   </footnote>
   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
   The corresponding LDAP bind DN is
   <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>.
  </para>

  <para>With HTTP Basic authentication, it looks like this.</para>
  <para>
   HTTP Basic authentication works as shown in the following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -236,9 +242,10 @@
}</computeroutput>
  </screen>

  <para>Or, using the HTTP Basic
  <replaceable>username</replaceable>:<replaceable>password</replaceable>@ form
  in the URL, it looks like this.</para>
  <para>
   The alternative HTTP Basic
   <replaceable>username</replaceable>:<replaceable>password</replaceable>@ form
   in the URL works as shown in the following example.  </para>

  <screen>
$ <userinput>curl \
@@ -249,7 +256,9 @@
}</computeroutput>
  </screen>

  <para>With HTTP header based authentication, it looks like this.</para>
  <para>
   HTTP header based authentication works as shown in the following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -262,34 +271,48 @@
}</computeroutput>
  </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>
   If the directory data is laid out differently
   or if the 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="reference#appendix-rest2ldap"
  xlink:role="http://docbook.org/xlink/role/olink"><citetitle>REST LDAP
  Configuration</citetitle></link> for details on all configuration
  choices.</para>
  <para>
   The REST LDAP gateway can also translate
   HTTP user name and password authentication to LDAP PLAIN SASL authentication.
   Likewise, the gateway falls back to proxied authorization as necessary,
   using a root DN authenticated connection to LDAP servers.
   See the <citetitle>Reference</citetitle> appendix,
   <link
    xlink:show="new"
    xlink:href="reference#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>
    There are two alternative ways to create resources.
   </para>

    <para>The following example creates a new user entry with ID
    <literal>newuser</literal>.</para>
   <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 shows you how to create
     a new user entry with ID <literal>newuser</literal>.
    </para>

    <screen>
$ <userinput>curl \
@@ -342,9 +365,11 @@
   </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>
    <para>
     To create a resource in a way that lets 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>
@@ -352,7 +377,9 @@
 <section xml:id="read-rest">
  <title>Reading a Resource</title>

  <para>To read a resource, perform an HTTP GET.</para>
  <para>
   To read a resource, perform an HTTP GET as shown in the following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -387,11 +414,15 @@
 <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>
   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>
  <para>
   The following example adds a manager for Sam Carter.
  </para>

  <screen>
$ <userinput>curl \
@@ -449,9 +480,11 @@
}</computeroutput>
  </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>
  <para>
   To update a resource only if the resource matches a particular version,
   use an <literal>If-Match: <replaceable>revision</replaceable></literal> header
   as shown in the following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -462,7 +495,7 @@
$ <userinput>curl \
 --request PUT \
 --user kvaughan:bribery \
--header "If-Match: 00000000b017c5b8" \
 --header "If-Match: 00000000b017c5b8" \
 --header "Content-Type: application/json" \
 --data '{
   "contactInformation": {
@@ -519,8 +552,10 @@
 <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>
  <para>
   To delete a resource, perform an HTTP DELETE on the resource URL.
   The operation returns the resource you deleted as shown in the following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -551,12 +586,14 @@
}</computeroutput>
  </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>
  <para>
   To delete a resource only if the resource matches a particular version,
   use an <literal>If-Match: <replaceable>revision</replaceable></literal> header
   as shown in the following example.
  </para>

  <screen>$ <userinput>curl
 --user kvaughan:bribery
  <screen>$ <userinput>curl \
 --user kvaughan:bribery \
 http://opendj.example.com:8080/users/newuser?_fields=_rev</userinput>
<computeroutput>{"_rev":"000000006d8d7358"}</computeroutput>

@@ -590,14 +627,17 @@
  </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>
    To delete a resource and all of 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>
   <para>
    In this example, the LDAP view of the user to delete shows two child entries
    as seen in the following example.
   </para>

   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN uid=nbohr,ou=people,dc=example,dc=com "(&amp;)" dn</userinput>
@@ -609,18 +649,25 @@
   </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>
    <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>
     <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>
    <para>
     Force the HTTP Connection Handler to reread its configuration
     as shown in the following <command>dsconfig</command> commands.
    </para>

    <screen>
$ <userinput>dsconfig \
@@ -646,8 +693,11 @@
   </listitem>

   <listitem>
    <para>Delete as a user who has rights to perform a subtree delete on
    the resource.</para>
    <para>
     Request the delete as a user who has rights
     to perform a subtree delete on the resource
     as shown in the following example.
    </para>

    <screen>
$ <userinput>curl \
@@ -677,18 +727,12 @@
 <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>
  <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 following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -727,14 +771,31 @@
}</computeroutput>
  </screen>

  <para>
   Notice in the example 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.
   This makes it possible to patch more than one part of the resource
   by using a set of patch operations in the same request.
  </para>

  <variablelist>
   <para>OpenDJ supports four types of patch operation.</para>
   <para>
    OpenDJ supports four types of patch operations:
   </para>

   <varlistentry>
    <term>"add"</term>
    <term><literal>add</literal></term>
    <listitem>
     <para>The add operation ensures that the target field contains the value
     provided, creating parent fields as necessary.</para>
     <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,
@@ -745,67 +806,93 @@
      (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>
     <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>
    <term><literal>remove</literal></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>
      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 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>
     <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>
    <term><literal>replace</literal></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>
     <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>
    <term><literal>increment</literal></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>
     <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 and negative to decrement.
      The target field must take 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>
   One key nuance in how a patch works with OpenDJ concerns 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 allow use of a hyphen to add an element to a set.
     Include the hyphen as the last element
     of the <literal>field</literal> JSON pointer path.
     For example:
     <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>
  <para>
   Perform patch operations as if arrays values were sets.
   The following example includes Barbara Jensen in a group
   by adding her to the set of members.
  </para>

  <screen>
$ <userinput>curl \
@@ -848,7 +935,9 @@
}</computeroutput>
  </screen>

  <para>Removing her from the group is similar.</para>
  <para>
   The following example removes Barbara Jensen from the group.
  </para>

  <screen>
$ <userinput>curl \
@@ -889,12 +978,9 @@
  </screen>

  <para>
   You can change the value of more than one attribute in a patch operation.
   To do so, include multiple operations in the body of the JSON patch.
   Notice that for a multi-valued attribute, the "value" field takes an array,
   whereas the "value" field takes a single value for a single-valued field.
   Also notice in the following example that for single-valued fields,
   an "add" operation has the same effect as a "replace" operation.
   To change the value of more than one attribute in a patch operation,
   include multiple operations in the body of the JSON patch,
   as shown in the following example.
  </para>

  <screen>
@@ -943,9 +1029,22 @@
}</computeroutput>
  </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>
  <para>
   Notice that for a multi-valued attribute,
   the <literal>value</literal> field takes an array,
   whereas the <literal>value</literal> field takes
   a single value for a single-valued field.
   Also notice that for single-valued fields,
   an <literal>add</literal> operation has the same effect
   as a <literal>replace</literal> operation.
  </para>

  <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,
   as shown in the following example.
  </para>

  <screen>
$ <userinput>curl \
@@ -992,20 +1091,26 @@
}</computeroutput>
  </screen>

  <para>The resource revision changes after you successfully perform the patch
  operation.</para>
  <para>
   The resource revision changes when the patch is successful.
  </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>
   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 the resource.
  </para>

  <para>The following example creates a new user entry.</para>
  <para>
   The following example creates a new user entry.
  </para>

  <screen>
$ <userinput>curl \
@@ -1059,14 +1164,15 @@
 <section xml:id="query-rest">
  <title>Querying Resource Collections</title>

  <para>To query resource collections, perform an HTTP GET with a
  <literal>_queryFilter=<replaceable>expression</replaceable></literal> parameter
  in your query string.</para>
  <para>
   To query resource collections, perform an HTTP GET with a
   <literal>_queryFilter=<replaceable>expression</replaceable></literal> parameter
   in the query string.
  </para>

  <para>
   The following listing summarizes the string representation
   for the filter expression.
   Continue reading for additional explanation.
   for the filter <replaceable>expression</replaceable>.
  </para>

  <programlisting language="none">
@@ -1094,7 +1200,7 @@

  <para>
   The following table shows some LDAP search filters
   with corresponding query filter expressions.
   with corresponding examples of query filter expressions.
  </para>

  <table pgwide="1">
@@ -1222,30 +1328,39 @@
  </table>

  <variablelist>
   <para>For query operations, your filter <replaceable>expression</replaceable>
   is 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>
    For query operations, the filter <replaceable>expression</replaceable>
    is 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>
   <para>
    In filter 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 also 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>
      <para>
       Build filters using the following comparison expressions:
      </para>

      <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>
        <para>
         Matches when the pointer equals the value, as in the following example.
        </para>

        <screen width="87">
$ <userinput>curl \
@@ -1282,8 +1397,9 @@
      <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>
        <para>
         Matches when the pointer contains the value, as in the following example.
        </para>

        <screen width="91">
$ <userinput>curl \
@@ -1316,8 +1432,9 @@
      <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>
        <para>
         Matches when the pointer starts with the value, as in the following example.
        </para>

        <screen width="87">
$ <userinput>curl \
@@ -1340,8 +1457,9 @@
      <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>
        <para>
         Matches when the pointer is less than the value, as in the following example.
        </para>

        <screen width="87">
$ <userinput>curl \
@@ -1364,8 +1482,10 @@
      <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>
        <para>
         Matches when the pointer is less than or equal to the value,
         as in the following example.
        </para>

        <screen width="87">
$ <userinput>curl \
@@ -1390,8 +1510,10 @@
      <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>
        <para>
         Matches when the pointer is greater than the value,
         as in the following example.
        </para>

        <screen width="87">
$ <userinput>curl \
@@ -1416,8 +1538,10 @@
      <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>
        <para>
         Matches when the pointer is greater than or equal to the value,
         as in the following example.
        </para>

        <screen width="87">
$ <userinput>curl \
@@ -1443,9 +1567,12 @@
   <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>
     <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>
$ <userinput>curl \
@@ -1493,11 +1620,18 @@
   <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>
      <literal>true</literal> matches any resource in the collection.
     </para>

     <para>In other words you can list all resources in a collection as in the
     following example.</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>
$ <userinput>curl \
@@ -1526,16 +1660,14 @@
   <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>
     <para>
      Combine expressions using boolean operators
      <literal>and</literal>, <literal>or</literal>, and <literal>!</literal> (not),
      and by using parentheses <literal>(<replaceable>expression</replaceable>)</literal>
      with group expressions.
      The following example queries resources with last name Jensen
      and manager name starting with <literal>Bar</literal>.
     </para>

     <screen>
$ <userinput>curl \
@@ -1553,6 +1685,14 @@
  "remainingPagedResults" : -1
}</computeroutput>
     </screen>

     <para>
      Notice that the filters use the JSON pointers
      <literal>name/familyName</literal>
      and <literal>manager/displayName</literal>
      to identify the fields nested inside the
      <literal>name</literal> and <literal>manager</literal> objects.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
@@ -1605,7 +1745,7 @@
     <para>
      When <literal>_pagedResultsCookie</literal> is also set,
      the starting point is the position tracked by the cookie.
      Otherwise the offset is relative to the beginning of the result set.
      Otherwise, the offset is relative to the beginning of the result set.
     </para>

     <para>
@@ -1650,16 +1790,8 @@
      to page through the results.
     </para>


     <para>
      The following example demonstrates the use of paged results.

      The first call requests 5 results per page, and retrieves the first page.

      The next call provides the cookie to request the next 5 results.

      The final call provides the cookie and requests the 10th page of results
      after the last page of results specified by the cookie.
      The following example demonstrates how paged results are used.
     </para>

     <screen width="87">
@@ -1727,7 +1859,14 @@
     </screen>

     <para>
      Notice that <literal>"remainingPagedResults" : -1</literal> in each case
      The first call requests five results per page, and retrieves the first page.
      The next call provides the cookie to request the next five results.
      The final call provides the cookie and requests the 10th page of results
      after the last page of results specified by the cookie.
     </para>

     <para>
      Notice that <literal>"remainingPagedResults" : -1</literal> in each case,
      meaning that the number of remaining results is not known.
     </para>
    </listitem>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-schema.xml

New file
@@ -0,0 +1,729 @@
<?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 2015 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>Using LDAP Schema</title>
 <indexterm><primary>Schema</primary></indexterm>

 <para>
  LDAP services are based on X.500 Directory Services,
  which are telecommunications standards.
  In telecommunications, interoperability is paramount.
  Competitors must cooperate to the extent that they use each others' systems.
  For directory services, the protocols for exchanging data
  and the descriptions of the data are standardized.
  LDAP defines <firstterm>schema</firstterm> that describe both
  what attributes a given LDAP entry must have and may optionally have,
  and also what attribute values can contain and how they can be matched.
  Formal schema definitions protect interoperability when many applications
  read and write to the same directory service.
  Directory data are much easier to share
  as long as you understand how to use LDAP schema.
 </para>

 <para>
  The <citetitle>Administration Guide</citetitle> chapter on
  <link
   xlink:show="new"
   xlink:href="admin-guide#chap-schema"
   xlink:role="http://docbook.org/xlink/role/olink"
  ><citetitle>Managing Schema</citetitle></link>
  covers LDAP schema from the server administrator's perspective.
  Administrators can update LDAP directory schema.
  OpenDJ directory server includes
  a large number of standard schema definitions available by default.
  Administrators can also adjust how strictly OpenDJ directory server
  applies schema definitions.
 </para>

 <para>
  This chapter covers LDAP schema from the script developer's perspective.
  As a script developer, you use the available schema
  and accept the server's application of schema when updating directory entries.
 </para>

 <itemizedlist>
  <para>
   In this chapter you will learn how to:
  </para>

  <listitem>
   <para>
    Look up available schemas
   </para>
  </listitem>

  <listitem>
   <para>
    Understand what the schemas allow
   </para>
  </listitem>

  <listitem>
   <para>
    Understand and resolve errors that arise due to schema violations
   </para>
  </listitem>
 </itemizedlist>

 <section xml:id="getting-schema-information">
  <title>Getting Schema Information</title>

  <indexterm>
   <primary>Schema</primary>
   <secondary>Reading definitions</secondary>
  </indexterm>

  <para>
   Directory servers publish information about services they provide
   as operational attributes of the <firstterm>root DSE</firstterm>.
   The root DSE is the entry with an empty string DN, <literal>""</literal>.
   DSE stands for DSA-Specific Entry.
   DSA stands for Directory System Agent.
   The DSE differs by server, but is generally nearly identical for replicas.
  </para>

  <para>
   OpenDJ directory server publishes the DN
   of the entry holding schema definitions as the value of the attribute
   <literal>subschemaSubentry</literal>
   as shown in <xref linkend="example-finding-schema" />.
  </para>

  <example xml:id="example-finding-schema">
   <title>Finding the Schema Entry</title>

   <para>
    Look up the schema DN:
   </para>

   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN "" --searchScope base "(&amp;)" subschemaSubentry</userinput>
<computeroutput>dn:
subschemaSubentry: cn=schema</computeroutput>
   </screen>

   <para>
    By default, the DN for the schema entry is <literal>cn=schema</literal>.
   </para>
  </example>

  <variablelist>
   <para>
    The schema entry has the following attributes
    whose values are schema definitions:
   </para>

   <varlistentry>
    <term><literal>attributeTypes</literal></term>
    <listitem>
     <para>
      <firstterm>Attribute type</firstterm> definitions describe
      attributes of directory entries,
      such as <literal>givenName</literal> or <literal>mail</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>objectClasses</literal></term>
    <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>.
      Object classes inherit from other object classes.
      For example, <literal>inetOrgPerson</literal> inherits
      from <literal>person</literal>.
     </para>

     <para>
      Object classes are specified as values of an entry's
      <literal>objectClass</literal> attribute.
     </para>

     <itemizedlist>
      <para>
       An object class can be one of the following:
      </para>

      <listitem>
       <para>
        <firstterm>Structural</firstterm> object classes define
        the core structure of the entry,
        generally representing a real-world object.
       </para>

       <para>
        By default, OpenDJ directory entries have
        a single structural object class
        or at least a single line of structural object class inheritance.
       </para>

       <para>
        The <literal>person</literal> object class is structural, for example.
       </para>
      </listitem>

      <listitem>
       <para>
        <firstterm>Auxiliary</firstterm> object classes define
        additional characteristics of entries.
       </para>

       <para>
        The <literal>posixAccount</literal> object class is auxiliary, for example.
       </para>
      </listitem>

      <listitem>
       <para>
        <firstterm>Abstract</firstterm> object classes define
        base characteristics for other object classes to inherit,
        and cannot themselves inherit from other object classes.
       </para>

       <para>
        The <literal>top</literal> object class from which others inherit
        is abstract, for example.
       </para>
      </listitem>
     </itemizedlist>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>ldapSyntaxes</literal></term>
    <listitem>
     <para>
      An <firstterm>attribute syntax</firstterm> constrains
      what directory clients can store as attribute values.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>matchingRules</literal></term>
    <listitem>
     <para>
      A <literal>Matching rule</literal> determines how the directory server
      compares attribute values to assertion values
      for LDAP search and LDAP compare operations.
     </para>

     <para>
      For example, in a search having the filter <literal>(uid=bjensen)</literal>
      the assertion value is <literal>bjensen</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>nameForms</literal></term>
    <listitem>
     <para>
      A <firstterm>name form</firstterm> specifies which attribute can be used
      as the relative DN (RDN) for a structural object class.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>dITStructureRules</literal></term>
    <listitem>
     <para>
      A <firstterm>DIT structure rule</firstterm> defines a relationship
      between directory entries by identifying the name form
      allowed for subordinate entries of a given superior entry.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <example xml:id="example-reading-schema-definition">
   <title>Reading an Object Class Schema Definition</title>

   <para>
    The schema entry in OpenDJ directory server is large
    because it contains all of the schema definitions.
    Filter the results when reading a specific schema definition.
    As schema definitions themselves are long strings,
    pass the <option>--dontWrap</option> option
    to the <command>ldapsearch</command> command when reading one.
   </para>

   <para>
    The example below reads the definition
    for the <literal>person</literal> object class:
   </para>

   <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN "cn=schema" \
 --searchScope base \
 --dontWrap \
 "(&amp;)" \
 objectClasses \
 | grep \'person\'</userinput>
 <computeroutput>objectClasses: ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )
  MAY ( userPassword $ telephoneNumber $ seeAlso $ description )
  X-ORIGIN 'RFC 4519' )</computeroutput>
   </screen>

   <para>
    Notice the use of the object class name in <command>grep \'person\'</command>
    to filter search results.
    The actual result would not be wrapped.
   </para>
  </example>

  <para>
   The object class defines
   which attributes an entry of that object class <emphasis>must</emphasis> have
   and which attributes the entry <emphasis>may</emphasis> optionally have.
   A <literal>person</literal> entry must have
   a <literal>cn</literal> and an <literal>sn</literal> attribute.
   A <literal>person</literal> entry may optionally have
   <literal>userPassword</literal>, <literal>telephoneNumber</literal>,
   <literal>seeAlso</literal>, and <literal>description</literal> attributes.
  </para>

  <para>
   To determine definitions of those attributes, read the LDAP schema
   as demonstrated in <xref linkend="example-reading-attribute-definitions" />.
  </para>

  <example xml:id="example-reading-attribute-definitions">
   <title>Reading Schema Definitions for an Attribute</title>

   <para>
    The following example shows you how to read the schema definition
    for the <literal>cn</literal> attribute:
   </para>

   <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN "cn=schema" \
 --searchScope base \
 --dontWrap \
 "(&amp;)" \
 attributeTypes \
 | grep \'cn\'</userinput>
 <computeroutput>attributeTypes: ( 2.5.4.3 NAME ( 'cn' 'commonName' ) SUP name X-ORIGIN 'RFC 4519' )</computeroutput>
   </screen>

   <para>
    The <literal>cn</literal> attribute inherits its definition
    from the <literal>name</literal> attribute.
    That attribute definition indicates attribute syntax and matching rules
    as shown in the following example:
   </para>

   <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN "cn=schema" \
 --searchScope base \
 --dontWrap \
 "(&amp;)" \
 attributeTypes \
 | grep \'name\'</userinput>
<computeroutput>attributeTypes: ( 2.5.4.41 NAME 'name' EQUALITY caseIgnoreMatch
  SUBSTR caseIgnoreSubstringsMatch
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} X-ORIGIN 'RFC 4519' )</computeroutput>
   </screen>

   <para>
    This means that the server ignores case when matching a common name value.
    Use the OID to read the syntax as shown in the following example:
   </para>

   <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN "cn=schema" \
 --searchScope base \
 --dontWrap \
 "(&amp;)" \
 ldapSyntaxes \
 | grep 1.3.6.1.4.1.1466.115.121.1.15</userinput>
<computeroutput>ldapSyntaxes: ( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' )</computeroutput>
   </screen>

   <para>
    Taken together with the information for the <literal>name</literal> attribute,
    the common name attribute value is a Directory String of at most 32,768 characters.
    For details about syntaxes, read
    <link xlink:href="http://tools.ietf.org/html/rfc4517" xlink:show="new"
    >RFC 4517, <citetitle>Lightweight Directory Access Protocol (LDAP):
     Syntaxes and Matching Rules</citetitle></link>.
    That document describes a Directory String as one or more UTF-8 characters.
   </para>
  </example>
 </section>

 <section xml:id="respecting-schema">
  <title>Respecting LDAP Schema</title>

  <indexterm>
   <primary>Schema</primary>
   <secondary>Respecting definitions</secondary>
  </indexterm>

  <para>
   For the sake of interoperability and to avoid polluting directory data,
   scripts and applications should respect LDAP schema.
   In the simplest case,
   scripts and applications can use the schemas already defined.
  </para>

  <para>
   OpenDJ directory server does accept updates to schema definitions
   over LDAP while the server is running.
   This means that when a new application calls for attributes
   that are not yet defined by existing directory schemas,
   the directory administrator can easily add them as described in
   <link
    xlink:show="new"
    xlink:href="admin-guide#update-schema"
    xlink:role="http://docbook.org/xlink/role/olink"
   ><citetitle>Updating Directory Schema</citetitle></link>
   as long as the new definitions do not conflict with existing definitions.
  </para>

  <para>
   General purpose applications handle many different types of data.
   Such applications must deal with schema compliance at run time.
   Software development kits such as the Java-based OpenDJ LDAP SDK
   provide mechanisms for reading schema definitions at run time
   and checking whether entry data is valid according to the schema definitions.
  </para>

  <variablelist>
   <para>
    Many scripts do not require run time schema checking.
    In such cases it is enough properly to handle
    schema-related LDAP result codes when writing to the directory:
   </para>

   <varlistentry>
    <term>LDAP result code: 17 (Undefined attribute type)</term>
    <listitem>
     <para>
      The requested operation failed because it referenced
      an attribute that is not defined in the server schema.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 18 (Inappropriate matching)</term>
    <listitem>
     <para>
      The requested operation failed because it attempted to perform
      an inappropriate type of matching against an attribute.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 20 (Attribute or value exists)</term>
    <listitem>
     <para>
      The requested operation failed because it would have resulted in
      a conflict with an existing attribute or attribute value in the target entry.
     </para>

     <para>
      For example, the request tried to add a second value
      to a single-valued attribute.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 21 (Invalid attribute syntax)</term>
    <listitem>
     <para>
      The requested operation failed because it violated the syntax
      for a specified attribute.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 34 (Invalid DN syntax)</term>
    <listitem>
     <para>
      The requested operation failed because it would have resulted in
      an entry with an invalid or malformed DN.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 64 (Naming violation)</term>
    <listitem>
     <para>
      The requested operation failed because it would have violated
      the server's naming configuration.
     </para>

     <para>
      For example, the request did not respect a name form definition.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 65 (Object class violation)</term>
    <listitem>
     <para>
      The requested operation failed because it would have resulted in
      an entry that violated the server schema.
     </para>

     <para>
      For example, the request tried to remove a required attribute,
      or tried to add an attribute that is not allowed.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>LDAP result code: 69 (Object class mods prohibited)</term>
    <listitem>
     <para>
      The requested operation failed because it would have modified]
      the object classes associated with an entry in an illegal manner.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   When you encounter an error, take the time to read the additional information.
   The additional information from OpenDJ directory server often suffices
   to allow you to resolve the problem directly.
  </para>

  <para>
   <xref linkend="example-object-class-violations" /> and
   <xref linkend="example-invalid-attribute-syntax" />
   show some common problems that can result from schema violations.
  </para>

  <example xml:id="example-object-class-violations">
   <title>Object Class Violations</title>

   <para>
    A number of schema violations show up as object class violations.
    The following request fails to add an <literal>undefined</literal> attribute.
   </para>

   <screen>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
 --bindPassword bribery
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: undefined
undefined: This attribute is not defined.
</userinput>
<computeroutput>Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation failed
Result Code:  65 (Object Class Violation)
Additional Information:  Entry uid=bjensen,ou=People,dc=example,dc=com cannot
  be modified because the resulting entry would have violated the server schema:
  Entry uid=bjensen,ou=People,dc=example,dc=com violates
  the Directory Server schema configuration because
  it includes attribute undefined which is not allowed
  by any of the objectclasses defined in that entry</computeroutput>
   </screen>

   <para>
    The solution in this case is to make sure
    that the <literal>undefined</literal> attribute is defined
    and that it is allowed by one of the object classes defined for the entry.
   </para>

   <para>
    The following request fails to add a second structural object class:
   </para>

   <screen>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
 --bindPassword bribery
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: organizationalUnit
</userinput>
<computeroutput>Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation failed
Result Code:  65 (Object Class Violation)
Additional Information:  Entry uid=bjensen,ou=People,dc=example,dc=com cannot
  be modified because the resulting entry would have violated the server schema:
  Entry uid=bjensen,ou=People,dc=example,dc=com violates
  the Directory Server schema configuration because
  it includes multiple conflicting structural objectclasses
  inetOrgPerson and organizationalUnit.
  Only a single structural objectclass is allowed in an entry</computeroutput>
   </screen>

   <para>
    The solution in this case is to define only one structural object class
    for the entry.
    Either Babs Jensen is a person or an organizational unit, but not both.
   </para>
  </example>

  <example xml:id="example-invalid-attribute-syntax">
   <title>Invalid Attribute Syntax</title>

   <para>
    The following request fails to add an empty string as
    a common name attribute value.
   </para>

   <screen>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
 --bindPassword bribery
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: cn
cn:
</userinput>
<computeroutput>Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
MODIFY operation failed
Result Code:  21 (Invalid Attribute Syntax)
Additional Information:  When attempting to modify entry
 uid=bjensen,ou=People,dc=example,dc=com to add one or more values
 for attribute cn, value "" was found to be invalid
 according to the associated syntax:
 The operation attempted to assign a zero-length value to an attribute
 with the directory string syntax</computeroutput>
   </screen>

   <para>
    As mentioned in <xref linkend="example-reading-attribute-definitions" />,
    a Directory String has one or more UTF-8 characters.
   </para>
  </example>
 </section>

 <section xml:id="abusing-schema">
  <title>Abusing LDAP Schema</title>

  <itemizedlist>
   <para>
    Follow the suggestions in <xref linkend="respecting-schema" />
    as much as possible.
    In particular follow these rules of thumb:
   </para>

   <listitem>
    <para>
     Test with your own copy of OpenDJ directory server
     to resolve schema issues before going live.
    </para>
   </listitem>

   <listitem>
    <para>
     Adapt your scripts and applications to avoid violating schema definitions.
    </para>
   </listitem>

   <listitem>
    <para>
     When existing schemas are not sufficient,
     request schema updates to add definitions
     that do not conflict with any already in use.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   When it is not possible to respect the schema definitions,
   you can sometimes work around LDAP schema constraints
   without changing OpenDJ directory server configuration.
   The schema defines an <literal>extensibleObject</literal> object class.
   The <literal>extensibleObject</literal> object class is auxiliary.
   It effectively allows entries to hold any user attribute,
   even attributes that are not defined in the schema.
  </para>

  <example xml:id="example-extensible-object">
   <title>Working Around Restrictions With ExtensibleObject</title>

   <para>
    The following example adds one attribute that is undefined
    and another that is not allowed.
   </para>

   <screen>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "uid=kvaughan,ou=people,dc=example,dc=com" \
 --bindPassword bribery
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: objectClass
objectClass: extensibleObject
-
add: undefined
undefined: This attribute is not defined in the LDAP schema.
-
add: serialNumber
serialNumber: This attribute is not allowed according to the object classes.
</userinput>
<computeroutput>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</computeroutput>
   </screen>

   <para>
    Use of the <literal>extensibleObject</literal> object class
    opens the door to abuse and can prevent interoperability.
    Restrict its use to cases where no better alternative is available.
   </para>
  </example>
 </section>

 <xinclude:include href="../shared/sec-standard-schema.xml" />
</chapter>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/chap-virtual-attrs-collective-attrs.xml

File was renamed from opendj-sdk/opendj-server-legacy/src/main/docbkx/admin-guide/chap-virtual-attrs-collective-attrs.xml
@@ -9,8 +9,7 @@
  ! 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.
  ! 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.
  !
@@ -20,15 +19,15 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 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='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>Working With Virtual and Collective Attributes</title>

 <para>OpenDJ supports virtual attributes with dynamically generated values.
@@ -37,8 +36,9 @@
 <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>
 <para>
  In this chapter you will learn how to define virtual and collective attributes.
 </para>
 
 <section xml:id="virtual-attributes">
  <title>Virtual Attributes</title>
@@ -67,7 +67,7 @@
   </varlistentry>
   <varlistentry>
    <term><literal>hasSubordinates</literal></term>
    <listitem><para>Boolean. Whether the entry has children.</para></listitem>
    <listitem><para>Boolean. Indicates whether the entry has children.</para></listitem>
   </varlistentry>
   <varlistentry>
    <term><literal>numSubordinates</literal></term>
@@ -101,9 +101,10 @@
     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
     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:show="new"
     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
@@ -153,9 +154,9 @@
  
  <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>
  <literal>user-defined</literal> type to create your own virtual attribute types.
   The virtual attribute is defined by the server configuration,
   which is not replicated.</para>
  
  <screen>
$ <userinput>dsconfig \
@@ -219,7 +220,7 @@
   <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>
   a user depending on their service level.</para>

    <note>
     <para>The following example depends on the <literal>cos</literal> object
@@ -394,13 +395,13 @@
  <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
   <para>This example demonstrates how to instruct OpenDJ to 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
   <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
@@ -452,13 +453,13 @@
  <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
   <para>This example demonstrates how to instruct OpenDJ to 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.
   <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>

@@ -517,7 +518,7 @@
   <literallayout class="monospaced"
   >collectiveConflictBehavior: real-overrides-virtual</literallayout>

   <para>This line says that if a collective attribute clashes with a real
   <para>This line indicates 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

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/index.xml

New file
@@ -0,0 +1,109 @@
<?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 2015 ForgeRock AS.
  !    
-->
<book xml:id='server-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:xinclude='http://www.w3.org/2001/XInclude'>
 <info>
  <xinclude:include href="../shared/mediaobject-fr-logo.xml" />

  <title>OpenDJ Directory Server Developer's Guide</title>
  <subtitle>Version ${docTargetVersion}</subtitle>
  <abstract>
   <para>
    Hands-on guide to using OpenDJ directory server
    with an emphasis on command-line tools.
    The OpenDJ project offers open source LDAP directory services in Java.
   </para>
  </abstract>

  <copyright>
   <year>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 />

 <xinclude:include href="preface.xml" />

 <xinclude:include href="chap-rest-operations.xml" />
 <xinclude:include href="chap-ldap-operations.xml" />

 <xinclude:include href="chap-schema.xml" />
 <xinclude:include href="chap-groups.xml" />
 <xinclude:include href="chap-virtual-attrs-collective-attrs.xml" />
 <xinclude:include href="chap-referrals.xml" />

 <!--
 <chapter xml:id="writing-plugins">
  <title>Writing an OpenDJ Plugin</title>

  <para>
   Not implemented yet, see OPENDJ-1344
  </para>
 </chapter>

 <chapter xml:id="writing-controls-ext-ops-plugins">
  <title>Writing Custom Controls and Extended Operations</title>

  <para>
   Not implemented yet
  </para>
 </chapter>
 <chapter xml:id="writing-task-plugins">
  <title>Writing Custom Scheduled Tasks</title>

  <para>
   Not implemented yet
  </para>
 </chapter>

 <chapter xml:id="embedding-opendj">
  <title>Embedding OpenDJ Server</title>

  <para>
   Not implemented yet, see OPENDJ-685
  </para>
 </chapter>
 -->

 <index />
</book>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/server-dev-guide/preface.xml

New file
@@ -0,0 +1,202 @@
<?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 2015 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 develop scripts that use OpenDJ tools.
  <!-- Java-based extensions to the directory server,
  and Java-based applications that embed the directory server. -->
 </para>

 <para>
  If you are building a Java-based Lightweight Directory Access Protocol (LDAP)
  client application, refer to the
  <link
   xlink:href="dev-guide#dev-guide"
   xlink:role="http://docbook.org/xlink/role/olink"
   xlink:show="new"
  ><citetitle>LDAP SDK Developer's Guide</citetitle></link> instead.
 </para>

 <itemizedlist>
  <para>
   In reading and following the instructions in this guide,
   you will learn how to:
  </para>

  <listitem>
   <para>
    Access OpenDJ directory server by using Representational State Transfer (REST)
    APIs over Hypertext Transfer Protocol (HTTP)
   </para>
  </listitem>

  <listitem>
   <para>
    Access OpenDJ directory server using the LDAP tools delivered with the server
   </para>
  </listitem>

  <listitem>
   <para>
    Use LDAP schema
   </para>
  </listitem>

  <listitem>
   <para>
    Work with standard LDAP groups and OpenDJ-specific groups
   </para>
  </listitem>

  <listitem>
   <para>
    Work with LDAP collective attributes and OpenDJ virtual attributes
   </para>
  </listitem>

  <listitem>
   <para>
    Work with LDAP referrals in search results
   </para>
  </listitem>

  <!--
    <listitem>
     <para>
      Develop custom OpenDJ Java plugins
     </para>
    </listitem>

    <listitem>
     <para>
      Develop custom controls and extended operations using Java plugins
     </para>
    </listitem>

    <listitem>
     <para>
      Develop custom scheduled tasks using Java plugins
     </para>
    </listitem>

    <listitem>
     <para>
      Embed OpenDJ in a Java application
     </para>
    </listitem>
  -->
 </itemizedlist>

 <section xml:id="using-this-guide">
  <title>Using This Guide</title>

  <para>
   This guide is intended for directory administrators
   who write scripts that use OpenDJ directory services<!--,
   and developers who write extensions for OpenDJ directory servers-->.
  </para>

  <itemizedlist>
   <para>
    This guide is written with the expectation
    that you already have basic familiarity with the following topics:
   </para>

   <listitem>
    <para>
     Installing OpenDJ directory server, if the server is not yet installed
    </para>

    <para>
     If you are not yet familiar with OpenDJ directory server installation,
     read the
     <link
      xlink:href="install-guide#install-guide"
      xlink:role="http://docbook.org/xlink/role/olink"
      xlink:show="new"
     ><citetitle>Installation Guide</citetitle></link> first.
    </para>
   </listitem>

   <listitem>
    <para>
     Using command-line tools
    </para>
   </listitem>

   <listitem>
    <para>
     LDAP and directory services
    </para>
   </listitem>
<!--
  </itemizedlist>

  <itemizedlist>
   <para>
    This guide is written with the assumption that readers of the chapters
    that show how to access OpenDJ directory server and to use the tools
    are familiar with the following topics:
   </para>
-->

   <listitem>
    <para>
     Basic OpenDJ server configuration
    </para>

    <para>
     Some examples in this guide require OpenDJ configuration steps.
    </para>
  </listitem>

   <listitem>
    <para>
     HTTP, JavaScript Object Notation (JSON), and web applications
    </para>
   </listitem>
  </itemizedlist>

<!--
  <para>
   This guide is written with the assumption that readers of the chapters
   that show how to extend and to embed OpenDJ directory server
   are familiar with writing applications in the Java programming language.
  </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>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/shared/sec-cli-overview.xml

New file
@@ -0,0 +1,500 @@
<?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.
  !
-->
<section xml:id="cli-overview"
         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>Command-Line Tools</title>
 <indexterm><primary>Commands</primary></indexterm>

 <para>
  Before you try the examples in this guide,
  set your PATH to include the OpenDJ directory server tools.
  Where the tools are located depends on the operating environment
  and on the packages used to install OpenDJ.
  <xref linkend="cli-path-locations" /> indicates where to find the tools.
 </para>

 <table xml:id="cli-path-locations">
  <title>Paths To Administration Tools</title>
  <tgroup cols="3">
   <thead>
    <row>
     <entry>OpenDJ running on...</entry>
     <entry>OpenDJ installed from...</entry>
     <entry>Default path to tools...</entry>
    </row>
   </thead>
   <tbody>
    <row>
     <entry>Apple Mac OS X, Linux distributions, Oracle Solaris</entry>
     <entry>WebStart, .zip</entry>
     <entry><filename>/path/to/opendj/bin</filename></entry>
    </row>
    <row>
     <entry>Linux distributions</entry>
     <entry>.deb, .rpm</entry>
     <entry><filename>/opt/opendj/bin</filename></entry>
    </row>
    <row>
     <entry>Microsoft Windows</entry>
     <entry>WebStart, .zip</entry>
     <entry><filename>C:\path\to\opendj\bat</filename></entry>
    </row>
    <row>
     <entry>Oracle Solaris</entry>
     <entry>SVR4</entry>
     <entry><filename>/usr/opendj/bin</filename></entry>
    </row>
   </tbody>
  </tgroup>
 </table>

 <para>
  You find the installation and upgrade tools,
  <command>setup</command>,
  <command>upgrade</command>,
  and <command>uninstall</command>,
  in the parent directory of the other tools,
  as these tools are not used for everyday administration.
  For example, if the path to most tools is
  <filename>/path/to/opendj/bin</filename>
  you can find these tools in
  <filename>/path/to/opendj</filename>.
  For instructions on how to use the installation and upgrade tools, see the
  <link
   xlink:show="new"
   xlink:href="install-guide#install-guide"
   xlink:role="http://docbook.org/xlink/role/olink"
  ><citetitle>Installation Guide</citetitle></link>.
 </para>

 <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>

 <variablelist>
  <para>
   The following list uses the UNIX names for the commands.
   On Windows all command-line tools have the extension .bat.
  </para>

  <varlistentry>
   <term><link
    xlink:href="reference#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="reference#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="reference#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="reference#dbtest-1"
    xlink:role="http://docbook.org/xlink/role/olink">dbtest</link></term>
   <listitem>
    <para>
     Debug databases for <literal>local-db</literal> backends.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><link
    xlink:href="reference#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 command with the <option>--commandFilePath</option> option
     in interactive mode, then reading from the batch file
     with the <option>--batchFilePath</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>
     Alternatively, you can read commands from standard input
     by using the <option>--batch</option> option.
    </para>

    <para>
     In addition to the
     <link
      xlink:href="reference#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 that you can set
     with the <command>dsconfig</command> command.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><link
    xlink:href="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#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="reference#ldapsearch-1"
    xlink:role="http://docbook.org/xlink/role/olink">ldapsearch</link></term>
   <listitem>
    <para>
     Search a branch of directory data for entries
     that match the LDAP filter you specify.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><link
    xlink:href="reference#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="reference#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="reference#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="reference#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 directory server.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><link
    xlink:href="reference#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 generate test data that mimics data expected in production,
     but without compromising real, potentially private information.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><link
    xlink:href="reference#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="reference#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="reference#rebuild-index-1"
    xlink:role="http://docbook.org/xlink/role/olink">rebuild-index</link></term>
   <listitem>
    <para>
     Rebuild an index stored in an indexed backend.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><link
    xlink:href="reference#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="reference#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="reference#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="reference#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="reference#verify-index-1"
    xlink:role="http://docbook.org/xlink/role/olink">verify-index</link></term>
   <listitem>
    <para>
     Verify that an index stored in an indexed backend is not corrupt.
    </para>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term><link
    xlink:href="reference#windows-service"
    xlink:role="http://docbook.org/xlink/role/olink">windows-service</link>
   (Windows only)</term>
   <listitem>
    <para>
     Register OpenDJ as a Windows Service.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</section>

 opendj-sdk/opendj-server-legacy/src/main/docbkx/shared/sec-standard-schema.xml

New file
@@ -0,0 +1,307 @@
<?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.
  !
-->
 <section xml:id="standard-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">
 <title>Standard Schema Included With OpenDJ Server</title>

 <indexterm>
  <primary>Schema</primary>
  <secondary>Bundled definitions</secondary>
 </indexterm>

 <variablelist>
  <para>
   OpenDJ directory server provides many standard schema definitions
   in these LDIF files under <filename>/path/to/opendj/config/schema</filename>.
  </para>

  <varlistentry>
   <term>
    <filename>00-core.ldif</filename>
   </term>
   <listitem>
    <para>
     This file contains a core set of
     attribute type and object class definitions
     from the following Internet-Drafts, RFCs, and standards:
    </para>

    <simplelist columns="1">
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-ietf-boreham-numsubordinates"
      >draft-ietf-boreham-numsubordinates</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-findlay-ldap-groupofentries"
      >draft-findlay-ldap-groupofentries</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-furuseth-ldap-untypedobject"
      >draft-furuseth-ldap-untypedobject</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-good-ldap-changelog"
      >draft-good-ldap-changelog</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-ietf-ldup-subentry"
      >draft-ietf-ldup-subentry</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/draft-wahl-ldap-adminaddr"
      >draft-wahl-ldap-adminaddr</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc1274">RFC 1274</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc2079">RFC 2079</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc2256">RFC 2256</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc2798">RFC 2798</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3045">RFC 3045</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3296">RFC 3296</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3671">RFC 3671</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc3672">RFC 3672</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4512">RFC 4512</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4519">RFC 4519</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4523">RFC 4523</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4524">RFC 4524</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc4530">RFC 4530</member>
     <member xlink:show="new" xlink:href="https://tools.ietf.org/html/rfc5020">RFC 5020</member>
     <member xlink:show="new" xlink:href="https://www.itu.int/rec/T-REC-X.501">X.501</member>
    </simplelist>
   </listitem>
  </varlistentry>

  <varlistentry>
   <term>
    <filename>01-pwpolicy.ldif</filename>
   </term>
   <listitem>
    <para>
     This file contains schema definitions from
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/draft-behera-ldap-password-policy-09"
      >draft-behera-ldap-password-policy</link> (Draft 09),
     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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/draft-good-ldap-changelog"
      >draft-good-ldap-changelog</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc2713"
      >RFC 2713</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc2714"
      >RFC 2714</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc2739"
      >RFC 2739</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc2926"
      >RFC 2926</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc3112"
      >RFC 3112</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc3712"
      >RFC 3712</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc4403"
      >RFC 4403</link>, 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/draft-howard-rfc2307bis"
      >draft-howard-rfc2307bis</link>, which defines a mechanism
     for storing 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
     <link
      xlink:show="new"
      xlink:href="https://tools.ietf.org/html/rfc4876"
      >RFC 4876</link>, 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>