external-software/github_OpenIdentityPlatform_OpenDJ.git

parent: 7970a420 | patch | commit | ignore whitespace

CR-6068 OPENDJ-1785 Add "extra" doc into code for generated content

Mark Craig

13.00.2015 3ef562d2eb067eb7dfdbd7cc355d9bbfd054f4d6

CR-6068 OPENDJ-1785 Add "extra" doc into code for generated content

This patch is like r11722, but for the LDAP SDK tools.

This patch does not resolve the fact that duplicate tools exist.
I have, however, logged OPENDJ-1810 regarding that point.
Duplication should disappear in the move to a single set of tools.

This is a subtask of the following issue:
OPENDJ-386 Move to single reference document

10 files modified

	opendj-sdk/opendj-cli/src/main/java/com/forgerock/opendj/cli/CommonArguments.java	7 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-cli/src/main/resources/com/forgerock/opendj/cli/cli.properties	83 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/AddRate.java	4 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/AuthRate.java	3 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/MakeLDIF.java	4 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/ModRate.java	3 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/SearchRate.java	3 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-ldap-toolkit/src/main/resources/com/forgerock/opendj/ldap/tools/tools.properties	187 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/opendj-server-legacy/src/main/docbkx/reference/man-ldapmodify.xml	40 ●●●●● patch \| view \| raw \| blame \| history
	opendj-sdk/src/main/docbkx/dev-guide/man-ldapmodify.xml	40 ●●●●● patch \| view \| raw \| blame \| history

 opendj-sdk/opendj-cli/src/main/java/com/forgerock/opendj/cli/CommonArguments.java

@@ -21,7 +21,7 @@
 * CDDL HEADER END
 *
 *
 *      Copyright 2014 ForgeRock AS
 *      Copyright 2014-2015 ForgeRock AS.
 */
package com.forgerock.opendj.cli;

@@ -186,9 +186,12 @@
     *             If there is a problem with any of the parameters used to create this argument.
     */
    public static StringArgument getControl() throws ArgumentException {
        return new StringArgument(OPTION_LONG_CONTROL.toLowerCase(), OPTION_SHORT_CONTROL, OPTION_LONG_CONTROL, false,
        StringArgument controlStr =
                new StringArgument(OPTION_LONG_CONTROL.toLowerCase(), OPTION_SHORT_CONTROL, OPTION_LONG_CONTROL, false,
                true, true, INFO_LDAP_CONTROL_PLACEHOLDER.get(), null, OPTION_LONG_CONTROL,
                INFO_DESCRIPTION_CONTROLS.get());
        controlStr.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_CONTROLS.get());
        return controlStr;
    }

    /**

 opendj-sdk/opendj-cli/src/main/resources/com/forgerock/opendj/cli/cli.properties

@@ -972,4 +972,85 @@
ERR_ERROR_CANNOT_READ_PASSWORD=Unable to read password
ERR_ERROR_CANNOT_READ_BIND_NAME=Unable to read bind name
ERR_ERROR_CANNOT_READ_HOST_NAME=Cannot read the host name
 

# Supplements to descriptions for generated reference documentation.
SUPPLEMENT_DESCRIPTION_CONTROLS=<para>                                             \
    For some <replaceable>controloid</replaceable> values,                         \
    you can replace object identifiers with user-friendly strings.                 \
                                                                                   \
    The strings are listed here in lower case, but the case is not important.      \
    You can use camelCase if you prefer, for example.                              \
   </para>                                                                         \
                                                                                   \
   <variablelist>                                                                  \
    <varlistentry>                                                                 \
     <term><literal>accountusable</literal></term>                                 \
     <term><literal>accountusability</literal></term>                              \
     <listitem>                                                                    \
      <para>Account Usability Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>authzid</literal></term>                                       \
     <term><literal>authorizationidentity</literal></term>                         \
     <listitem>                                                                    \
      <para>Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>effectiverights</literal></term>                               \
     <term><literal>geteffectiverights</literal></term>                            \
     <listitem>                                                                    \
      <para>Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>managedsait</literal></term>                                   \
     <listitem>                                                                    \
      <para>Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>noop</literal></term>                                          \
     <term><literal>no-op</literal></term>                                         \
     <listitem>                                                                    \
      <para>No-Op Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2</para>       \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>pwpolicy</literal></term>                                      \
     <term><literal>passwordpolicy</literal></term>                                \
     <listitem>                                                                    \
      <para>Password Policy Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>realattrsonly</literal></term>                                 \
     <term><literal>realattributesonly</literal></term>                            \
     <listitem>                                                                    \
      <para>Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>subtreedelete</literal></term>                                 \
     <term><literal>treedelete</literal></term>                                    \
     <listitem>                                                                    \
      <para>Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
                                                                                   \
    <varlistentry>                                                                 \
     <term><literal>virtualattrsonly</literal></term>                              \
     <term><literal>virtualattributesonly</literal></term>                         \
     <listitem>                                                                    \
      <para>Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19</para> \
     </listitem>                                                                   \
    </varlistentry>                                                                \
   </variablelist>

 opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/AddRate.java

@@ -21,7 +21,7 @@
 * CDDL HEADER END
 *
 *
 *      Copyright 2014-2015 ForgeRock AS
 *      Copyright 2014-2015 ForgeRock AS.
 */

