CR-2017 Fix for OPENDJ-1080: Unique Attributes: should document multiple types

Mark Craig

19.49.2013 abd4d82eb7225c3a2da236c56c420bf2d550f589

CR-2017 Fix for OPENDJ-1080: Unique Attributes: should document multiple types

 opends/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml

@@ -20,7 +20,7 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2012 ForgeRock AS
  !      Copyright 2011-2013 ForgeRock AS
  !    
-->
<chapter xml:id='chap-attribute-uniqueness'
@@ -51,9 +51,22 @@
 same, theoretically unique attribute value getting assigned to two different
 entries at once. You do not notice the problem until the network outage
 goes away and replication resumes.</para>
 
 <para>This chapter shows you how to set up attribute value uniqueness
 in your directory environment.</para>

 <itemizedlist>
  <para>This chapter shows you how to set up attribute value uniqueness
  in your directory environment with the following procedures.</para>

  <listitem><para><xref linkend="enable-unique-uids" /></para></listitem>
  <listitem><para><xref linkend="enable-unique-attributes" /></para></listitem>
  <listitem><para><xref linkend="unique-attributes-scoped" /></para></listitem>
  <listitem><para><xref linkend="unique-attributes-repl" /></para></listitem>
 </itemizedlist>

 <para>OpenDJ directory server uses the unique attribute plugin to handle
 attribute value uniqueness. As shown in the examples in this chapter, you
 can configure the unique attribute plugin to handle one or more attributes
 and to handle entries under one or more base DNs. You can also configure
 multiple instances of the plugin for the same OpenDJ directory server.</para>

 <procedure xml:id="enable-unique-uids">
  <title>To Enable Unique UIDs</title>
@@ -150,10 +163,52 @@
  
  <step>
   <para>Before you set up the plugin, index the attribute for equality.</para>

   <para>See <link xlink:show="new" xlink:href="admin-guide#configure-indexes"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring &amp;
   Rebuilding Indexes</citetitle></link> for instructions.</para>
  </step>
  <step>
   <para>Set up the plugin configuration for your attribute.</para>
   <screen>$ dsconfig

   <para>You can either add the attribute to an existing plugin configuration,
   or create a new plugin configuration including the attribute.</para>

   <para>When choosing between these alternatives, keep in mind that values
   must be unique across the attributes and base DNs specified in each
   plugin configuration. Therefore only group attributes together in the
   same configuration if you want each value to be unique for all
   attributes. For example, you might create a single plugin configuration
   for telephone, fax, mobile, and pager numbers. As an alternative
   example, suppose user IDs are numeric, that user entries also specify
   <literal>uidNumber</literal>, and that user IDs are normally the same as
   their <literal>uidNumber</literal>s. In that case you create separate
   unique attribute configurations for <literal>uid</literal> and
   <literal>uidNumber</literal>.</para>

   <stepalternatives>
    <step>
     <para>If you want to add the attribute to an existing plugin
     configuration, do so as shown in the following example which uses the
     plugin configuration from <xref linkend="enable-unique-uids" />.</para>

     <screen>$ dsconfig
 set-plugin-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --plugin-name "UID Unique Attribute"
 --add type:mobile
 --trustAll
 --no-prompt</screen>
    </step>

    <step>
     <para>If you want to create a new plugin configuration, do so as shown in
     the following example.</para>

     <screen>$ dsconfig
 create-plugin
 --port 4444
 --hostname opendj.example.com
@@ -166,6 +221,8 @@
 --set type:mobile
 --trustAll
 --no-prompt</screen>
    </step>
   </stepalternatives>
  </step>
  <step>
   <para>Check that the plugin is working correctly.</para>
@@ -196,7 +253,120 @@
 uid=ajensen,ou=People,dc=example,dc=com</screen>
  </step>
 </procedure>
 

 <procedure xml:id="unique-attributes-scoped">
  <title>To Limit The Scope of Uniqueness</title>

  <para>In some cases you need attribute uniqueness separately for different
  base DNs in your directory. For example, you need all <literal>uid</literal>
  values to remain unique both for users in <literal>dc=example,dc=com</literal>
  and <literal>dc=example,dc=org</literal>, but it is not a problem to have
  one entry under each base DN with the same user ID as the organizations are
  separate. The following steps demonstrate how to limit the scope of uniqueness
  by creating separate configuration entries for the unique attribute
  plugin.</para>

  <step>
   <para>If the attribute you target is not indexed for equality by default,
   index the attribute for equality.</para>

   <para>See <link xlink:show="new" xlink:href="admin-guide#configure-indexes"
   xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring &amp;
   Rebuilding Indexes</citetitle></link> for instructions.</para>

   <para>The examples in this procedure target the user ID attribute,
   <literal>uid</literal>, which is indexed for equality by default.</para>
  </step>

  <step>
   <para>For each base DN, set up a configuration entry that ensures the
   target attribute values are unique.</para>

   <screen>$ dsconfig
 create-plugin
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --plugin-name "Unique Example.com UIDs"
 --type unique-attribute
 --set enabled:true
 --set base-dn:dc=example,dc=com
 --set type:uid
 --trustAll
 --no-prompt
$ dsconfig
 create-plugin
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --plugin-name "Unique Example.org UIDs"
 --type unique-attribute
 --set enabled:true
 --set base-dn:dc=example,dc=org
 --set type:uid
 --trustAll
 --no-prompt</screen>
  </step>

  <step>
   <para>Check that the plugin is working correctly.</para>

   <screen>$ cat uniq-ids.ldif
dn: uid=unique,ou=People,dc=example,dc=com
uid: unique
givenName: Unique
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
cn: Unique Person
sn: Person
userPassword: 1Mun1qu3

dn: uid=unique,ou=People,dc=example,dc=org
uid: unique
givenName: Unique
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
cn: Unique Person
sn: Person
userPassword: 1Mun1qu3

dn: uid=copycat,ou=People,dc=example,dc=com
uid: unique
uid: copycat
givenName: Copycat
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
cn: Copycat Person
sn: Person
userPassword: copycopy

$ ldapmodify
 --defaultAdd
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename uniq-ids.ldif
Processing ADD request for uid=unique,ou=People,dc=example,dc=com
ADD operation successful for DN uid=unique,ou=People,dc=example,dc=com
Processing ADD request for uid=unique,ou=People,dc=example,dc=org
ADD operation successful for DN uid=unique,ou=People,dc=example,dc=org
Processing ADD request for uid=copycat,ou=People,dc=example,dc=com
ADD operation failed
Result Code:  19 (Constraint Violation)
Additional Information:  A unique attribute conflict was detected for
 attribute uid:  value unique already exists in entry
 uid=unique,ou=People,dc=example,dc=com</screen>
  </step>
 </procedure>

 <procedure xml:id="unique-attributes-repl">
  <title>To Ensure Unique Attribute Values With Replication</title>
  <indexterm>