directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: r329780 - in /directory/apacheds/trunk/xdocs: developers/ users/
Date Mon, 31 Oct 2005 09:20:40 GMT
Author: akarasulu
Date: Mon Oct 31 01:20:32 2005
New Revision: 329780

URL: http://svn.apache.org/viewcvs?rev=329780&view=rev
Log:
more generated doco from confluence

Added:
    directory/apacheds/trunk/xdocs/users/acareas.xml
    directory/apacheds/trunk/xdocs/users/allowselfpasswordmodify
    directory/apacheds/trunk/xdocs/users/denysubentryaccess.xml
    directory/apacheds/trunk/xdocs/users/enablesearchforallusers.xml
    directory/apacheds/trunk/xdocs/users/grantadddelmodtogroup.xml
    directory/apacheds/trunk/xdocs/users/grantmodtoentry.xml
    directory/apacheds/trunk/xdocs/users/userpermissions.xml
Modified:
    directory/apacheds/trunk/xdocs/developers/aci_aciitemabnf.xml
    directory/apacheds/trunk/xdocs/developers/aci_implnotes.xml
    directory/apacheds/trunk/xdocs/users/authorization.xml
    directory/apacheds/trunk/xdocs/users/subentries.xml
    directory/apacheds/trunk/xdocs/users/userclasses.xml

Modified: directory/apacheds/trunk/xdocs/developers/aci_aciitemabnf.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/developers/aci_aciitemabnf.xml?rev=329780&r1=329779&r2=329780&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/developers/aci_aciitemabnf.xml (original)
+++ directory/apacheds/trunk/xdocs/developers/aci_aciitemabnf.xml Mon Oct 31 01:20:32 2005
@@ -175,9 +175,24 @@
 ;MYRULE
 ;id-X = "X"
 </source>
-    <p>
+    <table>
+      <tr>
+        <th>
+          <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+        </th>
+        <th>
+          <center>The Apache Directory Server way...</center>
+        </th>
+      </tr>
+      <tr>
+        <td/>
+        <td>
+          <p>
 Apache Directory Server allows a fully flexible version of this grammar where
 order of named components and amount of spaces (where applicable) do not
 matter.</p>
+        </td>
+      </tr>
+    </table>
   </body>
 </document>

Modified: directory/apacheds/trunk/xdocs/developers/aci_implnotes.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/developers/aci_implnotes.xml?rev=329780&r1=329779&r2=329780&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/developers/aci_implnotes.xml (original)
+++ directory/apacheds/trunk/xdocs/developers/aci_implnotes.xml Mon Oct 31 01:20:32 2005
@@ -71,11 +71,20 @@
 \\</p>
       <p>
 \\</p>
-      <p>
+      <table>
+        <tr>
+          <td>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+          </td>
+          <td>
+            <p>
 A set of ACITuples are generated from an ACIItem.  Sets of ACITuples can be
 mixed and evaluated together to represent the combined access control affects of
 one or more
 ACIItems.</p>
+          </td>
+        </tr>
+      </table>
       <p>
 \\</p>
       <p>