package com.forgerock.opendj.ldap.tools;
@@ -416,6 +416,7 @@
        final LocalizableMessage toolDescription = INFO_ADDRATE_TOOL_DESCRIPTION.get();
        final ArgumentParser argParser =
            new ArgumentParser(AddRate.class.getName(), toolDescription, false, true, 1, 1, "template-file-path");
        argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RATE_TOOLS.get());

        final ConnectionFactoryProvider connectionFactoryProvider;
        final ConnectionFactory connectionFactory;
@@ -446,6 +447,7 @@
            resourcePathArg =
                new StringArgument("resourcepath", 'r', MakeLDIF.OPTION_LONG_RESOURCE_PATH, false, false, true,
                    INFO_PATH_PLACEHOLDER.get(), null, null, INFO_ADDRATE_DESCRIPTION_RESOURCE_PATH.get());
            resourcePathArg.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RESOURCE_PATH.get());
            argParser.addArgument(resourcePathArg);

            randomSeedArg =

 opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/AuthRate.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2010 Sun Microsystems, Inc.
 *      Portions Copyright 2011-2015 ForgeRock AS
 *      Portions Copyright 2011-2015 ForgeRock AS.
 */
package com.forgerock.opendj.ldap.tools;

@@ -391,6 +391,7 @@
        final ArgumentParser argParser =
                new ArgumentParser(AuthRate.class.getName(), toolDescription, false, true, 0, 0,
                        "[filter format string] [attributes ...]");
        argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RATE_TOOLS.get());

        ConnectionFactoryProvider connectionFactoryProvider;
        ConnectionFactory connectionFactory;

 opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/MakeLDIF.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2006-2010 Sun Microsystems, Inc.
 *      Portions Copyright 2013-2014 ForgeRock AS
 *      Portions Copyright 2013-2015 ForgeRock AS.
 */
package com.forgerock.opendj.ldap.tools;

@@ -87,6 +87,7 @@
        final LocalizableMessage toolDescription = INFO_MAKELDIF_TOOL_DESCRIPTION.get();
        final ArgumentParser argParser = new ArgumentParser(MakeLDIF.class.getName(), toolDescription,
                false, true, 1, 1, "template-file-path");
        argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_MAKELDIF.get());

        BooleanArgument showUsage;
        IntegerArgument randomSeed;
@@ -96,6 +97,7 @@
        try {
            resourcePath = new StringArgument("resourcepath", 'r', OPTION_LONG_RESOURCE_PATH, false, false, true,
                    INFO_PATH_PLACEHOLDER.get(), null, null, INFO_MAKELDIF_DESCRIPTION_RESOURCE_PATH.get());
            resourcePath.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RESOURCE_PATH.get());
            argParser.addArgument(resourcePath);

            ldifFile = new StringArgument("ldiffile", OPTION_SHORT_OUTPUT_LDIF_FILENAME,

 opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/ModRate.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2010 Sun Microsystems, Inc.
 *      Portions Copyright 2011-2015 ForgeRock AS
 *      Portions Copyright 2011-2015 ForgeRock AS.
 */
package com.forgerock.opendj.ldap.tools;

@@ -167,6 +167,7 @@
        final ArgumentParser argParser =
                new ArgumentParser(ModRate.class.getName(), toolDescription, false, true, 1, 0,
                        "[(attribute:value format string) ...]");
        argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RATE_TOOLS.get());
        ConnectionFactoryProvider connectionFactoryProvider;
        ConnectionFactory connectionFactory;
        ModifyPerformanceRunner runner;

 opendj-sdk/opendj-ldap-toolkit/src/main/java/com/forgerock/opendj/ldap/tools/SearchRate.java

@@ -22,7 +22,7 @@
 *
 *
 *      Copyright 2010 Sun Microsystems, Inc.
 *      Portions Copyright 2011-2015 ForgeRock AS
 *      Portions Copyright 2011-2015 ForgeRock AS.
 */
package com.forgerock.opendj.ldap.tools;

