Backport CR-3283 Fix for Server docs patch for OPENDJ-980: Allow copy/ past...

Mark Craig

31.17.2014 ae57abea41b1a1c805fee27ffcfeabc0ae07e969

 opends/src/main/docbkx/admin-guide/chap-groups.xml

@@ -20,15 +20,15 @@
  !
  ! CCPL HEADER END
  !
  !      Copyright 2011-2013 ForgeRock AS
  !      Copyright 2011-2014 ForgeRock AS
  !    
-->
<chapter xml:id='chap-groups'
 xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
 xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 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.
@@ -52,18 +52,20 @@
  generated data during setup and did not create an organizational unit for
  groups yet, create the entry before you try the examples.</para>

  <screen>$ ldapmodify
 --defaultAdd
 --port 1389
 --bindDN "cn=Directory Manager"
  <screen>
$ <userinput>ldapmodify \
 --defaultAdd \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password
dn: ou=Groups,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: Groups

Processing ADD request for ou=Groups,dc=example,dc=com
ADD operation successful for DN ou=Groups,dc=example,dc=com</screen>
</userinput>
<computeroutput>Processing ADD request for ou=Groups,dc=example,dc=com
ADD operation successful for DN ou=Groups,dc=example,dc=com</computeroutput>
  </screen>
 </tip>

 <section xml:id="static-groups">
@@ -102,8 +104,9 @@
  <para>To create a static group, add a group entry such as the following
  to the directory.</para>

  <screen>$ cat static.ldif 
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
  <screen>
$ <userinput>cat static.ldif</userinput>
<computeroutput>dn: cn=My Static Group,ou=Groups,dc=example,dc=com
cn: My Static Group
objectClass: groupOfNames
objectClass: top
@@ -111,38 +114,43 @@
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
</computeroutput>

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename static.ldif 
Processing ADD request for cn=My Static Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=My Static Group,ou=Groups,dc=example,dc=com</screen>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --defaultAdd \
 --filename static.ldif</userinput>
<computeroutput>Processing ADD request for cn=My Static Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=My Static Group,ou=Groups,dc=example,dc=com</computeroutput>
  </screen>
  
  <para>To change group membership, modify the values of the membership
  attribute.</para>
  
  <screen>$ cat add2grp.ldif 
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
  <screen>
$ <userinput>cat add2grp.ldif</userinput>
<computeroutput>dn: cn=My Static Group,ou=Groups,dc=example,dc=com
changetype: modify
add: member
member: uid=scarter,ou=People,dc=example,dc=com
</computeroutput>

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename add2grp.ldif 
Processing MODIFY request for cn=My Static Group,ou=Groups,dc=example,dc=com
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --filename add2grp.ldif</userinput>
<computeroutput>Processing MODIFY request for cn=My Static Group,ou=Groups,dc=example,dc=com
MODIFY operation successful for DN
 cn=My Static Group,ou=Groups,dc=example,dc=com
$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(cn=My Static Group)"
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
</computeroutput>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 "(cn=My Static Group)"</userinput>
<computeroutput>dn: cn=My Static Group,ou=Groups,dc=example,dc=com
ou: Groups
objectClass: groupOfNames
objectClass: top
@@ -150,7 +158,8 @@
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
member: uid=scarter,ou=People,dc=example,dc=com
cn: My Static Group</screen>
cn: My Static Group</computeroutput>
  </screen>

  <para>RFC 4519 says a <literal>groupOfNames</literal> entry must have
  at least one member. Although OpenDJ allows you to create a
@@ -159,25 +168,27 @@
  <literal>groupOfEntries</literal> object class as shown in the following
  example.</para>

  <screen>$ cat group-of-entries.ldif
dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
  <screen>
$ <userinput>cat group-of-entries.ldif</userinput>
<computeroutput>dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
cn: Initially Empty Static Group
objectClass: groupOfEntries
objectClass: top
ou: Groups

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename group-of-entries.ldif
Processing ADD request for
</computeroutput>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --defaultAdd \
 --filename group-of-entries.ldif</userinput>