Added: directory/apacheds/trunk/xdocs/users/acareas.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/acareas.xml?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/acareas.xml (added)
+++ directory/apacheds/trunk/xdocs/users/acareas.xml Mon Oct 31 01:20:32 2005
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>ACAreas</title>
+  </properties>
+  <body>
+    <section heading="h1" name="Introduction">
+      <p>
+This guide will show you how to create an Access Control Specific Area and inner
+areas for administering access controls within ApacheDS.  Basic knowledge of the
+X.500 administrative model is presumed along with an understanding of the Basic
+Access Control Scheme in X.501.  For quick primers please take a look at the
+following
+documentation:</p>
+      <ul nesting="1">
+        <li>
+          <a href="./subentries.html">Subentries</a>
+and the Administrative
+Model
+        </li>
+        <li>
+          <a href="./authorization.html">Authorization</a>
+        </li>
+      </ul>
+    </section>
+    <section heading="h1" name="Creating Access Control Specific Areas (ACSA)">
+      <p>
+An access control specific area is an Autonomous Administrative Area (AAA) for
+managing access control specific aspects of a subtree within the DIT.  Like all
+administrative areas, an access control specific area is rooted at a vertex
+entry called the Administrative Point (AP).  The ACSA spans down until leaf
+entries are encountered or until another ACSA is encountered.  Access control
+specific areas do not
+overlap.</p>
+      <p>
+Under the AP, you can add subentries that contain prescriptiveACI attributes. 
+Zero or more subentries can be added, each with one or more prescriptiveACI. 
+These subentries apply access control information (ACI) in these prescriptiveACI
+attributes to collections of entries within the
+ACSA.</p>
+      <subsection heading="h2" name="Adding an 'administrativeRole' Attribute">
+        <p>
+An entry becomes an AP when it has an administrativeRole attribute added to it
+with the appropriate
+value
+          <a href="./s.html">s</a>
+. For an ACSA, we need to add the 'accessControlSpecificArea' value to this
+attribute.
+        </p>
+        <p>
+Most of the time users will create partitions in the server and set the root
+context of the partition (it's suffix) to be the AP for a ACSA.  For example the
+default server.xml for ApacheDS ships with a partition with the suffix,
+dc=example,dc=com.  We can use this suffix entry as the AP and our ACSA can
+cover all entries under and including
+dc=example,dc=com.</p>
+        <p>
+The code below binds to the server as admin (uid=admin,ou=system) and modifies
+the suffix entry to become an ACSA.  Note that we check to make sure the
+attribute does not already exist before attempting the add
+operation.</p>
+        <source>  ...
+  // Get a DirContext on the dc=example,dc=com entry
+  Hashtable env = new Hashtable();
+  env.put( "java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory" );
+  env.put( "java.naming.provider.url", "ldap://localhost:389/dc=example,dc=com" );
+  env.put( "java.naming.security.principal", "uid=admin,ou=system" );
+  env.put( "java.naming.security.credentials", "secret" );
+  env.put( "java.naming.security.authentication", "simple" );
+  ctx = new InitialDirContext( env );
+
+  // Lookup the administrativeRole specifically since it is operational
+  Attributes ap = ctx.getAttributes( "", new String[] { "administrativeRole" } );
+  Attribute administrativeRole = ap.get( "administrativeRole" );
+
+  // If it does not exist or has no ACSA value then add the attribute
+  if ( administrativeRole == null || ! administrativeRole.contains( "accessControlSpecificArea" ) )
+  {
+    Attributes changes = new BasicAttributes( "administrativeRole", "accessControlSpecificArea", true );
+    ctx.modifyAttributes( "", DirContext.ADD_ATTRIBUTE, changes );
+  }
+  ...
+</source>
+        <p>
+This simple modification of adding the value 'accessControlSpecificArea' to the
+administrativeRole makes the suffix entry dc=example,dc=com an AP for an access
+control specific area. Now you can add subentries to your heart's content which
+subordinate to the
+AP.</p>
+      </subsection>
+    </section>
+    <section heading="h1" name="Creating an Access Control Inner Administrative Area">
+      <p>
+Creating an inner area involves the same process.  In fact the same code can be
+used by changing the value added to the administrativeRole attribute.  To create
+the inner area just add 'accessControlInnerArea' for the administrativeRole
+within the AP: same steps, same code, different value for the
+administrativeRole.</p>
+    </section>
+    <section heading="h1" name="Access Control Subentries">
+      <p>
+After creating the access control area you can create subentries that
+subordinate to this AP for managing access to it and anything below.  Access
+control subentries are entries with the objectClasses: 'subentry' and
+'accessControlSubentry'.  An access control subentry must contain 3 attributes
+other than the obvious objectClass attribute.  These required attributes are
+listed
+below:</p>
+      <table>
+        <tr>
+          <th>
+Attribute</th>
+          <th>
+SINGLE-VALUED</th>
+          <th>
+Description</th>
+        </tr>
+        <tr>
+          <td>
+cn</td>
+          <td>
+no</td>
+          <td>
+The name of the subentry used as its
+RDN</td>
+        </tr>
+        <tr>
+          <td>
+subtreeSpecification</td>
+          <td>
+yes</td>
+          <td>
+The specification for the collection of entries the ACI is to be applied
+to.</td>
+        </tr>
+        <tr>
+          <td>
+prescriptiveACI</td>
+          <td>
+no</td>
+          <td>
+The attribute holding the
+ACIItem</td>
+        </tr>
+      </table>
+    </section>
+  </body>
+</document>

Added: directory/apacheds/trunk/xdocs/users/allowselfpasswordmodify
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/allowselfpasswordmodify?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/allowselfpasswordmodify (added)
+++ directory/apacheds/trunk/xdocs/users/allowselfpasswordmodify Mon Oct 31 01:20:32 2005
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>AllowSelfPasswordModify</title>
+  </properties>
+  <body>
+    <source>{
+  identificationTag "allowSelfAccessAndModification",
+  precedence 14,
+  authenticationLevel none,
+  itemOrUserFirst userFirst: 
+  {
+    userClasses { thisEntry },
+    userPermissions 
+    { 
+      { protectedItems {entry}, grantsAndDenials { grantModify, grantBrowse, grantRead } },
+      { protectedItems {allAttributeValues {userPassword}}, grantsAndDenials { grantAdd, grantRemove } }
+    } 
+  } 
+}
+</source>
+    <section heading="h2" name="Commentary">
+      <p>
+Note that two different user permissions are used to accurately specify self
+access and self modification of the *userPassword* attribute within the entry. 
+So with the first userPermission of this ACI a user would be able to read all
+attributes and values within his/her entry.  They also have the ability to
+modify the entry but this is moot since they cannot add, remove or replace any
+attributes within their entry.  The second user permission completes the picture
+by granting add and remove permissions to all values of userPassword.  This
+means the user can replace the
+password.</p>
+      <table>
+        <tr>
+          <th>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+          </th>
+          <th>
+            <center>"grantAdd + grantRemove = grantReplace"</center>
+          </th>
+        </tr>
+        <tr>
+          <td/>
+          <td>
+            <p>
+Modify operations either add, remove or replace attributes and their values in
+LDAP.  X.500 seems to have overlooked the replace capability.  Hence there is no
+such thing as a *grantReplace* permission.  However grantAdd and grantDelete on
+an attribute and its values are both required for a replace operation to take
+place.</p>
+          </td>
+        </tr>
+      </table>
+    </section>
+  </body>
+</document>

Modified: directory/apacheds/trunk/xdocs/users/authorization.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/authorization.xml?rev=329780&r1=329779&r2=329780&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/authorization.xml (original)
+++ directory/apacheds/trunk/xdocs/users/authorization.xml Mon Oct 31 01:20:32 2005
@@ -41,13 +41,22 @@
 the multivalued operational attribute, *entryACI*. The values of the entryACI
 attribute contain
 ACIItems.</p>
-        <p>
+        <table>
+          <tr>
+            <td>
+              <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+            </td>
+            <td>
+              <p>
 There is one exception to the rule of consulting entryACI attributes within
 ApacheDS: add operations do not consult the entryACI within the entry being
 added. This is a security precaution. If allowed users can arbitrarily add
 entries where they wanted by putting entryACI into the new entry being added.
 This could comprimise the
 DSA.</p>
+            </td>
+          </tr>
+        </table>
       </subsection>
       <subsection heading="h3" name="Prescriptive ACI">
         <p>
@@ -72,20 +81,35 @@
 ACIs instead. Entry ACIs are more for managing exceptional cases and should not
 be used
 excessively.</p>
-        <p>
+        <table>
+          <tr>
+            <th>
+              <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+            </th>
+            <th>
+              <center>How it works!</center>
+            </th>
+          </tr>
+          <tr>
+            <td/>
+            <td>
+              <p>
 For every type of LDAP operation ApacheDS checks to see if any access control
 subentries include the protected entry in their collection. The set of
 subentries which include the protected entry are discovered very rapidly by the
 subentry subsystem. The subentry subsystem caches subtreeSpecifications for all
 subentries within the server so inclusion checks are
 fast.</p>
-        <p>
+              <p>
 For each access control subentry in the set, ApacheDS checks within a
 prescriptive ACI cache for ACI tuples. ApacheDS also caches prescriptive ACI
 information in a special form called ACI tuples. This is done so ACIItem parsing
 and conversion to an optimal representations for evaluation is not required at
 access time. This way access based on prescriptive ACIs is determined very
 rapidly.</p>
+            </td>
+          </tr>
+        </table>
       </subsection>
       <subsection heading="h3" name="Subentry ACI">
         <p>
@@ -116,63 +140,93 @@
 on different protection mechanisms offered by the ACIItem syntax. We do this
 instead of specifying the grammar which is not the best way to learn a
 language.</p>
-      <p>
-Please don't go any further until you have read up on the use
-of
-        <a href="./subentries.html">Subentries</a>
-. Knowledge of subentries, subtreeSpecifications, administrative areas, and
-administrative roles are required to properly digest the following
-matterial.
-      </p>
       <table>
         <tr>
           <th>
-Trail</th>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/forbidden.png"/>
+          </th>
           <th>
-Description</th>
+            <center>Before you go any further...</center>
+          </th>
         </tr>
         <tr>
+          <td/>
           <td>
-            <a href="./enablesearchforallusers.html">EnableSearchForAllUsers</a>
+            <p>
+Please don't go any further until you have read up on the use
+of
+              <a href="./subentries.html">Subentries</a>
+. Knowledge of subentries, subtreeSpecifications, administrative areas, and
+administrative roles are required to properly digest the following
+matterial.
+            </p>
           </td>
-          <td>
+        </tr>
+      </table>
+      <p>
+Before going on to these trails you might want to set up an Administrative Area
+for managing access control via prescriptiveACI.  Both subentryACI and
+prescriptiveACI require the presence of an Administrative Point entry.  For more
+information and code examples
+see
+        <a href="./acareas.html">ACAreas</a>
+.
+      </p>
+      <subsection heading="h3" name="ACI Trails">
+        <p>
+Here are some trails that resemble simple HOWTO guides.  They're ordered with
+the most pragmatic usage first.  We will add to these trails over
+time.</p>
+        <table>
+          <tr>
+            <th>
+Trail</th>
+            <th>
+Description</th>
+          </tr>
+          <tr>
+            <td>
+              <a href="./enablesearchforallusers.html">EnableSearchForAllUsers</a>
+            </td>
+            <td>
 Enabling access to browse and read all entries and their attributes by
 authenticated
 users.</td>
-        </tr>
-        <tr>
-          <td>
-            <a href="./denysubentryaccess.html">DenySubentryAccess</a>
-          </td>
-          <td>
+          </tr>
+          <tr>
+            <td>
+              <a href="./denysubentryaccess.html">DenySubentryAccess</a>
+            </td>
+            <td>
 Protecting access to subentries
 themselves.</td>
-        </tr>
-        <tr>
-          <td>
-            <a href="./allowselfpasswordmodify.html">AllowSelfPasswordModify</a>
-          </td>
-          <td>
+          </tr>
+          <tr>
+            <td>
+              <a href="./allowselfpasswordmodify.html">AllowSelfPasswordModify</a>
+            </td>
+            <td>
 Granting users the rights needed to change their own
 passwords.</td>
-        </tr>
-        <tr>
-          <td>
-            <a href="./grantadddelmodtogroup.html">GrantAddDelModToGroup</a>
-          </td>
-          <td>
+          </tr>
+          <tr>
+            <td>
+              <a href="./grantadddelmodtogroup.html">GrantAddDelModToGroup</a>
+            </td>
+            <td>
 Granting add, delete, and modify permissions to a group of
 users.</td>
-        </tr>
-        <tr>
-          <td>
-            <a href="./grantmodtoentry.html">GrantModToEntry</a>
-          </td>
-          <td>
+          </tr>
+          <tr>
+            <td>
+              <a href="./grantmodtoentry.html">GrantModToEntry</a>
+            </td>
+            <td>
 Applying ACI to a single
 entry.</td>
-        </tr>
-      </table>
+          </tr>
+        </table>
+      </subsection>
     </section>
   </body>
 </document>

Added: directory/apacheds/trunk/xdocs/users/denysubentryaccess.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/denysubentryaccess.xml?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/denysubentryaccess.xml (added)
+++ directory/apacheds/trunk/xdocs/users/denysubentryaccess.xml Mon Oct 31 01:20:32 2005
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>DenySubentryAccess</title>
+  </properties>
+  <body>
+    <p>
+Coming soon
+...</p>
+  </body>
+</document>

Added: directory/apacheds/trunk/xdocs/users/enablesearchforallusers.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/enablesearchforallusers.xml?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/enablesearchforallusers.xml (added)
+++ directory/apacheds/trunk/xdocs/users/enablesearchforallusers.xml Mon Oct 31 01:20:32 2005
@@ -0,0 +1,322 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>EnableSearchForAllUsers</title>
+  </properties>
+  <body>
+    <section heading="h1" name="Enable Authenticated Users to Browse and Read Entries in a Subtree">
+      <table>
+        <tr>
+          <th>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+          </th>
+          <th>
+            <center>The first time is always the hardest!</center>
+          </th>
+        </tr>
+        <tr>
+          <td/>
+          <td>
+            <p>
+We presume this is your first encounter and so many bases will be covered this
+time around. Every other trail will build on this information.  So expect a
+little less to read as you gain
+momentum.</p>
+          </td>
+        </tr>
+      </table>
+      <p>
+Since the entire directory is locked down for all but the superuser, you're
+going to want to grant read and browse access to users for certain regions of
+the DIT. This will probably be the first thing you'll want to do after turning
+on access
+controls.</p>
+      <subsection heading="h2" name="Check for insufficientAccessRights for Normal Users">
+        <p>
+Just to make sure everything is locked down login as admin and create a new
+non-superuser.  For more information on how to do this
+see
+          <a href="./authentication.html">Authentication</a>
+.  After creating the normal user make sure you cannot bind to dc=example,dc=com
+with access controls enabled.  You should get an error trying to bind with a
+result code of 50 (insufficientAccessRights).  If using JNDI to connect to the
+server you should get a NoPermissionException.  After we apply the following ACI
+you can check
+again.
+        </p>
+      </subsection>
+      <subsection heading="h2" name="Partition and Access Control Area Setup">
+        <p>
+For this example we presume you have setup a partition at the namingContext
+dc=example,dc=com and have turned on access controls.  Now you want to grant
+browse and read access to entries and their
+attributes.</p>
+        <p>
+Before you can add a subentry with the prescriptiveACI you'll need to create an
+administrative area.  For now we'll make the root of the partition the
+adminstrative point (AP). Every entry including this entry and those underneath
+it will be part of the autonous administrative area for managing access
+controls. To do this we must add the administrativeRole operational attribute to
+the AP entry.
+See
+          <a href="./acarea.html">ACArea</a>
+for code and information about creating access control administrative
+areas.
+        </p>
+      </subsection>
+      <subsection heading="h2" name="Adding the Subentry">
+        <p>
+The subentry can be added using an LDIF or via code. We'll show the code but the
+LDIF can be accessed
+here
+          <a href="./enablesearchforallusers.ldif.html">enableSearchForAllUsers.ldif</a>
+:
+        </p>
+        <source>  // Get a DirContext on the dc=example,dc=com entry
+  Hashtable env = new Hashtable();
+  env.put( "java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory" );
+  env.put( "java.naming.provider.url", "ldap://localhost:" + port + "/dc=example,dc=com" );
+  env.put( "java.naming.security.principal", "uid=admin,ou=system" );
+  env.put( "java.naming.security.credentials", "secret" );
+  env.put( "java.naming.security.authentication", "simple" );
+  ctx = new InitialDirContext( env );
+
+  // now add the A/C subentry below dc=example,dc=com
+  Attributes subentry = new BasicAttributes( "cn", "enableSearchForAllUsers", true );
+  Attribute objectClass = new BasicAttribute( "objectClass" );
+  subentry.put( objectClass );
+  objectClass.add( "top" );
+  objectClass.add( "subentry" );
+  objectClass.add( "accessControlSubentry" );
+  subentry.put( "subtreeSpecification", "{}" );
+  subentry.put( "prescriptiveACI", "{ \n" +
+                "  identificationTag \"enableSearchForAllUsers\",\n" +
+                "  precedence 14,\n" +
+                "  authenticationLevel simple,\n" +
+                "  itemOrUserFirst userFirst: \n" +
+                "  { \n" +
+                "    userClasses { allUsers }, \n" +
+                "    userPermissions \n" +
+                "    { \n" +
+                "       {\n" +
+                "         protectedItems {entry, allUserAttributeTypesAndValues}, \n" +
+                "         grantsAndDenials { grantRead, grantReturnDN, grantBrowse } \n" +
+                "       }\n" +
+                "    } \n" +
+                "  } " );
+  ctx.createSubcontext( "cn=enableSearchForAllUsers", subentry );
+</source>
+        <p>
+Before we cover the anatomy of this ACIItem, you might want to add the subentry
+and test access with a normal non-super user to make sure access is now
+granted.</p>
+      </subsection>
+    </section>
+    <section heading="h1" name="ACIItem Description">
+      <p>
+Here's the ACIItem you just added above without all the Java
+clutter:</p>
+      <source>{ 
+  identificationTag "enableSearchForAllUsers",
+  precedence 14,
+  authenticationLevel simple,
+  itemOrUserFirst userFirst: 
+  { 
+    userClasses { allUsers }, 
+    userPermissions 
+    { 
+       {
+         protectedItems {entry, allUserAttributeTypesAndValues}, 
+         grantsAndDenials { grantRead, grantReturnDN, grantBrowse } 
+       }
+    } 
+  } 
+}
+</source>
+      <p>
+There are several parameters to this simple ACIItem.  Here's a breif
+exaplanation of each field and it's meaning or
+significance.</p>
+      <table>
+        <tr>
+          <th>
+Fields</th>
+          <th>
+Description</th>
+        </tr>
+        <tr>
+          <td>
+identificationTag</td>
+          <td>
+Identifies the ACIItem within an
+entry.</td>
+        </tr>
+        <tr>
+          <td>
+precedence</td>
+          <td>
+Determine which ACI to apply with conflicting
+ACIItems.</td>
+        </tr>
+        <tr>
+          <td>
+authenticationLevel</td>
+          <td>
+User's level of trust with values of none, simple,
+strong</td>
+        </tr>
+        <tr>
+          <td>
+itemOrUserFirst</td>
+          <td>
+Determines order of item permissions or user
+permissions.</td>
+        </tr>
+        <tr>
+          <td>
+userClasses</td>
+          <td>
+The set of users the permissions apply
+to.</td>
+        </tr>
+        <tr>
+          <td>
+userPermissions</td>
+          <td>
+Permissions on protected
+items</td>
+        </tr>
+      </table>
+      <subsection heading="h2" name="identificationTag">
+        <p>
+The identificationTag is just that a tag.  It's often used with a subtring
+search filter to lookup a specific ACIItem within an entry.  One or more
+ACIItems may be present within a subentry, zero or more in entries, so this
+serves as a means to address the ACIItem within
+entries.</p>
+      </subsection>
+      <subsection heading="h2" name="precedence">
+        <p>
+Precendence is used to determine the ACI to apply when two or more ACIItem's
+applied to an entry conflict.  The ACIItem with the highest precedence is
+applied over other conflicting
+ACIItems.</p>
+        <table>
+          <tr>
+            <th>
+              <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+            </th>
+            <th>
+              <center>Denials Overpower Grants</center>
+            </th>
+          </tr>
+          <tr>
+            <td/>
+            <td>
+              <p>
+When two or more conflicting ACIItems are encountered with the same precedence
+the ACIItems with denials overpower ACIItems with
+grants.</p>
+            </td>
+          </tr>
+        </table>
+        <p>
+Right now the use of this field may not mean too much to you.  We're dealing
+with a very simple situation with a single access control area.  Later as you
+add more subentries their subtreeSpecifications may define collections that
+intersect.  When this happens two or more conflicting ACIItems may apply to the
+same entry.  Precendence is then applied to determine which permissions
+apply.</p>
+        <p>
+Another complex situation requiring precedence is the use of inner areas.  These
+nested inner administrative areas overlap and so do their effects.  The
+authority within an AA may deny some operation to all entries but grant access
+to subentries of inner areas so minor authorities can control access to inner
+areas.  Their grants to users may need to have a higher precedence over denials
+in outer areas. Such situations will arise and precedence will need to be used. 
+In this example we just assign an arbitrary value to the
+precedence.</p>
+      </subsection>
+      <subsection heading="h2" name="authenticationLevel">
+        <p>
+The authenticationLevel is the minimum authentication requirement for requestor
+for the ACI to by applied:  According to
+X.501:</p>
+        <table>
+          <tr>
+            <th>
+              <img src="http://docs.safehaus.org/images/icons/emoticons/information.png"/>
+            </th>
+            <th>
+              <center>18.4.2.3 Authentication Level</center>
+            </th>
+          </tr>
+          <tr>
+            <td/>
+            <td>
+              <p>
+... Strong authentication of the requestor is considered to exceed a requirement
+for simple or no authentication, and simple authentication exceeds a requirement
+for no authentication
+...</p>
+            </td>
+          </tr>
+        </table>
+        <p>
+The authenticationLevel can have three values: none, simple and strong.  It's
+used to be able to associate permissions with the level of trust in users.  For
+none, the identity of the user is anonymous or does not matter.  The user can be
+anyone. The simple authenticationLevel means the user has authenticated but is
+using a simple bind with clear text passwords.  The strong authenticationLevel
+represents users that bind to the directory using strong authentication
+mechanisms via
+SASL.</p>
+        <p>
+SASL can allow annonynous binds as well so there is a distinction here.  Using
+SASL alone does not mean the authenticationLevel is strong.  As we add SASL
+mechanisms to the server, we'll qualify each one with none, simple or strong. 
+This will be reflected in the authenticationLevel property of the principal
+making
+requests.</p>
+      </subsection>
+      <subsection heading="h2" name="itemOrUserFirst">
+        <p>
+This field describes the order of information within the ACI whether protected
+items are described first or user classes and permissions are described first. 
+For simplicity we will only describe the userFirst configuration in this
+tutorial.</p>
+      </subsection>
+      <subsection heading="h2" name="userClasses">
+        <p>
+UserClasses is used to list the sets of users to which this permission applies. 
+Several mechanisms can be used here to define userClasses.  They can be defined
+by name per user, by group membership, or by the superset of all users possible
+and many more.  In our example we have applied the ACI to all users that have
+authenticated by simple or strong
+means.</p>
+        <p>
+For more information
+see
+          <a href="./userclasses.html">UserClasses</a>
+.
+        </p>
+      </subsection>
+      <subsection heading="h2" name="userPermissions">
+        <p>
+These are the permissions granted or denied to those users included by the
+userClasses field.  The grants or denials however are qualified by the protected
+items operated upon.  In our example we grant read, return DN and browse to all
+entries, their attributes and all possible values they may
+have.</p>
+        <p>
+For more information
+see
+          <a href="./userpermissions.html">UserPermissions</a>
+.
+        </p>
+      </subsection>
+    </section>
+  </body>
+</document>

Added: directory/apacheds/trunk/xdocs/users/grantadddelmodtogroup.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/grantadddelmodtogroup.xml?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/grantadddelmodtogroup.xml (added)
+++ directory/apacheds/trunk/xdocs/users/grantadddelmodtogroup.xml Mon Oct 31 01:20:32 2005
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>GrantAddDelModToGroup</title>
+  </properties>
+  <body>
+    <p>
+Coming soon
+...</p>
+  </body>
+</document>

Added: directory/apacheds/trunk/xdocs/users/grantmodtoentry.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/grantmodtoentry.xml?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/grantmodtoentry.xml (added)
+++ directory/apacheds/trunk/xdocs/users/grantmodtoentry.xml Mon Oct 31 01:20:32 2005
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>GrantModToEntry</title>
+  </properties>
+  <body>
+    <p>
+Coming soon
+...</p>
+  </body>
+</document>

Modified: directory/apacheds/trunk/xdocs/users/subentries.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/subentries.xml?rev=329780&r1=329779&r2=329780&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/subentries.xml (original)
+++ directory/apacheds/trunk/xdocs/users/subentries.xml Mon Oct 31 01:20:32 2005
@@ -3,7 +3,7 @@
 <document>
   <properties>
     <author email="akarasulu">akarasulu</author>
-    <title>Subentry Implementation</title>
+    <title>Subentries</title>
   </properties>
   <body>
     <section heading="h2" name="Introduction">
@@ -14,9 +14,10 @@
         <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a>
 .  Subentries have existed within X.500 Directories for years with clear
 specifications for administering collective attributes, schema, and access
-controls.  Although LDAP has no equivalent *yet* for administering these aspects
-it is well on its way with RFC 3672 towards adopting and adapting these
-mechanisms from X.500 Directories.  It is only a matter of
+controls.  With the exception of managing collective attributes LDAP has no
+equivalent *yet* for administering these aspects.  However with RFC 3672, LDAP
+is on its way towards adopting and adapting these mechanisms from X.500
+Directories.  It is only a matter of
 time.
       </p>
       <p>
@@ -24,198 +25,152 @@
 aspects of administration using Subentries and Administrative Areas similar to
 X.500
 Directories.</p>
-      <p>
-This page describes how Subentries are implemented within ApacheDS according to
-RFC 3672.  An understanding of this RFC and our implementation is critical for
-implementing administration mechanisms for the various mentioned
-aspects.</p>
-    </section>
-    <section heading="h2" name="SubtreeSpecificationParser Class">
-      <p>
-Within the *org.apache.ldap.common.subtree* package there resides a
-SubtreeSpecificationParser which parses the value of a subtreeSpecification
-attribute as defined by RFC 3672.  It generates a bean representation of the
-subtreeSpecification, a SubtreeSpecification instance.  This parser is used by
-the subentry management subsystem of ApacheDS to create these objects to track
-and manage subtrees representing collections of
-entries.</p>
-    </section>
-    <section heading="h2" name="SubtreeEvaluator Class">
-      <p>
-Within the *org.apache.ldap.server.subtree* package there resides a
-SubtreeEvaluator class.  An evaluate() method in this class determines whether
-or not an entry is included by the entry collection described by a
-subtreeSpecification attribute present within a
-subentry.</p>
-      <p>
-The SubtreeEvaluator uses the SubtreeSpecification objects generated  by
-SubtreeSpecificationParser instances.  The evaluator is a critical component as
-we'll see
-later.</p>
     </section>
-    <section heading="h2" name="Tracking Entry Incusion in Subtrees">
+    <section heading="h2" name="What exactly are subentries?">
       <p>
-ApacheDS will need to rapidly determine which subentries an entry is contained
-in.  This will be required for schema checking, access controls, and collective
-attribute handling.  Eventually trigger handling and replication will also
-depend on this
-mechanism.</p>
-      <p>
-To determine the set of subentries including an entry we must use the
-SubtreeEvaluator on each subentry within a naming context.  Searching for these
-subentries, then parsing their subtreeSpecification attribute values every time
-would be an extremely expensive task to perform for each operation.  For this
-reason the subentry subsystem must load all subentry specifications at startup. 
-The parsing of the subtreeSpecification attribute to generate instances of
-SubtreeSpecifcation beans would happen upon initialization of the subsystem. 
-Furthermore the subsystem must track the addition, deletion and modification of
-subentry subtreeSpecifications to update this cache.  Checking for inclusion
-with this cache eliminates the need to search for subentries and parse their
-subtreeSpecification
-attributes.</p>
-      <p>
-There still remains a considerable effort to evaluate all the subentry
-SubtreeSpecifications for each operation on an entry.  When done once this
-information can be cached as well, however it can be permanantly stored with the
-entry using operational attributes.  For this reason we use subentry operational
-attributes within entries to reference the subentries whose subtreeSpecification
-includes them.  Such operational attributes can have a value or multiple values
-containing the DN of the subentry.  A different subentry operational attribute
-is used for each type of administrativeRole associated with the Administrative
-Point corresponding to the subentry.  Hence a subentry operational attribute for
-accessControlSpecificAreas for example can contain zero or more values pointing
-to subentries responsible for Directory Acces Control Domains (DACD). 
-Partitioning the operational attributes according to the administrativeRoles
-further reduces the processing overhead for locating including subentries for an
-entry based on functional needs.  These subentry operational attributes are
-injected automatically into entries by the subentry subsystem on add operations.
-They are modified whenever the subtreeSpecification value on subentries are
-altered or the name of and entry is changed via a modifyRdn operation.  Note
-that these operational attributes also make it easier to search for entries
-included within a subentry's
-subtree.</p>
+To explain this properly we're going to need to discuss a couple other things
+like administrative areas (AA) and administrative points (AP) within the
+directory.  However for the impatient here's a quick attempt to describe what
+subentries
+are:</p>
+      <p>
+Subentries are hidden leaf entries (which cannot have children).  These entries
+immediately subordinate to an administrative point (AP) within the directory. 
+They are used to specify administrative information for a part of the Directory
+Information Tree (DIT).  Subentries can contain administrative information for
+aspects of access control, schema administration, and collective attributes (and
+others which have not been defined in any specification
+yet).</p>
     </section>
-    <section heading="h2" name="Subentry Subsystem Implementation">
-      <p>
-The subentry subsystem must search for all subentries corresponding to a naming
-context and parse their subtreeSpecifications on startup.  The
-SubtreeSpecification objects are cached in memory using a hash.  The normalized
-DN of the subentry is used as the key into this
-hash.</p>
-      <p>
-The subsystem uses an interceptor to detect the addition, deletion and
-modification of subentries to update this cache with new information.  This way
-a restart will not be required to update the cache when administrative changes
-are made via subentry
-modifications.</p>
-      <p>
-Whenever an entry is added or its name is changed via a modifyRdn operation, the
-interceptor traps these calls and evaluates or re-evaluates the subentry
-operational attributes for that entry.  The cache of SubtreeSpecifications is
-accessed to test for inclusion of that entry within a subentry's
-subtree.</p>
+    <section heading="h2" name="Administrative Areas, Entries and Points">
       <p>
-The subsystem may partition the SubtreeSpecification cache based on the naming
-context under which its subentry is located.  Partitioning the space this way
-reduces the overall search for including
-subtrees.</p>
-    </section>
-    <section heading="h2" name="Actions to take on operations">
-      <subsection heading="h3" name="Operations on Subentries">
-        <ul nesting="1">
-          <li>
-Add
-Subentry</li>
-          <ul nesting="2">
-            <li>
-Parse and add SubtreeSpecification of the Subentry to
-cache</li>
-            <li>
-Find and update the subentry operational attributes of all entries included by
-the new
-subtreeSpecification</li>
-          </ul>
-          <li>
-Delete
-Subentry</li>
-          <ul nesting="2">
-            <li>
-Remove the SubtreeSpecification of the Subentry from the
-cache</li>
-            <li>
-Find all entries that were included in the subtree and remove references to the
-subentry</li>
-          </ul>
-          <li>
-Modify Subentry's subtreeSpecification
-Attribute</li>
-          <ul nesting="2">
-            <li>
-Remove all entry references to the subentry's according to the old
-subtree</li>
-            <li>
-Remove the old SubtreeSpecification from the SS
-cache</li>
-            <li>
-Parse and add the new SubtreeSpecification to the SS
-cache</li>
-            <li>
-Find all entries selected by the new SubtreeSpecification and update their
-operational attributes to point to the
-subentry</li>
-          </ul>
-          <li>
-ModifyRdn on
-Subentry</li>
-          <ul nesting="2">
-            <li>
-Lookup all entries that reference the old name of the subentry and replace those
-operational attributes with the new
-name</li>
-          </ul>
-        </ul>
-      </subsection>
-      <subsection heading="h3" name="Operations on Entries">
-        <ul nesting="1">
-          <li>
-Add
-Entry</li>
-          <ul nesting="2">
-            <li>
-Check to see if the entry is included by any
-SubtreeSpecifications</li>
-            <li>
-If it is add the appropriate subentry operational attributes to the entry to
-reference the
-subentry</li>
-          </ul>
-          <li>
-ModifyRdn</li>
-          <ul nesting="2">
-            <li>
-Some specific exclusions may cause Rdn name changes to affect inclusion so we
-have to remove all subentry operational attributes within the entry and
-recompute then once
-again.</li>
-            <li>
-Operations that change the names of administrative points directly via a
-modifyRdn on the AP or via one of the AP's ancestors cannot be permitted.  The
-reason is these changes would change the name of subentries referenced by
-entries in scope below the AP.  To move an AP the user must make it a normal
-entry
-first.</li>
-          </ul>
-        </ul>
-      </subsection>
+First some definitions as provided by
+X.501:</p>
+      <ul nesting="1">
+        <li>
+11.1.1 administrative area: A subtree of the DIT considered from the perspective
+of
+administration.</li>
+        <li>
+11.1.2 administrative entry: An entry located at an administrative
+point.</li>
+        <li>
+11.1.3 administrative point: The root vertex of an administrative
+area.</li>
+        <li>
+11.1.5 autonomous administrative area: A subtree of the DIT whose entries are
+all administered by the same Administrative Authority. Autonomous administrative
+areas are
+non-overlapping.</li>
+        <li>
+11.1.11 inner administrative area: A specific administrative area whose scope is
+wholly contained within the scope of another specific administrative area of the
+same
+type.</li>
+        <li>
+11.1.17 specific administrative area: A subset (in the form of a subtree) of an
+autonomous administrative area defined for a particular aspect of
+administration: access control, subschema or entry collection administration.
+When defined, specific administrative areas of a particular kind partition an
+autonomous administrative
+area.</li>
+        <li>
+11.1.18 specific administrative point: The root vertex of a specific
+administrative
+area.</li>
+      </ul>
+      <p>
+Now take a step back because the above definitions are, well, from a sleep
+inducing spec. Let's just talk about some
+situations.</p>
+      <p>
+Presume you're the uber directory administrator over at WallyWorld (a Walmart
+competitor). Let's say WallyWorld uses their corporate directory for various
+things including their product catalog. As the uber admin you're going to have a
+bunch of people wanting access, update and even administer your directory.
+Entire departments within WallyWorld are going to want to control different
+parts of the directory. Sales may want to manage the product catalog, while
+operations may want to manage information in other areas dealing with suppliers
+and store locations. Whatever the domain some department will need to manage the
+information as the
+authority.</p>
+      <p>
+Each department will probably designate different people to manage different
+aspects of their domain. You're not going to want to deal with their little
+fiefdoms instead you can delegate the administration of access control policy to
+a departmental contact. You will want to empower your users and administrative
+contacts in these departments so they can do part of the job for you. Plus it's
+much better than having to communicate with everyone in the company to meet
+their needs. This is where the delegation of authority comes into the
+picture.</p>
+      <p>
+Usually administrators do this already to an extent without defining
+administrative areas. Giving users the ability to change their own passwords for
+example is a form of delegation. This is generally a good idea because you don't
+want to set passwords for people. First because you don't want to see the
+password and secondly because of the management nightmare you'd have to deal
+with. Expand this idea out a little further and think about delegating
+administration not of users on their passwords but of entire subtrees in the
+directory to administrative contacts in various
+departments.</p>
+      <p>
+Do you really want to manage the corporate product catalog or just let the sales
+department manage it. But what do we mean by manage? You want sales people to
+create, and delete entries but they may only trust a few people to do this.
+Others may just view the catelog. Who are the people with add/remove powers and
+why should you have to be involved with deciding this ever changing departmental
+policy? Instead you can delegate the management of access controls in this area
+to a administrative contact in the sales department. The sales contact can then
+administer access controls for their department. They're closer to the people in
+sales then you are and they probably have more bandwidth to handle sales related
+needs than you do. Delegating authority in this fashion is what X.500 engineers
+pioneered in the early 80's with the telecom boom in Europe. They knew different
+authorities will want to manage different aspects of directory administration
+for themselves. These X.500 definitions are there to be able to talk about
+administrative areas within the directory. Now let's get back to what these
+things are
+exactly.</p>
+      <p>
+An administrative area is some part of the directory tree that is arbitrarily
+defined. The tree can be split into different administrative areas to delegate
+authority for managing various aspects of administration. For example you can
+have a partition hanging off of 'dc=example,dc=com' with an 'ou=product catalog'
+area. You may want this area to be managed by the sales department with respect
+to the content, schema, it's visibility, and collective attributes. Perhaps you
+only want to delegate only one aspect of administration , access control, since
+you don't want people messing around with schema. To do so you can define
+everything under 'ou=product catalog' to be an administrative area specifically
+for access control and delegate that aspect only. In that case the entry,
+'ou=product catalog,dc=example,dc=com' becomes an administrative entry. It is
+also the administrative point for the area which is the tree rooted at this
+entry.</p>
+      <p>
+Not all administrative areas are equal. There are really two kinds. Autonomous
+and inner areas. Autonomous areas are areas of administration that cannot
+overlap. Meaning someone is assigned as the supreme authority for that subtree.
+Inner areas are, as their name suggests, nested administrative areas within
+autonomous areas and other inner areas. Yes, you can nest these inner areas as
+deep as you like. You may be asking yourself what the point to all this is.
+Well, say you're the supreme admin of admins. You delegate the authority to
+manage access control for the corporate catalog to the sales admin. That admin
+may in turn decide to delegate yet another area of the catalog to another
+contact within a different department. You delegate access control management to
+the sales admin over the product catalog. The sales admin realizes that the job
+is way bigger than he can manage so he delegates administration of subtrees in
+the catalog to various contacts in different departments. For example regions of
+the catalog under 'ou=electronics' and 'ou=produce' may be delegated to
+different contacts in their respective departments. However the sales admin
+still reserves the ability to override access controls in the catalog. The sales
+admin can change who manages access controls for different parts of the catalog.
+This chain of delegation is possible using inner administrative
+areas.</p>
     </section>