@@ -212,6 +212,7 @@
        final ArgumentParser argParser =
                new ArgumentParser(SearchRate.class.getName(), toolDescription, false, true, 1, 0,
                        "[filter format string] [attributes ...]");
        argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RATE_TOOLS.get());

        ConnectionFactoryProvider connectionFactoryProvider;
        ConnectionFactory connectionFactory;

 opendj-sdk/opendj-ldap-toolkit/src/main/resources/com/forgerock/opendj/ldap/tools/tools.properties

@@ -288,7 +288,9 @@
INFO_LDAPCOMPARE_TOOL_DESCRIPTION=This utility can be used to perform \
 LDAP compare operations in the Directory Server
INFO_LDAPMODIFY_TOOL_DESCRIPTION=This utility can be used to perform LDAP \
 modify, add, delete, and modify DN operations in the Directory Server
 modify, add, delete, and modify DN operations in the Directory Server. \
 When not using a file to specify modifications, end your input with EOF \
 (Ctrl+D on UNIX, Ctrl+Z on Windows)
INFO_LDAPPWMOD_TOOL_DESCRIPTION=This utility can be used to perform LDAP \
 password modify operations in the Directory Server
INFO_LDAPSEARCH_TOOL_DESCRIPTION=This utility can be used to perform LDAP \
@@ -439,13 +441,16 @@
  \ \ \ \ -F -c 4 -t 4 -b "dc=example,dc=com" -g "rand(0,2000)" "(uid=user.%%d)"
INFO_ADDRATE_TOOL_DESCRIPTION=This utility can be used to measure \
  add and optionally delete throughput and response time of a directory server using \
  user-defined entries.\n\
  user-defined entries. \
  The {template-file-path} argument identifies a template file \
  that has the same form as a template file for the makeldif command. \
  For details, see makeldif.template.\n\
  \nExamples:\n \  This example is adding entries and randomly deleting them while \
  the number of entries added is greater than 10,000: \n \
  addrate -p 1389 -f -c 10 -C random -s 10000 addrate.template \n \
  This example adds entries and starts to delete them in the same \
  order if their age is greater than a certain time: \n \
  addrate -p 1389 -f -c 10 -C fifo -a 2 addrate.template 
  addrate -p 1389 -f -c 10 -C fifo -a 2 addrate.template
INFO_SEARCHRATE_TOOL_DESCRIPTION_BASEDN=Base DN format string.
INFO_MODRATE_TOOL_DESCRIPTION=This utility can be used to measure \
  modify throughput and response time of a directory service using \
@@ -549,6 +554,182 @@
INFO_ADDRATE_DESCRIPTION_NOPURGE=Disable the purge phase when the tool stops.

# Supplements to descriptions for generated reference documentation.
SUPPLEMENT_DESCRIPTION_RATE_TOOLS=<para>                                         \
    When you do not use the <option>-f</option> option                           \
    to keep connections open and rebind on the connections,                      \
    the tool can exhaust the available ports and crash.                          \
    You can work around this problem on test systems                             \
    by changing TCP settings on the system.                                      \
   </para>                                                                       \
                                                                                 \
   <para>                                                                        \
    For example on Linux systems, set the following parameters                   \
    in the <filename>/etc/sysctl.conf</filename> file.                           \
   </para>                                                                       \
                                                                                 \
   <programlisting language="ini">                                               \
  net.ipv4.tcp_fin_timeout = 30                                                  \
  net.ipv4.tcp_tw_recycle = 1                                                    \
  net.ipv4.tcp_tw_reuse = 1                                                      \
   </programlisting>                                                             \
                                                                                 \
   <para>                                                                        \
    The parameter <literal>net.ipv4.tcp_fin_timeout</literal>                    \
    sets how long to wait in seconds for a final FIN packet                      \
    before forcing a close of the socket.                                        \
    The default is 60 (seconds).                                                 \
   </para>                                                                       \
                                                                                 \
   <para>                                                                        \
    The parameter <literal>net.ipv4.tcp_tw_recycle</literal>                     \
    enables fast recycling of TIME_WAIT sockets.                                 \
    The default is 0 (false).                                                    \
    Enabling this can cause Network Address Translation (NAT) issues.            \
   </para>                                                                       \
                                                                                 \
   <para>                                                                        \
    The parameter <literal>net.ipv4.tcp_tw_reuse</literal>                       \
    enables reuse of TIME_WAIT sockets for new connections.                      \
    The default is 0 (false).                                                    \
   </para>                                                                       \
                                                                                 \
   <para>                                                                        \
    These settings are recommended only for testing,                             \
    and <emphasis>not for production systems</emphasis>.                         \
   </para>                                                                       \
                                                                                 \
   <para>                                                                        \
    After making the changes to <filename>/etc/sysctl.conf</filename>,           \
    reload the configuration with the <command>sysctl</command> command.         \
   </para>                                                                       \
                                                                                 \
   <screen>                                                                      \
  # sysctl -p                                                                    \
   </screen>