<computeroutput>Processing ADD request for
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
$ cat add-members.ldif
# Now add some members to the group.
</computeroutput>
$ <userinput>cat add-members.ldif</userinput>
<computeroutput># Now add some members to the group.
dn: cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
changetype: modify
add: member
@@ -185,16 +196,17 @@
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com
member: uid=scarter,ou=People,dc=example,dc=com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --filename add-members.ldif
Processing MODIFY request for
</computeroutput>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --filename add-members.ldif</userinput>
<computeroutput>Processing MODIFY request for
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com
MODIFY operation successful for DN
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com</screen>
 cn=Initially Empty Static Group,ou=Groups,dc=example,dc=com</computeroutput>
  </screen>
 </section>

 <section xml:id="dynamic-groups">
@@ -220,62 +232,66 @@
  is Cupertino). Change the filter if your data is different, and so no
  entries have <literal>l: Cupertino</literal>.</para>

  <screen>$ cat dynamic.ldif
dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
  <screen>
$ <userinput>cat dynamic.ldif</userinput>
<computeroutput>dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
cn: My Dynamic Group
objectClass: top
objectClass: groupOfURLs
ou: Groups
memberURL: ldap:///ou=People,dc=example,dc=com??sub?l=Cupertino

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename dynamic.ldif 
Processing ADD request for cn=My Dynamic Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=My Dynamic Group,ou=Groups,dc=example,dc=com</screen>
</computeroutput>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --defaultAdd \
 --filename dynamic.ldif</userinput>
<computeroutput>Processing ADD request for cn=My Dynamic Group,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=My Dynamic Group,ou=Groups,dc=example,dc=com</computeroutput>
  </screen>
  
  <para>Group membership changes dynamically as entries change to match the
  <literal>memberURL</literal> values.</para>
  
  <screen>$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(&amp;(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))"
 mail
dn: uid=bjensen,ou=People,dc=example,dc=com
  <screen width="81">
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 "(&amp;(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))" \
 mail</userinput>
<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

dn: uid=rjensen,ou=People,dc=example,dc=com
mail: rjensen@example.com

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
dn: uid=ajensen,ou=People,dc=example,dc=com
</computeroutput>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password</userinput>
<computeroutput>dn: uid=ajensen,ou=People,dc=example,dc=com
changetype: modify
replace: l
l: Cupertino

Processing MODIFY request for uid=ajensen,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=ajensen,ou=People,dc=example,dc=com
^D
$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 "(&amp;(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))"
 mail
dn: uid=ajensen,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=ajensen,ou=People,dc=example,dc=com</computeroutput>
<userinput>^D</userinput>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 "(&amp;(uid=*jensen)(isMemberOf=cn=My Dynamic Group,ou=Groups,dc=example,dc=com))" \
 mail</userinput>
<computeroutput>dn: uid=ajensen,ou=People,dc=example,dc=com
mail: ajensen@example.com

dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com

dn: uid=rjensen,ou=People,dc=example,dc=com
mail: rjensen@example.com</screen>
mail: rjensen@example.com</computeroutput>
  </screen>
 </section>

 <section xml:id="virtual-static-groups">
@@ -303,38 +319,42 @@
  <literal>Virtual Static member</literal> or
  <literal>Virtual Static uniqueMember</literal> property.</para>
  
  <screen>$ dsconfig
 set-virtual-attribute-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --name "Virtual Static member"
 --set allow-retrieving-membership:true
 --trustAll
 --no-prompt</screen>
  <screen>
$ <userinput>dsconfig \
 set-virtual-attribute-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --name "Virtual Static member" \
 --set allow-retrieving-membership:true \
 --trustAll \
 --no-prompt</userinput>
  </screen>
  
  <para>The following example creates a virtual static group, and reads the
  group entry with all members.</para>
  
  <screen>$ cat virtual.ldif 
dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
  <screen>
$ <userinput>cat virtual.ldif</userinput>
<computeroutput>dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
cn: Virtual Static
objectclass: top
objectclass: groupOfNames
objectclass: ds-virtual-static-group
ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com
</computeroutput>
$ <userinput>ldapmodify \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --defaultAdd \
 --filename virtual.ldif</userinput>