-    <section heading="h2" name="Subentry Operational Attributes in Entries">
+    <section heading="h2" name="How are administrative areas defined?">
       <p>
-Our approach here is justified in part by the use of subschemaSubentry
-operational attributes which point to subentries managing schema information for
-an entry.  We will expand on this concept for the other aspects of
-administration, namely for access control and collective attribute management. 
-RFC 3672 defines the following administrativeRole values for an administrative
-point:</p>
+Usually an entry is selected as the administrative point and marked with an
+operational attribute. The attributeType of the operational attribute is
+'administrativeRole'. This attribute can have the following
+values:</p>
       <table>
         <tr>
           <th>
@@ -261,96 +216,295 @@
         </tr>
       </table>
       <p>
-We propose the following subentry operational attribute types to be used to
-correspond to these
-administrativeRoles:</p>
-      <table>
-        <tr>
-          <th>
-OID</th>
-          <th>
-NAME</th>
-          <th>
-ATTRIBUTE TYPE
-NAME</th>
-        </tr>
-        <tr>
-          <td>
-2.5.23.1</td>
-          <td>
-autonomousArea</td>
-          <td>
-automomousAreaSubentry</td>
-        </tr>
-        <tr>
-          <td>
-2.5.23.2</td>
-          <td>
-accessControlSpecificArea</td>
-          <td>
-accessControlAreaSubentries</td>
-        </tr>
-        <tr>
-          <td>
-2.5.23.3</td>
-          <td>
-accessControlInnerArea</td>
-          <td>
-accessControlInnerAreaSubentries</td>
-        </tr>
-        <tr>
-          <td>
-2.5.23.4</td>
-          <td>
-subschemaAdminSpecificArea</td>
-          <td>
-subschemaSubentry
-(EXISTS)</td>
-        </tr>
-        <tr>
-          <td>
-2.5.23.5</td>
-          <td>
-collectiveAttributeSpecificArea</td>
-          <td>
-collectiveAttributeSubentries
-(EXISTS)</td>
-        </tr>
-        <tr>
-          <td>
-2.5.23.6</td>
-          <td>
-collectiveAttributeInnerArea</td>
-          <td>
-collectiveAttributeSubentries
-(EXISTS)</td>
-        </tr>
-      </table>
+As you can see, 3 aspects, schema, collective attributes, and access control are
+considered. An autonomous administrative area can hence be considered with
+respect to all three specific aspect of administration. If an AP is marked as an
+autonomousArea it generally means that administration of all aspects are allowed
+by the authority. If marked with a specific aspect then only that aspect of
+administration is delegated. The administrativeRole operational attribute is
+multivalued so the uber admin can delegate any number of specific administration
+aspects as he
+likes.</p>
+      <p>
+Also notice that two aspects, collective attribute and access controls, allow
+administrative points to be inner areas. Delegated authorities for these two
+aspects can create inner administrative areas to further delegate their
+administrative powers. The schema aspect unlike the others cannot have inner
+areas because of potential conflicts this may cause which would lead to data
+integrity issues. For this reason only the authority of an automomous area can
+manage schema for the entire
+subtree.</p>
+      <p>
+An autonomous administrative area (AAA) includes the AP and spans all
+descendants below the AP down to the leaf entries of the subtree with one
+exception. If another AAA, let's call it AAA' (prime) is present and rooted
+below the first AAA then the first AAA does not include the entries of AAA'.
+Translation: an AAA spans down until other AAAs or leaf entries are encountered
+within the subtree. This is due to the fact that AAAs do not overlap as do inner
+AAs
+(IAA).</p>
     </section>