SUPPLEMENT_DESCRIPTION_MAKELDIF=<para>                                       \
   The <replaceable>template-file-path</replaceable> can be                  \
   one of the following:                                                     \
  </para>                                                                    \
                                                                             \
  <itemizedlist>                                                             \
   <listitem>                                                                \
    <para>                                                                   \
     A full path to the template file such as                                \
     <filename>/path/to/opendj/config/MakeLDIF/example.template</filename>.  \
    </para>                                                                  \
   </listitem>                                                               \
                                                                             \
   <listitem>                                                                \
    <para>                                                                   \
     A relative path to the template file such as                            \
     <filename>../../my-test-data.template</filename>.                       \
    </para>                                                                  \
   </listitem>                                                               \
                                                                             \
   <listitem>                                                                \
    <para>                                                                   \
     A file name that specifies one of the template files                    \
     that are built into the OpenDJ LDAP Toolkit,                            \
     such as <filename>example.template</filename>,                          \
     or <filename>people_and_groups.template</filename>.                     \
    </para>                                                                  \
   </listitem>                                                               \
  </itemizedlist>                                                            \
                                                                             \
  <para>                                                                     \
   The OpenDJ LDAP Toolkit includes these built-in template and data files:  \
  </para>                                                                    \
                                                                             \
  <variablelist>                                                             \
   <varlistentry>                                                            \
    <term><filename>cities</filename></term>                                 \
    <listitem>                                                               \
     <para>                                                                  \
      List of more than 200 cities.                                          \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
                                                                             \
   <varlistentry>                                                            \
    <term><filename>example.template</filename></term>                       \
    <listitem>                                                               \
     <para>                                                                  \
      Template to generate a base entry and users                            \
      in a branch <literal>ou=people,[suffix]</literal>,                     \
      where the default setting for suffix is                                \
      <literal>suffix=dc=example,dc=com</literal>.                           \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
                                                                             \
   <varlistentry>                                                            \
    <term><filename>first.names</filename></term>                            \
    <listitem>                                                               \
     <para>                                                                  \
      List of more than 8000 first names.                                    \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
                                                                             \
   <varlistentry>                                                            \
    <term><filename>last.names</filename></term>                             \
    <listitem>                                                               \
     <para>                                                                  \
      List of more than 13000 last names.                                    \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
                                                                             \
   <varlistentry>                                                            \
    <term><filename>people_and_groups.template</filename></term>             \
    <listitem>                                                               \
     <para>                                                                  \
      Template to generate a base entry, users, and groups.                  \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
                                                                             \
   <varlistentry>                                                            \
    <term><filename>states</filename></term>                                 \
    <listitem>                                                               \
     <para>                                                                  \
      List of US states by their two-character codes.                        \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
                                                                             \
   <varlistentry>                                                            \
    <term><filename>streets</filename></term>                                \
    <listitem>                                                               \
     <para>                                                                  \
      List of more than 70 street names.                                     \
     </para>                                                                 \
    </listitem>                                                              \
   </varlistentry>                                                           \
  </variablelist>
SUPPLEMENT_DESCRIPTION_RESOURCE_PATH=<para>                          \
      The utility looks for resources in the following locations in this order:\
     </para>                                                                  \
                                                                              \
     <orderedlist>                                                            \
      <listitem>                                                              \
       <para>                                                                 \
        The current directory where the command is run.                       \
       </para>                                                                \
      </listitem>                                                             \
                                                                              \
      <listitem>                                                              \
       <para>                                                                 \
        The resource path directory.                                          \
       </para>                                                                \
      </listitem>                                                             \
                                                                              \
      <listitem>                                                              \
       <para>                                                                 \
        The built-in files.                                                   \
       </para>                                                                \
      </listitem>                                                             \
     </orderedlist>
SUPPLEMENT_DESCRIPTION_PSEARCH_INFO=<para>                                         \
      A persistent search allows the client to continue receiving new results      \
      whenever changes are made to data that is in the scope of the search,        \

 opendj-sdk/opendj-server-legacy/src/main/docbkx/reference/man-ldapmodify.xml

