From 13bf89a1dceead2657056a320c4ccba06514cdf5 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 19 Jul 2013 10:49:14 +0000
Subject: [PATCH] CR-2017 Fix for OPENDJ-1080: Unique Attributes: should document multiple types
---
opendj-sdk/opends/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml | 182 ++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 176 insertions(+), 6 deletions(-)
diff --git a/opendj-sdk/opends/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml b/opendj-sdk/opends/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml
index 64d37ae..d8c7ea3 100644
--- a/opendj-sdk/opends/src/main/docbkx/admin-guide/chap-attribute-uniqueness.xml
+++ b/opendj-sdk/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 &
+ 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 &
+ 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>
--
Gitblit v1.10.0