-    <section heading="h2" name="Collective Attributes: a good simple usecase">
+    <section heading="h2" name="Subentries under an IAA or an AAA">
       <p>
-Collective attributes use subentries and are perhaps the simplest mechanism by
-which we can demonstrate the use of subentries.  Here is an RFC for LDAP that
-describes
-how:
-        <a href="http://www.faqs.org/rfcs/rfc3671.html">RFC 3671</a>
-      </p>
+Subentries hold administrative information for an IAA or an AAA. These entries
+are of the objectClass 'subentry'. The subentry must contain two attributes: a
+commonName and a subtreeSpecification. The commonName (or cn) is used as the
+subentry's rdn attribute. The subtreeSpecification describes the collection of
+entries within the AA (IAA or AAA) that the administrative instruction applies
+to.</p>
+      <p>
+A subtree specification uses various parameters described below to define the
+set of entries. Note that entries need not exist for them to be included in the
+collection on
+addition.</p>
+      <subsection heading="h3" name="Base parameter">
+        <p>
+This is the relative name of the root vertex of the subtree relative to the AP.
+So if the AP is 'ou=system' and the base is 'ou=users', the subtree begins at
+'ou=users,ou=system'. The base can be any length of name components including 0
+where it's the empty name "". In this case, the subtree begins at the AP,
+'ou=system' in the example
+above.</p>
+      </subsection>
+      <subsection heading="h3" name="Chop parameters">
+        <p>
+Chop specification parameters define specific nodes to be excluded from the
+collection as well as how deep the subtree spans and even where it starts
+relative to the
+base.</p>
+        <subsection heading="h4" name="chopBefore and chopAfter">
+          <p>
+These parameters are names relative to the root vertex of the subtree, hence
+they are relative to the base parameter. They specify whether or not an entry
+and its descendants are to be excluded from the
+collection.</p>
+          <p>
+When chopBefore is used, the entry specified is excluded from the collection.
+When chopAfter is used the entry is included however all descendants below the
+entry are
+excluded.</p>
+        </subsection>
+        <subsection heading="h4" name="minimum and maximum">
+          <p>
+The minimum parameter describes the minimum DN length required to include
+entries within the selection. The maximum parameter describes the maximum DN
+length allowed before entries are excluded from the
+collection.</p>
+        </subsection>
+      </subsection>
+      <subsection heading="h3" name="Specification filter parameter">
+        <p>
+The specification filter is a unique beast. It's a filter like a search filter,
+however its syntax and expressivity is radically different. Think of a
+specification filter as a simplified form of search filters where all terms only
+test the objectClass attribute and only equality checks can be performed. Oh and
+yes, you do have logical operators like and, or and
+not.</p>
+        <p>
+So with a filter you have the ability to "refine" the subtree already specified
+with chop, and base parameters. This "refinement" makes it so the collection is
+not really a contiguous subtree of entries but a possibly disconnected set of
+selected based on the objectClass characteristics of entries. This feature of a
+subtreeSpecification is very powerful. For example, I can define a subtree to
+cover a region of an AA yet include only inetOrgPersons within this
+region.</p>
+      </subsection>
+      <subsection heading="h3" name="Subentry types in ApacheDS">
+        <p>
+Different subentry objectClasses exist for applying different aspects of
+administration to the entry collection described by their subtreeSpecification
+attribute. By the way the subtreeSpecification attribute is single valued so
+there can only be one in a subentry. However you can have several subentries of
+various kinds under an AP. Furthermore their collections can
+intersect.</p>
+        <p>
+The kinds of subentries allowed though are limited by the administrativeRole of
+the AP. If the AP is for an access control AA then you can't add a subentry to
+it for schema administration. The AP must have the role for schema
+administration as well to allow both types of
+subentries.</p>
+        <p>
+ApacheDS does not manage schema using subentries in the formal X.500 sense right
+now. There is a single global subentry defined at 'cn=schema' for the entire
+DSA. The schema is static and cannot be updated at runtime even by the
+administrator. Pretty rough for now but it's the only lagging subsystem. We'll
+of course make sure this subsystem catches
+up.</p>
+        <p>
+ApacheDS does however manage collective attributes using subentries. An AP that
+takes the administrativeRole for managing collective attributes can have
+subentries added. These subentries are described in greater detail
+here:
+          <a href="./collective.html">Collective</a>
+. In short, collective attributes added to subentries show up within entries
+included by the subtreeSpecification. Adding, removing, and modifying the values
+of collective attributes within the subentries instantly manifest changes in the
+entries selected by the subtreeSpecification. Again
+consult
+          <a href="./collective.html">Collective</a>
+for a hands on explanation of how to use this
+feature.
+        </p>
+        <p>
+ApacheDS performs access control and allows delegation using subentries, AAAs,
+and IAAs. ApacheDS uses the Basic Access Control Scheme from X.501 to manage
+access control. By default this subsystem is deactivated because it locks down
+everything except access by the admin. More information about hands on use is
+available
+here:
+          <a href="./authorization.html">Authorization</a>
+. However to summarize its association with subentries, access control
+information (ACI) can be added to subentries under an AP for access control AAs.
+When one or more ACI are added in this fashion, the access rules of the ACI set
+apply to all entries selected by the subtreeSpecification. Even with this
+powerful feature individual entries can have ACI added to them for controlling
+access to them. Also there are things you can do with ACI added to subentries
+that cannot be done with entry level ACI. For example you cannot allow entry
+addition with entry ACI. You must use subtreeSpecifications to define where
+entries may be added because those entries and their parents may not exist
+yet.
+        </p>
+      </subsection>
+      <subsection heading="h3" name="How to specify a subentry's subtreeSpecification">
+        <p>
+The best way to demonstrate subtreeSpecification values are through examples.
+Here's the simplest filter of them
+all:</p>
+        <source>{}
+</source>
+        <p>
+This basically selects the entire contiguous subtree below the AP. The base is
+the empty name and it's rooted at the
+AP.</p>
+        <p>
+Next step let's add a
+base:</p>
+        <source>{ base "ou=users" }
+</source>
+        <p>
+If this is the subtreeSpecification under the AP, 'ou=system', then it selects
+every entry under
+'ou=users,ou=system'.</p>
+        <p>
+OK that was easy so now let's slice and dice the tree now using the minimum and
+maximum chop
+parameters.</p>
+        <source>{ minimum 3, maximum 5 }
+</source>
+        <p>
+This selects all entries below 'ou=system' which have a DN size equal to 3 name
+components, but no more than 5. So for example 'uid=jdoe,ou=users,ou=system'
+would be included but 'uid=jack,ou=do,ou=not,ou=select,ou=users,ou=system' would
+not be included. Let's continue and combine the base with just a minimum
+parameter:</p>
+        <source>{ base "ou=users", minimum 4 }
+</source>
+        <p>
+Here the subtree starts at 'ou=users,ou=system' if the subentry subordinates to
+the AP at 'ou=system'. The user 'uid=jdoe,ou=deepenough,ou=users,ou=system' is
+selected by the spec where as 'uid=jbean,ou=users,ou=system' is
+not.</p>
+        <p>
+It's time to add some chop
+exclusions:</p>
+        <source>{ 
+  base "ou=users", 
+  minimum 4, 
+  specificExclusions { chopBefore: "ou=untrusted" } 
+}
+</source>
+        <p>
+Again if placed at the AP 'ou=system' this subtree would begin at
+'ou=users,ou=system'. It would not include users that subordinate to it though
+because of the minimum constraint since these users would have 3 components in
+their DN. The specific exclusions prevent 'ou=untrusted,ou=users,ou=system' and
+all its descendants from being included in the collection. However
+'uid=jbean,ou=trusted,ou=users,ou=system' would be included since it meets the
+minimum requirement, is a descendant of 'ou=users,ou=system' and is not under
+the excluded DN,
+'ou=untrusted,ou=users,ou=system'.</p>
+        <p>
+Note that you can add as many exclusions as you like by comma delimiting them.
+For
+example:</p>
+        <source>{ 
+  base "ou=users", 
+  minimum 4, 
+  specificExclusions { chopBefore: "ou=untrusted", chopAfter: "ou=ugly", chopBefore: "ou=bad" } 
+}
+</source>
+        <p>
+The final example includes a refinement. Again any combination of chop, filter
+and base parameters can be used. The following refinement makes sure the users
+selected are of the objectClass inetOrgPerson and specialUser where the OID for
+the specialUser class is 32.5.2.1
+(fictitious).</p>
+        <source>{ 
+  base "ou=users", 
+  minimum 4, 
+  specificExclusions { chopBefore: "ou=untrusted", chopAfter: "ou=ugly", chopBefore: "ou=bad" }
+  specificationFilter and:{ item:32.5.2.1, item:inetOrgPerson } 
+}
+</source>
+        <p>
+If you'd like to see the whole specification of the grammar used for the
+subtreeSpecification take a look at Appendix A
+in
+          <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a>
+.
+        </p>
+      </subsection>
     </section>