@@ -20,7 +20,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<refentry xml:id='ldapmodify-1'
@@ -30,7 +30,7 @@
 xsi:schemaLocation='http://docbook.org/ns/docbook
                     http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'>
 <info><copyright><year>2011-2014</year><holder>ForgeRock AS</holder></copyright></info>
 <info><copyright><year>2011-2015</year><holder>ForgeRock AS.</holder></copyright></info>
 <refmeta>
  <refentrytitle>ldapmodify</refentrytitle><manvolnum>1</manvolnum>
  <refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -371,6 +371,42 @@
ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</computeroutput>
  </screen>

  <para>
   The following listing shows a UNIX shell script that adds a user entry.
  </para>

  <programlisting language="shell">
#!/bin/sh
#
# Add a new user with the ldapmodify utility.
#

usage(){
        echo "Usage: $0 uid firstname lastname"
        exit 1
}
[[ $# -lt 3 ]] &amp;&amp; usage

LDAPMODIFY=/path/to/opendj/bin/ldapmodify
HOST=opendj.example.com
PORT=1389
ADMIN=uid=kvaughan,ou=people,dc=example,dc=com
PWD=bribery

$LDAPMODIFY -h $HOST -p $PORT -D $ADMIN -w $PWD -a &lt;&lt;EOF
dn: uid=$1,ou=people,dc=example,dc=com
uid: $1
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: $2 $3
givenName: $2
sn: $3
mail: $1@example.com
EOF
  </programlisting>

 <para>The following example demonstrates adding a Description attribute
 to the new user's entry.</para>


 opendj-sdk/src/main/docbkx/dev-guide/man-ldapmodify.xml

@@ -20,7 +20,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2014 ForgeRock AS
  !      Copyright 2011-2015 ForgeRock AS.
  !    
-->
<refentry xml:id='ldapmodify-1'
@@ -30,7 +30,7 @@
 xsi:schemaLocation='http://docbook.org/ns/docbook
                     http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'>
 <info><copyright><year>2011-2014</year><holder>ForgeRock AS</holder></copyright></info>
 <info><copyright><year>2011-2015</year><holder>ForgeRock AS.</holder></copyright></info>
 <refmeta>
  <refentrytitle>ldapmodify</refentrytitle><manvolnum>1</manvolnum>
  <refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -364,6 +364,42 @@
ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</computeroutput>
  </screen>

  <para>
   The following listing shows a UNIX shell script that adds a user entry.
  </para>

  <programlisting language="shell">
#!/bin/sh
#
# Add a new user with the ldapmodify utility.
#

usage(){
        echo "Usage: $0 uid firstname lastname"
        exit 1
}
[[ $# -lt 3 ]] &amp;&amp; usage

LDAPMODIFY=/path/to/opendj/bin/ldapmodify
HOST=opendj.example.com
PORT=1389
ADMIN=uid=kvaughan,ou=people,dc=example,dc=com
PWD=bribery

$LDAPMODIFY -h $HOST -p $PORT -D $ADMIN -w $PWD -a &lt;&lt;EOF
dn: uid=$1,ou=people,dc=example,dc=com
uid: $1
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: $2 $3
givenName: $2
sn: $3
mail: $1@example.com
EOF
  </programlisting>

 <para>The following example demonstrates adding a Description attribute
 to the new user's entry.</para>

			@@ -21,7 +21,7 @@
			* CDDL HEADER END
			*
			*
			* Copyright 2014 ForgeRock AS
			* Copyright 2014-2015 ForgeRock AS.
			*/
			package com.forgerock.opendj.cli;

			@@ -186,9 +186,12 @@
			* If there is a problem with any of the parameters used to create this argument.
			*/
			public static StringArgument getControl() throws ArgumentException {
			return new StringArgument(OPTION_LONG_CONTROL.toLowerCase(), OPTION_SHORT_CONTROL, OPTION_LONG_CONTROL, false,
			StringArgument controlStr =
			new StringArgument(OPTION_LONG_CONTROL.toLowerCase(), OPTION_SHORT_CONTROL, OPTION_LONG_CONTROL, false,
			true, true, INFO_LDAP_CONTROL_PLACEHOLDER.get(), null, OPTION_LONG_CONTROL,
			INFO_DESCRIPTION_CONTROLS.get());
			controlStr.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_CONTROLS.get());
			return controlStr;
			}

			/**

			@@ -972,4 +972,85 @@
			ERR_ERROR_CANNOT_READ_PASSWORD=Unable to read password
			ERR_ERROR_CANNOT_READ_BIND_NAME=Unable to read bind name
			ERR_ERROR_CANNOT_READ_HOST_NAME=Cannot read the host name


			# Supplements to descriptions for generated reference documentation.
			SUPPLEMENT_DESCRIPTION_CONTROLS=<para> \
			For some <replaceable>controloid</replaceable> values, \
			you can replace object identifiers with user-friendly strings. \
			\
			The strings are listed here in lower case, but the case is not important. \
			You can use camelCase if you prefer, for example. \
			</para> \
			\
			<variablelist> \
			<varlistentry> \
			<term><literal>accountusable</literal></term> \
			<term><literal>accountusability</literal></term> \
			<listitem> \
			<para>Account Usability Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>authzid</literal></term> \
			<term><literal>authorizationidentity</literal></term> \
			<listitem> \
			<para>Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>effectiverights</literal></term> \
			<term><literal>geteffectiverights</literal></term> \
			<listitem> \
			<para>Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>managedsait</literal></term> \
			<listitem> \
			<para>Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>noop</literal></term> \
			<term><literal>no-op</literal></term> \
			<listitem> \
			<para>No-Op Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>pwpolicy</literal></term> \
			<term><literal>passwordpolicy</literal></term> \
			<listitem> \
			<para>Password Policy Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>realattrsonly</literal></term> \
			<term><literal>realattributesonly</literal></term> \
			<listitem> \
			<para>Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>subtreedelete</literal></term> \
			<term><literal>treedelete</literal></term> \
			<listitem> \
			<para>Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><literal>virtualattrsonly</literal></term> \
			<term><literal>virtualattributesonly</literal></term> \
			<listitem> \
			<para>Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19</para> \
			</listitem> \
			</varlistentry> \
			</variablelist>

			@@ -21,7 +21,7 @@
			* CDDL HEADER END
			*
			*
			* Copyright 2014-2015 ForgeRock AS
			* Copyright 2014-2015 ForgeRock AS.
			*/

			package com.forgerock.opendj.ldap.tools;
			@@ -416,6 +416,7 @@
			final LocalizableMessage toolDescription = INFO_ADDRATE_TOOL_DESCRIPTION.get();
			final ArgumentParser argParser =
			new ArgumentParser(AddRate.class.getName(), toolDescription, false, true, 1, 1, "template-file-path");
			argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RATE_TOOLS.get());

			final ConnectionFactoryProvider connectionFactoryProvider;
			final ConnectionFactory connectionFactory;
			@@ -446,6 +447,7 @@
			resourcePathArg =
			new StringArgument("resourcepath", 'r', MakeLDIF.OPTION_LONG_RESOURCE_PATH, false, false, true,
			INFO_PATH_PLACEHOLDER.get(), null, null, INFO_ADDRATE_DESCRIPTION_RESOURCE_PATH.get());
			resourcePathArg.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RESOURCE_PATH.get());
			argParser.addArgument(resourcePathArg);

			randomSeedArg =

			@@ -22,7 +22,7 @@
			*
			*
			* Copyright 2010 Sun Microsystems, Inc.
			* Portions Copyright 2011-2015 ForgeRock AS
			* Portions Copyright 2011-2015 ForgeRock AS.
			*/
			package com.forgerock.opendj.ldap.tools;

			@@ -391,6 +391,7 @@
			final ArgumentParser argParser =
			new ArgumentParser(AuthRate.class.getName(), toolDescription, false, true, 0, 0,
			"[filter format string] [attributes ...]");
			argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RATE_TOOLS.get());

			ConnectionFactoryProvider connectionFactoryProvider;
			ConnectionFactory connectionFactory;

			@@ -22,7 +22,7 @@
			*
			*
			* Copyright 2006-2010 Sun Microsystems, Inc.
			* Portions Copyright 2013-2014 ForgeRock AS
			* Portions Copyright 2013-2015 ForgeRock AS.
			*/
			package com.forgerock.opendj.ldap.tools;

			@@ -87,6 +87,7 @@
			final LocalizableMessage toolDescription = INFO_MAKELDIF_TOOL_DESCRIPTION.get();
			final ArgumentParser argParser = new ArgumentParser(MakeLDIF.class.getName(), toolDescription,
			false, true, 1, 1, "template-file-path");
			argParser.setDocToolDescriptionSupplement(SUPPLEMENT_DESCRIPTION_MAKELDIF.get());

			BooleanArgument showUsage;
			IntegerArgument randomSeed;
			@@ -96,6 +97,7 @@
			try {
			resourcePath = new StringArgument("resourcepath", 'r', OPTION_LONG_RESOURCE_PATH, false, false, true,
			INFO_PATH_PLACEHOLDER.get(), null, null, INFO_MAKELDIF_DESCRIPTION_RESOURCE_PATH.get());
			resourcePath.setDocDescriptionSupplement(SUPPLEMENT_DESCRIPTION_RESOURCE_PATH.get());
			argParser.addArgument(resourcePath);

			ldifFile = new StringArgument("ldiffile", OPTION_SHORT_OUTPUT_LDIF_FILENAME,

			@@ -288,7 +288,9 @@
			INFO_LDAPCOMPARE_TOOL_DESCRIPTION=This utility can be used to perform \
			LDAP compare operations in the Directory Server
			INFO_LDAPMODIFY_TOOL_DESCRIPTION=This utility can be used to perform LDAP \
			modify, add, delete, and modify DN operations in the Directory Server
			modify, add, delete, and modify DN operations in the Directory Server. \
			When not using a file to specify modifications, end your input with EOF \
			(Ctrl+D on UNIX, Ctrl+Z on Windows)
			INFO_LDAPPWMOD_TOOL_DESCRIPTION=This utility can be used to perform LDAP \
			password modify operations in the Directory Server
			INFO_LDAPSEARCH_TOOL_DESCRIPTION=This utility can be used to perform LDAP \
			@@ -439,13 +441,16 @@
			\ \ \ \ -F -c 4 -t 4 -b "dc=example,dc=com" -g "rand(0,2000)" "(uid=user.%%d)"
			INFO_ADDRATE_TOOL_DESCRIPTION=This utility can be used to measure \
			add and optionally delete throughput and response time of a directory server using \
			user-defined entries.\n\
			user-defined entries. \
			The {template-file-path} argument identifies a template file \
			that has the same form as a template file for the makeldif command. \
			For details, see makeldif.template.\n\
			\nExamples:\n \ This example is adding entries and randomly deleting them while \
			the number of entries added is greater than 10,000: \n \
			addrate -p 1389 -f -c 10 -C random -s 10000 addrate.template \n \
			This example adds entries and starts to delete them in the same \
			order if their age is greater than a certain time: \n \
			addrate -p 1389 -f -c 10 -C fifo -a 2 addrate.template
			addrate -p 1389 -f -c 10 -C fifo -a 2 addrate.template
			INFO_SEARCHRATE_TOOL_DESCRIPTION_BASEDN=Base DN format string.
			INFO_MODRATE_TOOL_DESCRIPTION=This utility can be used to measure \
			modify throughput and response time of a directory service using \
			@@ -549,6 +554,182 @@
			INFO_ADDRATE_DESCRIPTION_NOPURGE=Disable the purge phase when the tool stops.

			# Supplements to descriptions for generated reference documentation.
			SUPPLEMENT_DESCRIPTION_RATE_TOOLS=<para> \
			When you do not use the <option>-f</option> option \
			to keep connections open and rebind on the connections, \
			the tool can exhaust the available ports and crash. \
			You can work around this problem on test systems \
			by changing TCP settings on the system. \
			</para> \
			\
			<para> \
			For example on Linux systems, set the following parameters \
			in the <filename>/etc/sysctl.conf</filename> file. \
			</para> \
			\
			<programlisting language="ini"> \
			net.ipv4.tcp_fin_timeout = 30 \
			net.ipv4.tcp_tw_recycle = 1 \
			net.ipv4.tcp_tw_reuse = 1 \
			</programlisting> \
			\
			<para> \
			The parameter <literal>net.ipv4.tcp_fin_timeout</literal> \
			sets how long to wait in seconds for a final FIN packet \
			before forcing a close of the socket. \
			The default is 60 (seconds). \
			</para> \
			\
			<para> \
			The parameter <literal>net.ipv4.tcp_tw_recycle</literal> \
			enables fast recycling of TIME_WAIT sockets. \
			The default is 0 (false). \
			Enabling this can cause Network Address Translation (NAT) issues. \
			</para> \
			\
			<para> \
			The parameter <literal>net.ipv4.tcp_tw_reuse</literal> \
			enables reuse of TIME_WAIT sockets for new connections. \
			The default is 0 (false). \
			</para> \
			\
			<para> \
			These settings are recommended only for testing, \
			and <emphasis>not for production systems</emphasis>. \
			</para> \
			\
			<para> \
			After making the changes to <filename>/etc/sysctl.conf</filename>, \
			reload the configuration with the <command>sysctl</command> command. \
			</para> \
			\
			<screen> \
			# sysctl -p \
			</screen>
			SUPPLEMENT_DESCRIPTION_MAKELDIF=<para> \
			The <replaceable>template-file-path</replaceable> can be \
			one of the following: \
			</para> \
			\
			<itemizedlist> \
			<listitem> \
			<para> \
			A full path to the template file such as \
			<filename>/path/to/opendj/config/MakeLDIF/example.template</filename>. \
			</para> \
			</listitem> \
			\
			<listitem> \
			<para> \
			A relative path to the template file such as \
			<filename>../../my-test-data.template</filename>. \
			</para> \
			</listitem> \
			\
			<listitem> \
			<para> \
			A file name that specifies one of the template files \
			that are built into the OpenDJ LDAP Toolkit, \
			such as <filename>example.template</filename>, \
			or <filename>people_and_groups.template</filename>. \
			</para> \
			</listitem> \
			</itemizedlist> \
			\
			<para> \
			The OpenDJ LDAP Toolkit includes these built-in template and data files: \
			</para> \
			\
			<variablelist> \
			<varlistentry> \
			<term><filename>cities</filename></term> \
			<listitem> \
			<para> \
			List of more than 200 cities. \
			</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><filename>example.template</filename></term> \
			<listitem> \
			<para> \
			Template to generate a base entry and users \
			in a branch <literal>ou=people,[suffix]</literal>, \
			where the default setting for suffix is \
			<literal>suffix=dc=example,dc=com</literal>. \
			</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><filename>first.names</filename></term> \
			<listitem> \
			<para> \
			List of more than 8000 first names. \
			</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><filename>last.names</filename></term> \
			<listitem> \
			<para> \
			List of more than 13000 last names. \
			</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><filename>people_and_groups.template</filename></term> \
			<listitem> \
			<para> \
			Template to generate a base entry, users, and groups. \
			</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><filename>states</filename></term> \
			<listitem> \
			<para> \
			List of US states by their two-character codes. \
			</para> \
			</listitem> \
			</varlistentry> \
			\
			<varlistentry> \
			<term><filename>streets</filename></term> \
			<listitem> \
			<para> \
			List of more than 70 street names. \
			</para> \
			</listitem> \
			</varlistentry> \
			</variablelist>
			SUPPLEMENT_DESCRIPTION_RESOURCE_PATH=<para> \
			The utility looks for resources in the following locations in this order:\
			</para> \
			\
			<orderedlist> \
			<listitem> \
			<para> \
			The current directory where the command is run. \
			</para> \
			</listitem> \
			\
			<listitem> \
			<para> \
			The resource path directory. \
			</para> \
			</listitem> \
			\
			<listitem> \
			<para> \
			The built-in files. \
			</para> \
			</listitem> \
			</orderedlist>
			SUPPLEMENT_DESCRIPTION_PSEARCH_INFO=<para> \
			A persistent search allows the client to continue receiving new results \
			whenever changes are made to data that is in the scope of the search, \

			@@ -20,7 +20,7 @@
			!
			! CCPL HEADER END
			!
			! Copyright 2011-2014 ForgeRock AS
			! Copyright 2011-2015 ForgeRock AS.
			!
			-->
			<refentry xml:id='ldapmodify-1'
			@@ -30,7 +30,7 @@
			xsi:schemaLocation='http://docbook.org/ns/docbook
			http://docbook.org/xml/5.0/xsd/docbook.xsd'
			xmlns:xlink='http://www.w3.org/1999/xlink'>
			<info><copyright><year>2011-2014</year><holder>ForgeRock AS</holder></copyright></info>
			<info><copyright><year>2011-2015</year><holder>ForgeRock AS.</holder></copyright></info>
			<refmeta>
			<refentrytitle>ldapmodify</refentrytitle><manvolnum>1</manvolnum>
			<refmiscinfo class="software">OpenDJ</refmiscinfo>
			@@ -371,6 +371,42 @@
			ADD operation successful for DN uid=newuser,ou=People,dc=example,dc=com</computeroutput>
			</screen>

			<para>
			The following listing shows a UNIX shell script that adds a user entry.
			</para>

			<programlisting language="shell">
			#!/bin/sh
			#
			# Add a new user with the ldapmodify utility.
			#

			usage(){
			echo "Usage: $0 uid firstname lastname"
			exit 1
			}
			[[ $# -lt 3 ]] && usage

			LDAPMODIFY=/path/to/opendj/bin/ldapmodify
			HOST=opendj.example.com
			PORT=1389
			ADMIN=uid=kvaughan,ou=people,dc=example,dc=com
			PWD=bribery

			$LDAPMODIFY -h $HOST -p $PORT -D $ADMIN -w $PWD -a <<EOF
			dn: uid=$1,ou=people,dc=example,dc=com
			uid: $1
			objectClass: top
			objectClass: person
			objectClass: organizationalPerson
			objectClass: inetOrgPerson
			cn: $2 $3
			givenName: $2
			sn: $3
			mail: $1@example.com
			EOF
			</programlisting>

			<para>The following example demonstrates adding a Description attribute
			to the new user's entry.</para>