<computeroutput>Processing ADD request for cn=Virtual Static,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=Virtual Static,ou=Groups,dc=example,dc=com</computeroutput>

$ ldapmodify
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --defaultAdd
 --filename virtual.ldif
Processing ADD request for cn=Virtual Static,ou=Groups,dc=example,dc=com
ADD operation successful for DN cn=Virtual Static,ou=Groups,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Virtual Static)"
dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Virtual Static)"</userinput>
<computeroutput>dn: cn=Virtual Static,ou=Groups,dc=example,dc=com
objectClass: groupOfNames
objectClass: ds-virtual-static-group
objectClass: top
@@ -374,7 +394,8 @@
member: uid=abergin,ou=People,dc=example,dc=com
member: uid=mschneid,ou=People,dc=example,dc=com
cn: Virtual Static
ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com</screen>
ds-target-group-dn: cn=My Dynamic Group,ou=Groups,dc=example,dc=com</computeroutput>
  </screen>
 </section>

 <section xml:id="group-membership">
@@ -387,15 +408,17 @@
  <para>OpenDJ lets you look up which groups a user belongs to by using the
  <literal>isMemberOf</literal> attribute.</para>
  
  <screen>$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 uid=bjensen
 isMemberOf
dn: uid=bjensen,ou=People,dc=example,dc=com
  <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 uid=bjensen \
 isMemberOf</userinput>
<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
isMemberOf: cn=My Static Group,ou=Groups,dc=example,dc=com
isMemberOf: cn=Virtual Static,ou=Groups,dc=example,dc=com
isMemberOf: cn=My Dynamic Group,ou=Groups,dc=example,dc=com</screen>
isMemberOf: cn=My Dynamic Group,ou=Groups,dc=example,dc=com</computeroutput>
  </screen>
  
  <para>You must request <literal>isMemberOf</literal> explicitly.</para>
 </section>
@@ -416,21 +439,25 @@
  referential integrity plugin is disabled by default. To enable the plugin,
  use the <command>dsconfig</command> command.</para>
  
  <screen>$ dsconfig
 set-plugin-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --plugin-name "Referential Integrity"
 --set enabled:true
 --trustAll --no-prompt</screen>
  <screen>
$ <userinput>dsconfig \
 set-plugin-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --plugin-name "Referential Integrity" \
 --set enabled:true \
 --trustAll \
 --no-prompt</userinput>
  </screen>

  <para>With the plugin enabled, you can see OpenDJ referential integrity
  resolving group membership automatically.</para>
  
  <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
  <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"</userinput>
<computeroutput>dn: cn=My Static Group,ou=Groups,dc=example,dc=com
ou: Groups
objectClass: groupOfNames
objectClass: top
@@ -439,23 +466,25 @@
member: uid=tmorris,ou=People,dc=example,dc=com
member: uid=scarter,ou=People,dc=example,dc=com
cn: My Static Group
</computeroutput>
$ <userinput>ldapdelete \
 --port 1389 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 uid=scarter,ou=People,dc=example,dc=com</userinput>
<computeroutput>Processing DELETE request for uid=scarter,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=scarter,ou=People,dc=example,dc=com</computeroutput>

$ ldapdelete
 --port 1389
 --bindDN "cn=Directory Manager"
 --bindPassword password
 uid=scarter,ou=People,dc=example,dc=com
Processing DELETE request for uid=scarter,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=scarter,ou=People,dc=example,dc=com
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"
dn: cn=My Static Group,ou=Groups,dc=example,dc=com
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=My Static Group)"</userinput>
<computeroutput>dn: cn=My Static Group,ou=Groups,dc=example,dc=com
ou: Groups
objectClass: groupOfNames
objectClass: top
cn: My Static Group
member: uid=ahunter,ou=People,dc=example,dc=com
member: uid=bjensen,ou=People,dc=example,dc=com
member: uid=tmorris,ou=People,dc=example,dc=com</screen>
member: uid=tmorris,ou=People,dc=example,dc=com</computeroutput>
  </screen>

 <para>By default the referential integrity plugin is configured to manage
 <literal>member</literal> and <literal>uniqueMember</literal> attributes.