-    <section heading="h2" name="Looking Ahead">
+    <section heading="h2" name="Future Possibilities">
       <p>
-It's a safe bet to partition the SubtreeSpecification cache based on the naming
-context of a subentry.  However better results may be achieved by partitioning
-the cache based on administrative areas and their roles.  An approach here is
-yet to be
-determined.</p>
+In the immediate future we intend to
+introduce
+        <a href="./triggers.html">Triggers</a>
+, stored procedures and views into ApacheDS. Subentries will play a critical
+role in the administration and application of these features. For example a
+Trigger specification need not include information on what entries it applies to
+since the subtreeSpecification handles this. The question of "on what" a trigger
+applies to is nicely disassociated from the "which operation" part of the
+specification. This makes for much better reuse of triggers. It also allows for
+the pin point application of triggers to entries in the DIT. Likewise a view
+itself will be defined by a specification. A view for example in a subentry can
+define a region of the tree that does not exist but is shadowed from another
+region all together. The possibilities here are
+limitless.
+      </p>
+      <p>
+Of course we will revamp the schema subsystem of ApacheDS to use subentries in
+AAA to manage the schema in effect within different regions of the DIT. Today
+most LDAP servers just have a global scheme in effect for the entire DIT served
+by a DSA. We don't think that is reasonable at all. So expect some serious
+advances in the design of a new schema subsystem based on
+subentries.</p>
+      <p>
+Replication is yet another excellent candidate for using subentries. Replication
+of specific collections of entries can be managed for each cluster rather than
+replicating the entire DIT served by a DSA to replicas. This way we don't only
+control what is replicated but we can also control how and where it is
+replicated.</p>
     </section>
-    <section heading="h2" name="Grammar used to implement SubtreeSpecification">
+    <section heading="h2" name="Conclusions">
       <p>
-Take a look at the subtree specification grammar
-here
-        <a href="./subtreespecificationgrammar.html">SubtreeSpecificationGrammar</a>
-.
+ApacheDS has implemented subentries for the administration of various aspects of
+the directory and gains several powerful features as a result: namely precision
+application of control to entry collections and the ability to delegate
+administrative authority. For details on the administration of each aspect using
+subentries
+(
+        <a href="./collective.html">Collective</a>
+and
+        <a href="./authorization.html">Authorization</a>
+) please see the respective
+documentation.
       </p>
+      <p>
+As ApacheDS progresses it will gain an immense advantage from subentries. Both
+for existing LDAP features like scheme and for new experimental features like
+triggers, and
+replication.</p>
     </section>
   </body>
 </document>

Modified: directory/apacheds/trunk/xdocs/users/userclasses.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/userclasses.xml?rev=329780&r1=329779&r2=329780&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/userclasses.xml (original)
+++ directory/apacheds/trunk/xdocs/users/userclasses.xml Mon Oct 31 01:20:32 2005
@@ -3,7 +3,7 @@
 <document>
   <properties>
     <author email="akarasulu">akarasulu</author>
-    <title>User Classes</title>
+    <title>UserClasses</title>
   </properties>
   <body>
     <section heading="h2" name="What are User Classes?">
@@ -80,12 +80,21 @@
 *uniqueMember* attributes whose values are the DN of user entries are present
 within the entry to represent membership within the
 group.</p>
-      <p>
+      <table>
+        <tr>
+          <td>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+          </td>
+          <td>
+            <p>
 Although such group entries can be added anywhere within the DIT to be
 recognized by the Authorization subsystem, a recommended convention exists.  Use
 the ou=groups container under a namingContext/partition within the server to
 localize groups.  Most of the time group information can be stored under
 ou=groups,ou=system.</p>
+          </td>
+        </tr>
+      </table>
       <p>
 Just like the *name* construct, the *userGroup* construct takes a single
 parameter: the DN of the group entry.  During ACI evaluation ApacheDS checks to
@@ -110,11 +119,20 @@
         <a href="./subentries.html">Subentries</a>
 .
       </p>
-      <p>
+      <table>
+        <tr>
+          <td>
+            <img src="http://docs.safehaus.org/images/icons/emoticons/warning.png"/>
+          </td>
+          <td>
+            <p>
 For this purpose a subtree is not refined.  Meaning it does not evaluate
 refinement filters.  This is to restrict the information needed to make a
 determination to just the DN of the requestor and not the entry of the
 requestor.</p>
+          </td>
+        </tr>
+      </table>
     </section>
     <section heading="h2" name="Combining Multiple UserClass Specification Mechanisms">
       <p>

Added: directory/apacheds/trunk/xdocs/users/userpermissions.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/userpermissions.xml?rev=329780&view=auto
==============================================================================
--- directory/apacheds/trunk/xdocs/users/userpermissions.xml (added)
+++ directory/apacheds/trunk/xdocs/users/userpermissions.xml Mon Oct 31 01:20:32 2005
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>UserPermissions</title>
+  </properties>
+  <body>
+    <p>
+Coming soon
+...</p>
+  </body>
+</document>



Mime
View raw message