directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: r329722 [1/2] - in /directory/apacheds/trunk/xdocs: ./ users/
Date Mon, 31 Oct 2005 04:00:43 GMT
Author: akarasulu
Date: Sun Oct 30 20:00:37 2005
New Revision: 329722

URL: http://svn.apache.org/viewcvs?rev=329722&view=rev
Log:
committing doco generated from confluence to xdoc converter

Added:
    directory/apacheds/trunk/xdocs/users/userclasses.xml
Modified:
    directory/apacheds/trunk/xdocs/navigation.xml
    directory/apacheds/trunk/xdocs/users/authentication.xml
    directory/apacheds/trunk/xdocs/users/authorization.xml
    directory/apacheds/trunk/xdocs/users/building.xml
    directory/apacheds/trunk/xdocs/users/collective.xml
    directory/apacheds/trunk/xdocs/users/configuration.xml
    directory/apacheds/trunk/xdocs/users/index.xml
    directory/apacheds/trunk/xdocs/users/partitions.xml
    directory/apacheds/trunk/xdocs/users/plugin.xml

Modified: directory/apacheds/trunk/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/navigation.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/navigation.xml (original)
+++ directory/apacheds/trunk/xdocs/navigation.xml Sun Oct 30 20:00:37 2005
@@ -28,7 +28,7 @@
         <item name="Authorization" href="/users/aci.html"/>
         <item name="Subentries" href="/users/subentries.html"/>
         <item name="Collective Attributes" href="/users/collective.html"/>
-        <item name="JNDI Properties" href="/users/jndi.html"/>
+        <item name="Configuration" href="/users/configuration.html"/>
         <item name="Partitions" href="/users/partitions.html"/>
         <item name="Maven Plugin" href="/users/plugin.html"/>
       </item>

Modified: directory/apacheds/trunk/xdocs/users/authentication.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/authentication.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/authentication.xml (original)
+++ directory/apacheds/trunk/xdocs/users/authentication.xml Sun Oct 30 20:00:37 2005
@@ -1,76 +1,95 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Server Authentication</title>
+    <author email="akarasulu">akarasulu</author>
+    <title>Authentication</title>
   </properties>
-  
   <body>
-
-    <section name="Server Authentication">
-      <subsection name="Status">
-        <p>
-          Presently the directory server supports only simple authentication
-          and anonymous binds while storing passwords in clear text within
-          userPassword attributes in user entries.
-        </p>
-
-        <p>
-          Within a short while we'll be able to store passwords using the
-          authPassword property which uses strong one way hashes for
-          authentication such as MD5 and SHA1.  These schemes and the schema
-          used are described in detail here in <a href=
-          "http://www.faqs.org/rfcs/rfc3112.html">RFC 3112</a>.
-        </p>
-      </subsection>
-
-      <subsection name="What password do I use?">
-        <p>
-          So you just downloaded the server and fired her up.  Now you're
-          wondering how to get an LDAP client like jxplorer, gq, or ldapbrowser
-          to bind to the server over the wire.
-        </p>
-
-        <p>
-          By default the super user or admin account is created when the system
-          partition is created under the ou=system naming context.  This occurs
-          when the server is started for the first time.  The admin user can be
-          found under the following DN:
-        </p>
-
-        <source>
-          uid=admin,ou=system
-        </source>
-
-        <p>
-          The password is initially set to <b>secret</b>.  You might want to
-          change this after starting the server.  So you can bind to the server
-          as this user with <b>secret</b> as the password for the first time.
-        </p>
-
-        <p>
-          If you did not disable anonymous binds by setting the respective
-          property (described below), then you can bind anonymously to the
-          server without any username or password. NOTE: Even when anonymous
-          binds are disabled anonymous users can still bind to the RootDSE
-          as required by the protocol to lookup supported SASL mechanisms 
-          before attempting a bind.
-        </p>
-      </subsection>
-
-      <subsection name="Adding and authenticating normal users">
-        <p>
-          A user in the server is any entry with a userPassword attribute that
-          contains a clear text password.  The DN can be anything reachable
-          within one of the directory partitions.  So if you add a partition to
-          hang off of <code>dc=example,dc=com</code> then you can add user
-          entries anywhere under this naming context or just add user entries
-          under the <code>ou=system</code> naming context.  Below is an LDIF of
-          a user you can add to the directory as a test user.
-        </p>
-
-        <source>
-dn: uid=jdoe,ou=users,ou=system
+    <section heading="h2" name="Server Authentication">
+      <p>
+This page
+describes:</p>
+      <ol nesting="0">
+        <li>
+the status of
+authentication,</li>
+        <li>
+how to bind (authenticate) as the admin superuser after starting the server the
+first
+time,</li>
+        <li>
+adding non-superusers and binding to the directory as
+them,</li>
+        <li>
+how to protect user
+passwords,</li>
+        <li>
+how to disable anonymous
+binds,</li>
+        <li>
+how to customize the server to use different authentication
+mechanisms.</li>
+      </ol>
+      <subsection heading="h3" name="Status">
+        <p>
+Presently the directory server supports only simple authentication and anonymous
+binds while storing passwords in clear text within userPassword attributes in
+user
+entries.</p>
+        <p>
+Within a short while we'll be able to store passwords using the authPassword
+property which uses strong one way hashes for authentication such as MD5 and
+SHA1. These schemes and the schema used are described in detail here
+in
+          <a href="http://www.faqs.org/rfcs/rfc3112.html">RFC 3112</a>
+.
+        </p>
+      </subsection>
+      <subsection heading="h3" name="How do I bind as the admin superuser after initial startup?">
+        <p>
+You just downloaded the server and started it up for the first time. Now you're
+wondering how to bind to the server using an LDAP client like jxplorer, gq, or
+ldapbrowser.</p>
+        <p>
+By default the super user or admin account is created when the system partition
+is created under the ou=system naming context. This occurs when the server is
+started for the first time. The admin user can be found under the following
+DN:</p>
+        <source>          uid=admin,ou=system
+</source>
+        <p>
+The password is initially set to 'secret'. You definately want to change this
+after starting the server.  For the first time you can bind to the server as
+this user with 'secret' as the
+password.</p>
+        <p>
+To change the password for the admin user you'll have to make changes to two
+places.  First you'll have to change the password in the directory for the user.
+Second you'll have to change the password in the server.xml configuration file
+for the java.naming.security.credentials
+property.</p>
+        <p>
+If you did not disable anonymous binds by setting the respective property
+(described below), then you can bind anonymously to the server without any
+username or
+password.</p>
+        <p>
+Even when anonymous binds are disabled anonymous users can still bind to the
+RootDSE as required by the protocol to lookup supported SASL mechanisms before
+attempting a bind.  Don't worry the RootDSE is read
+only.</p>
+      </subsection>
+      <subsection heading="h3" name="Adding and authenticating normal users">
+        <p>
+By default a user in the server can be just about any entry with a userPassword
+attribute that contains a clear text password. The DN can be anything reachable
+within one of the directory partitions. So if you add a partition to hang off of
+dc=example,dc=com then you can add user entries anywhere under this naming
+context or just add user entries under the ou=system naming context. Below is an
+LDIF of a user you can add to the directory as a test
+user.</p>
+        <source>dn: uid=jdoe,ou=users,ou=system
 cn: John Doe
 sn: Doe
 givenname: John
@@ -87,106 +106,73 @@
 facsimiletelephonenumber: +1 408 555 5556
 roomnumber: 4613
 userpassword: test
-        </source>
-
-        <p>
-          You can download this <a href="newuser.ldif">newuser.ldif</a> file and
-          use it to add the user.  If you are lazy another test user, <code>
-          uid=akarasulu, ou=users, ou=system</code> already exists within the
-          directory.  It is created by default.  Simply replace jdoe's DN with
-          akarasulu's DN to search for this user and bind as this user.  Below
-          we use the ldapadd OpenLDAP client to import the LDIF file presuming
-          the server was started on port 1024 on the localhost:
-        </p>
-
-        <source>
-ldapadd -a -D 'uid=admin,ou=system' -f newuser.ldif -h localhost -p 1024 -x -w secret
-        </source>
-
+</source>
         <p>
-          You can confirm the add/import by performing a search for the user.
-          This time using the OpenLDAP search client you use the following
-          command:
-        </p>
-
-        <source>
-ldapsearch -D 'uid=admin,ou=system' -h localhost -p 1024 -x -w secret -s one
+You can download
+this
+          <a href="./newuser.ldif.html">newuser.ldif</a>
+file and use it to add the user. Below we use the ldapadd OpenLDAP client to
+import the LDIF file presuming the server was started on port 1024 on the
+localhost:
+        </p>
+        <source>ldapadd -a -D 'uid=admin,ou=system' -f newuser.ldif -h localhost -p 1024 -x -w secret
+</source>
+        <p>
+You can confirm the add/import by performing a search for the user. This time
+using the OpenLDAP search client you use the following
+command:</p>
+        <source>ldapsearch -D 'uid=admin,ou=system' -h localhost -p 1024 -x -w secret -s one
     -b 'ou=users,ou=system' '(uid=jdoe)'
-        </source>
-
-        <p>
-          You can start searching the directory using this new user like so:
-        </p>
-
-        <source>
-ldapsearch -D 'uid=jdoe,ou=users,ou=system' -h localhost -p 1024 -x -w test -s one -b 'ou=system' '(objectClass=*)'
-        </source>
-
-      </subsection>
-
-      <subsection name="Protecting User Passwords">
-        <p>
-          At the moment there's a sweet spot for new users.  This sweet
-          spot is immediately under the ou=users,ou=system context.  Users
-          created here are hard protected right now.  As of 0.9.3 an 
-          implementation of X.501 basic access controls are available however
-          the system is not turned on by default.  Turning it on presumes 
-          access is denied to all but the admin.  More information on this is
-          available in the access control page.  When the access control 
-          subsystem is not activated hardcoded minimal access controls are
-          used to protect the admin account, users and groups under respective
-          containers in the ou=system partition. 
-        </p>
+</source>
         <p>
-          In the absense of the ACI subsystem, authorization rules have been 
-          hardcoded into the system to control access to user entries under 
-          <code>ou=users,ou=system</code>.  Only the admin and the user 
-          him/her self can access their entries for reads.  Users cannot 
-          modify their group membership properties but can change their own 
-          passwords.  They do not see each other's accounts at all.  The admin 
-          is the only one that can read and write anything.
-        </p>
-
-        <p>
-          So in the interim you're best off adding your users to this area to
-          prevent others from reading clear text passwords stored in 
-          userPassword fields.  If using a release with hashed passwords we 
-          highly discourage the use of clear text passwords.
-        </p>
-
-        <p>
-          Note that anonymous binds and binds as users show different
-          views of the ou=system naming context.  So don't freak out if you
-          don't see the usual suspects when binding anonymously!  Anonymous
-          users cannot see the admin account or any other user accounts.  Users
-          other than admin cannot see the admin account and can only see one
-          user account: their own.  The admin sees everything and can alter or
-          remove any entry.
-        </p>
-      </subsection>
-
-      <subsection name="Disabling Anonymous Binds">
-        <p>
-          Anonymous binds come enabled out of the box.  So you might want to
-          turn off this feature especially if you're not using a version of 
-          ApacheDS that is 0.9.3 or higher with ACI support. 
-          To do so you're going to have to restart the server while disallowing
-          these binds.  In the server.xml that comes with the distribution 
-          take a look at the <b>allowAnonymousAccess</b> property for the
-          server startup configuration.
-        </p>
-      </subsection>
-
-      <subsection name="Custom Authenticator">
-        <p>
-          Authenticator SPI provides a way to implement your own 
-          authentication mechanism, for instance simple mechanism using 
-          password encryption such as MD5 or SHA1, or SASL mechanism. See the 
-          following example:
-        </p>
-
-        <source>
-import javax.naming.NamingException;
+You can start searching the directory using this new user like
+so:</p>
+        <source>ldapsearch -D 'uid=jdoe,ou=users,ou=system' -h localhost -p 1024 -x -w test -s one -b 'ou=system' '(objectClass=*)'
+</source>
+      </subsection>
+      <subsection heading="h3" name="Protecting user passwords">
+        <p>
+Without access controls enabled userPasswords and user entries are accessible
+and alterable by all: even anonymous users.  There are however some minimal
+built-in rules for protecting users and groups within the server without having
+to turn on the ACI
+subsystem.</p>
+        <p>
+Without ACIs the server automatically protects, hides, the admin user from
+everyone but the admin user.  Users cannot see other user entries under the
+'ou=users,ou=system' entry.  So placing new users there automatically protects
+them.  Placing new users anywhere else exposes them.  Groups defined using
+groupOfNames or groupOfUniqueNames under the 'ou=groups,ou=system' are also
+protected from access or alteration by anyone other than the admin user.  Again
+this protection is not allowed anywhere else but under these
+entries.</p>
+        <p>
+For simple configurations this should provide adequate protection but it lacks
+flexibility.  For advanced configurations users should enable the ACI subsystem.
+This however shuts down access to everything by everyone except the admin user
+which bypasses the ACI subsystem.  Directory administrators should look at the
+docomentation on how to specify access control information
+here:
+          <a href="./authorization.html">Authorization</a>
+.
+        </p>
+      </subsection>
+      <subsection heading="h3" name="Disabling anonymous binds">
+        <p>
+Anonymous binds come enabled out of the box. So you might want to turn off this
+feature especially if you're not using a version of ApacheDS that is 0.9.3 or
+higher with ACI support. To do so you're going to have to restart the server
+after settting the allowAnonymousAccess property to false in the server.xml
+configuration
+file.</p>
+      </subsection>
+      <subsection heading="h3" name="Using custom authenticators">
+        <p>
+Authenticator SPI provides a way to implement your own authentication mechanism,
+for instance simple mechanism using password encryption such as MD5 or SHA1, or
+SASL mechanism. See the following
+example:</p>
+        <source>import javax.naming.NamingException;
 
 import org.apache.ldap.server.auth.AbstractAuthenticator;
 import org.apache.ldap.server.auth.LdapPrincipal;
@@ -216,59 +202,48 @@
         return new LdapPrincipal( principalDn );
     }
 }
-          </source>
-
-          <p>
-            The authenticator class has to extend the 
-            org.apache.ldap.server.auth.AbstractAuthenticator.  This class 
-            needs to have a no-argument constructor that calls the super()
-            constructor with parameter the authentication mechanism it is 
-            going to handle.  In the above example, MyAuthenticator class is 
-            going to handle the simple authentication mechanism. To implement 
-            a SASL mechanism you need to call super() with the name of the 
-            SASL mechanism, e.g. super( "DIGEST-MD5" ).
-          </p>
-
-          <p>
-            You can optionally implement the init() method to initialize your 
-            authenticator class.  This will be called when the authenticator 
-            is loaded by ApacheDS during start-up.
-          </p>
-
-          <p>
-            When a client performs an authentication, ApacheDS will call the 
-            authenticate() method.  You can get the client authentication info 
-            from the server context. After you authenticate the client, you 
-            need to return the authorization id. If the authentication fails, 
-            you should throw an LdapNoPermissionException.
-          </p>
-
-          <p>
-            When there are multiple authenticators registered with the same 
-            authentication type, ApacheDS will try to use them in the order 
-            it was registered. If one fails it will use the next one, until it 
-            finds one that successfully authenticates the client.
-          </p>
-
-          <p>
-            To tell ApacheDS to load your custom authenticators, you need to 
-            specify it in the server.xml. You can also optionally specify the 
-            location of a .properties file containing the initialization 
-            parameters. See the following example:
-          </p>
-
-          <p>EXAMPLE BELOW IS NO LONGER VALID WITH XML CONFIGURATION</p>
-          <source>
-server.authenticators=myauthenticator yourauthenticator
+</source>
+        <p>
+The authenticator class has to extend the
+org.apache.ldap.server.auth.AbstractAuthenticator. This class needs to have a
+no-argument constructor that calls the super() constructor with parameter the
+authentication mechanism it is going to handle. In the above example,
+MyAuthenticator class is going to handle the simple authentication mechanism. To
+implement a SASL mechanism you need to call super() with the name of the SASL
+mechanism, e.g. super( "DIGEST-MD5"
+).</p>
+        <p>
+You can optionally implement the init() method to initialize your authenticator
+class. This will be called when the authenticator is loaded by ApacheDS during
+start-up.</p>
+        <p>
+When a client performs an authentication, ApacheDS will call the authenticate()
+method. You can get the client authentication info from the server context.
+After you authenticate the client, you need to return the authorization id. If
+the authentication fails, you should throw an
+LdapNoPermissionException.</p>
+        <p>
+When there are multiple authenticators registered with the same authentication
+type, ApacheDS will try to use them in the order it was registered. If one fails
+it will use the next one, until it finds one that successfully authenticates the
+client.</p>
+        <p>
+To tell ApacheDS to load your custom authenticators, you need to specify it in
+the server.xml. You can also optionally specify the location of a .properties
+file containing the initialization parameters. See the following
+example:</p>
+        <p>
+EXAMPLE BELOW IS NO LONGER VALID WITH XML
+CONFIGURATION</p>
+        <source>server.authenticators=myauthenticator yourauthenticator
 
 server.authenticator.class.myauthenticator=com.mycompany.MyAuthenticator
 server.authenticator.properties.myauthenticator=myauthenticator.properties
 
 server.authenticator.class.yourauthenticator=com.yourcompany.YourAuthenticator
 server.authenticator.properties.yourauthenticator=yourauthenticator.properties
-          </source>
+</source>
       </subsection>
-
     </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=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/authorization.xml (original)
+++ directory/apacheds/trunk/xdocs/users/authorization.xml Sun Oct 30 20:00:37 2005
@@ -1,36 +1,178 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Access Controls</title>
+    <author email="akarasulu">akarasulu</author>
+    <title>Authorization</title>
   </properties>
-  
   <body>
-
-    <section name="Access Control">
-      <subsection name="Status">
+    <p>
+ApacheDS uses an adaptation of the X.500 basic access control scheme in
+combination with X.500 subentries to control access to entries and attributes
+within the DIT. This document will show you how to enable the basic access
+control mechanism and how to define access control information to manage access
+to protected
+resources.</p>
+    <section heading="h2" name="Enabling Basic Access Controls">
+      <p>
+By default the access control subsystem is turned off. Once enabled everything
+is tightly locked down. Only the special admin user, '*uid=admin,ou=system*', is
+not affected by permissions. Access to all operations are denied by default
+until enabled using an ACIItem. For this reason enabling basic access controls
+is a configuration
+option.</p>
+      <p>
+To turn on the basic access control mechanism you need to set the
+*accessControlEnabled* property in the configuration to true. This can be set
+programatically on the StartupConfiguration or via the
+server.xml.</p>
+    </section>
+    <section heading="h2" name="Types of ACI (Access Control Information)">
+      <p>
+Three different types of ACI exist. All types use the same specification syntax
+for an ACIITem. These types differ in their placement and manner of use within
+the
+directory.</p>
+      <subsection heading="h3" name="Entry ACI">
         <p>
-        </p>
-
+Entry ACI are access controls added to entries to protect that entry
+specifically. Meaning the protoected entry is the entry where the ACI resides.
+When performing an operation on an entry, ApacheDS checks for the presence of
+the multivalued operational attribute, *entryACI*. The values of the entryACI
+attribute contain
+ACIItems.</p>
         <p>
-        </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>
       </subsection>
-
-      <subsection name="Default Settings">
+      <subsection heading="h3" name="Prescriptive ACI">
         <p>
-        </p>
-      </subsection>
-
-      <subsection name="X.501 Basic Access Controls">
+Prescriptive ACI are access controls that are applied to a collection of
+entries, not just to a single entry. Collections of entries are defined by the
+subtreeSpecifications of subentries. Hence prescriptive ACI are added to
+subentries as attributes and are applied by ApacheDS to the entries selected by
+the subentry's subtreeSpecification. ApacheDS uses the *prescriptiveACI*
+multivalued operational attribute within subentries to contain ACIItems that
+apply to the entry
+collection.</p>
+        <p>
+Prescriptive ACI can save much effort when trying to control access to a
+collection of resources. Prescriptive ACI can even be specified to apply access
+controls to entries that do not yet exist within the DIT. They are a very
+powerful mechanism and for this reason they are the prefered mechanism for
+managing access to protected resources. ApacheDS is optimized specifically for
+managing access to collections of entries rather than point entries
+themselves.</p>
         <p>
-        </p>
+Users should try to avoid entry ACIs whenever possible, and use prescriptive
+ACIs instead. Entry ACIs are more for managing exceptional cases and should not
+be used
+excessively.</p>
+        <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>
+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>
       </subsection>
-
-      <subsection name="ACI Examples">
+      <subsection heading="h3" name="Subentry ACI">
         <p>
-        </p>
+Access to subentries also needs to be controlled. Subentries are special in
+ApacheDS. Although they subordinate to an administrative entry (entry of an
+Administrative Point), they are technically considered to be in the same context
+as their administrative entry. ApacheDS considers the perscriptive ACI applied
+to the administrative entry, to also apply to its
+subentries.</p>
+        <p>
+This however is not the most intuitive mechanism to use for explicitly
+controlling access to subentries. A more explicit mechanism is used to specify
+ACIs specifically for protecting subentries. ApacheDS uses the multivalued
+operational attribute, *subentryACI*, within administrative entries to control
+access to immediately subordinate
+subentries.</p>
+        <p>
+Protection policies for ACIs themselves can be managed within the entry of an
+administrative
+point.</p>
       </subsection>
-
+    </section>
+    <section heading="h2" name="Some Simple Examples">
+      <p>
+The ACIItem syntax is very expressive and that makes it extremely powerful for
+specifying complex access control policies. However the syntax is not very easy
+to grasp for beginners. For this reason we start with simple examples that focus
+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>
+          <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>
+Protecting access to subentries
+themselves.</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>
+Granting add, delete, and modify permissions to a group of
+users.</td>
+        </tr>
+        <tr>
+          <td>
+            <a href="./grantmodtoentry.html">GrantModToEntry</a>
+          </td>
+          <td>
+Applying ACI to a single
+entry.</td>
+        </tr>
+      </table>
     </section>
   </body>
 </document>

Modified: directory/apacheds/trunk/xdocs/users/building.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/building.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/building.xml (original)
+++ directory/apacheds/trunk/xdocs/users/building.xml Sun Oct 30 20:00:37 2005
@@ -1,101 +1,97 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<document>
-  <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Apache Directory Project: Building the Directory Server</title>
-  </properties>
-  
-  <body>
-    <section name="Building and Running the Apache Directory Server">
-      <p>
-        All directory projects use <a href="http://maven.apache.org">Maven</a>
-        as the default build tool.  We try to remain current with the production
-        version of Maven.  As of 12/04 we use Maven 1.0.2 on JDK 1.4 and up.
-      </p>
-
-      <p>
-        The multiproject plugin is used to build all the maven projects
-        associated with the server.  After checking out the server trunk from
-        subversion, cd into it and run the following multiproject command:
-      </p>
-
-      <source>
-maven multiproject:install
-      </source>
-
-      <p>
-        Once you've built the server you'll find an executable jar file under
-        the main/target directory labeled apacheds-main-${version}.jar which can
-        be fired up like so:
-      </p>
-
-<source>
-java -jar main/target/apacheds-main-${version}.jar server.xml
-</source>
-
-      <p>
-        When you start the server without a xml conf file arguement default
-        settings are used.  It tries to bind to 389 but this non-root user
-        does not have the needed privledges so it tries to bind on the next
-        available port which is 1024.  You may like a conf file that can
-        be used to override and set server specific properties to control her
-        behavoir.  Below we use the <a href="http://valpithy.notlong.com">
-        xml configuration</a> file that comes preconfigured for Apache under 
-        the server/trunk/main directory:
-      </p>
-
-<source>
-java -jar main/target/apacheds-main-${version}.jar main/server.xml
-</source>
-    </section>
-
-    <section name="Apache Directory Server's Maven Modules">
-      <p>
-        The server is composed of 4 separate maven projects.  These projects are
-        summarized below:
-      </p>
-
-      <table>
-        <tr>
-          <th>Project</th><th>Summary</th>
-        </tr>
-
-        <tr>
-          <td>protocol</td>
-          <td>Contains an LDAP protocol provider for the SEDA framework.</td>
-        </tr>
-        <tr>
-          <td>plugin</td>
-          <td>Contains a maven plugin used while developing with/for the
-              directory server.</td>
-        </tr>
-        <tr>
-          <td>core</td>
-          <td>
-            Contains the server's core which contains the JNDI Provider that
-            wraps/is the backend subsystem.
-          </td>
-        </tr>
-        <tr>
-          <td>shared</td>
-          <td>Contains shared classes between modules to prevent cyclic deps.</td>
-        </tr>
-        <tr>
-          <td>main</td>
-          <td>
-            Contains the ApacheDS application <code>main()</code> along with
-            a special InitialContextFactory implemenation that extends the
-            CoreContextFactory ICF.  This ICF is the ServerContextFactory and
-            it initializes MINA adding the LDAP protocol provider as well as 
-            the other providers for protocols like Kerberos, Change Password,
-            NTP, DNS and DHCP.  Of course the configuration determines if
-            these protocols are started or not.  All protocols with the 
-            exception of NTP use the core LDAP store as their backing store
-            with custom schema.
-          </td>
-        </tr>
-      </table>
-    </section>
-    
-  </body>
-</document>
+<?xml version="1.0" encoding="UTF-8"?>
+
+<document>
+  <properties>
+    <author email="akarasulu">akarasulu</author>
+    <title>Building</title>
+  </properties>
+  <body>
+    <section heading="h2" name="Building and Running the Apache Directory Server">
+      <p>
+All directory projects
+use
+        <a href="http://maven.apache.org">Maven</a>
+as the default build tool. We try to remain current with the production version
+of Maven. As of 12/04 we use Maven 1.0.2 on JDK 1.4 and
+up.
+      </p>
+      <p>
+The multiproject plugin is used to build all the maven projects associated with
+the server. After checking out the server trunk from subversion, cd into it and
+run the following multiproject
+command:</p>
+      <source>maven multiproject:install
+</source>
+      <p>
+Once you've built the server you'll find an executable jar file under the
+main/target directory labeled apacheds-main-$version.jar which can be fired up
+like
+so:</p>
+      <source>java -jar main/target/apacheds-main-$version.jar server.xml
+</source>
+      <p>
+When you start the server without a xml conf file arguement default settings are
+used. It tries to bind to 389 but this non-root user does not have the needed
+privledges so it tries to bind on the next available port which is 1024. You may
+like a conf file that can be used to override and set server specific properties
+to control its behavoir. Below we use
+the
+        <a href="http://valpithy.notlong.com/">xml configuration</a>
+file that comes preconfigured for Apache under the server/trunk/main
+directory:
+      </p>
+      <source>java -jar main/target/apacheds-main-${version}.jar main/server.xml
+</source>
+    </section>
+    <section heading="h2" name="Apache Directory Server's Maven Modules">
+      <p>
+The server is composed of 4 separate maven projects.  These projects are
+summarized
+below:</p>
+      <table>
+        <tr>
+          <th>
+Project</th>
+          <th>
+Summary</th>
+        </tr>
+        <tr>
+          <td>
+core</td>
+          <td>
+The heart of the server which contains the JNDI Provider, interceptors,
+partitions and
+schema.</td>
+        </tr>
+        <tr>
+          <td>
+shared</td>
+          <td>
+Contains shared classes between modules to prevent cyclic
+deps.</td>
+        </tr>
+        <tr>
+          <td>
+plugin</td>
+          <td>
+Contains a maven plugin used while developing with/for the directory
+server.</td>
+        </tr>
+        <tr>
+          <td>
+main</td>
+          <td>
+Contains the ApacheDS application main() along with a special
+InitialContextFactory implemenation that extends the CoreContextFactory which is
+an InitialContextFactory implementation (ICF). This ICF is the
+ServerContextFactory and it initializes MINA adding the LDAP protocol provider
+as well as the other providers for protocols like Kerberos, Change Password,
+NTP, DNS and DHCP. Of course the configuration determines if these protocols are
+started or not. All protocols with the exception of NTP use the core LDAP store
+as their backing store with custom
+schema.</td>
+        </tr>
+      </table>
+    </section>
+  </body>
+</document>

Modified: directory/apacheds/trunk/xdocs/users/collective.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/collective.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/collective.xml (original)
+++ directory/apacheds/trunk/xdocs/users/collective.xml Sun Oct 30 20:00:37 2005
@@ -1,33 +1,239 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Collective Attributes</title>
+    <author email="akarasulu">akarasulu</author>
+    <title>Collective</title>
   </properties>
-  
   <body>
-
-    <section name="Collective Attributes">
-      <subsection name="What are collective attributes?">
+    <section heading="h2" name="Introduction">
+      <p>
+Collective attributes are attributes whose values are shared across a collection
+of entries. It's very common to encounter situations where a bunch of entries
+have the same value for an attribute. Collective attributes for LDAP are defined
+in
+        <a href="http://www.faqs.org/rfcs/rfc3671.html">RFC 3671</a>
+. ApacheDS implements this
+RFC.
+      </p>
+      <subsection heading="h3" name="Use Case">
         <p>
-        </p>
-      </subsection>
-
-      <subsection name="Collective Attribute Administrative Areas">
+For example one might organize everyone in an engineering department under an
+ou, 'ou=engineering'. If the engineering team is located in the same area and
+building then several attributes in each user entry within engineering will have
+the same value. An example of such an attribute would be the locale. If
+engineering is located in Sunnyvale CA then all locale attributes of entries
+under 'ou=engineering' would be set to
+Sunnyvale.</p>
         <p>
+Rather than manage the value for this attribute in each entry a single
+collective attribute can be used in a subentry. Changes to the value of this
+attribute would immediately be reflected to those entries selected by the
+subtreeSpecification of subentry. For more information on specifying subtrees
+take
+at
+          <a href="./subentries.html">Subentries</a>
+.
         </p>
       </subsection>
-
-      <subsection name="How ApacheDS Handles Collective Attributes">
+    </section>
+    <section heading="h2" name="Setting up a Collective Attribute Administration Area (AA)">
+      <p>
+To manage collective attributes for a collection of entries you must add
+collective subentries to the Administrative Point (AP) of the collective AA. For
+more information on AAs
+see
+        <a href="./subentries.html">Subentries</a>
+. These collective subentries must have the objectClass subentry as well as
+collectiveAttributeSubentry. Also the AP, of the AA, must have an
+administrativeRole value of collectiveAttributeSpecificArea (2.5.23.5) or
+collectiveAttributeInnerArea
+(2.5.23.6).
+      </p>
+      <subsection heading="h3" name="Example">
         <p>
-        </p>
-      </subsection>
+For the use case above we can presume a partition at the namingContext
+'dc=example,dc=com' with an 'ou=engineering' entry below containing users from
+the engineering team in Sunnyvale. Let's presume no AA has yet been defined so
+we have to create one. We'll set the partition root 'dc=example,dc=com' as the
+AP of an AA that spans the entire subtree. For this simple example the AA will
+be autonomous for the collective aspect. Setting this up is just a matter of
+modifying the 'dc=example,dc=com' entry so it contains the operational attribute
+administrativeRole with the value collectiveAttributeSpecificArea. The code
+below sets up this AAA for collective attribute
+administration.</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 );
 
-      <subsection name="Examples">
+  // Modify the entry to make it an AAA for collective attribute administration
+  Attributes mods = new BasicAttributes( "administrativeRole", "collectiveAttributeSpecificArea", true );
+  ctx.modifyAttributes( "", DirContext.ADD_ATTRIBUTE, mods );
+</source>
         <p>
-        </p>
+Now 'dc=example,dc=com' is the AP for a collective attribute AAA that spans the
+entire subtree under and including it down to every leaf entry. All that remains
+is the addition of the subentry with the collective attributes we want included
+in the entries of all engineering users. Here's what the LDIF would look like
+for this subentry given that its commonName is
+'engineeringLocale'.</p>
+        <source>dn: cn=engineeringLocale,dc=example,dc=com
+objectClass: top
+objectClass: subentry
+objectClass: collectiveAttributeSubentry
+cn: engineeringLocale
+c-l: Sunnyvale
+subtreeSpecification: {base "ou=engineering", minimum 4}
+</source>
+        <p>
+A couple points regarding this subentry's
+LDIF:</p>
+        <ol nesting="0">
+          <li>
+It subordinates to the AP
+('dc=example,dc=com')</li>
+          <li>
+It contains the objectClasses: subentry and
+collectiveAttributeSubentry</li>
+          <li>
+It contains the collective version of locale (l):
+c-l</li>
+          <li>
+Its subtreeSpecification excludes entries whose number of DN name components is
+is less than
+4</li>
+        </ol>
+        <p>
+Note that the minimum value of 4 is used in the subtreeSpecification to make
+sure that the entry 'ou=engineering,dc=example,dc=com' does not have c-l:
+Sunnyvale added to it. It's got 3 components to the DN so minimum 4 chops it out
+of the
+collection.</p>
       </subsection>
+    </section>
+    <section heading="h2" name="Collective Attribute Types">
+      <p>
+As one can see from the example above, special collective attributes are used
+for regular attributes: c-l for l. These attributes are derived from the
+original attribute and are marked as COLLECTIVE. RFC 3671 defines a bunch of
+these which are listed below. If you don't find what you're looking for just add
+it to your own schema using this
+pattern.</p>
+      <p>
+We have included this list from RFC 3671 into the collective.schema which comes
+standard with
+ApacheDS.</p>
+      <source>3.1. Collective Locality Name
+
+   The c-l attribute type specifies a locality name for a collection of
+   entries.
+
+      ( 2.5.4.7.1 NAME 'c-l'
+        SUP l COLLECTIVE )
+
+3.2. Collective State or Province Name
+
+   The c-st attribute type specifies a state or province name for a
+   collection of entries.
+
+      ( 2.5.4.8.1 NAME 'c-st'
+        SUP st COLLECTIVE )
+
+3.3. Collective Street Address
+
+   The c-street attribute type specifies a street address for a
+   collection of entries.
+
+      ( 2.5.4.9.1 NAME 'c-street'
+        SUP street COLLECTIVE )
+
+3.4. Collective Organization Name
+
+   The c-o attribute type specifies an organization name for a
+   collection of entries.
+
+      ( 2.5.4.10.1 NAME 'c-o'
+        SUP o COLLECTIVE )
+
+3.5. Collective Organizational Unit Name
+
+   The c-ou attribute type specifies an organizational unit name for a
+   collection of entries.
+
+      ( 2.5.4.11.1 NAME 'c-ou'
+        SUP ou COLLECTIVE )
+
+3.6. Collective Postal Address
+
+   The c-PostalAddress attribute type specifies a postal address for a
+   collection of entries.
+
+      ( 2.5.4.16.1 NAME 'c-PostalAddress'
+        SUP postalAddress COLLECTIVE )
+
+3.7. Collective Postal Code
+
+   The c-PostalCode attribute type specifies a postal code for a
+   collection of entries.
+
+      ( 2.5.4.17.1 NAME 'c-PostalCode'
+        SUP postalCode COLLECTIVE )
+
+3.8. Collective Post Office Box
+
+   The c-PostOfficeBox attribute type specifies a post office box for a
+   collection of entries.
+
+      ( 2.5.4.18.1 NAME 'c-PostOfficeBox'
+        SUP postOfficeBox COLLECTIVE )
+
+3.9. Collective Physical Delivery Office Name
+
+   The c-PhysicalDeliveryOfficeName attribute type specifies a physical
+   delivery office name for a collection of entries.
+
+      ( 2.5.4.19.1 NAME 'c-PhysicalDeliveryOfficeName'
+        SUP physicalDeliveryOfficeName COLLECTIVE )
+
+3.10. Collective Telephone Number
+
+   The c-TelephoneNumber attribute type specifies a telephone number for
+   a collection of entries.
+
+      ( 2.5.4.20.1 NAME 'c-TelephoneNumber'
+        SUP telephoneNumber COLLECTIVE )
+
+3.11. Collective Telex Number
+
+   The c-TelexNumber attribute type specifies a telex number for a
+   collection of entries.
+
+      ( 2.5.4.21.1 NAME 'c-TelexNumber'
+        SUP telexNumber COLLECTIVE )
+
+3.13. Collective Facsimile Telephone Number
+
+   The c-FacsimileTelephoneNumber attribute type specifies a facsimile
+   telephone number for a collection of entries.
+
+      ( 2.5.4.23.1 NAME 'c-FacsimileTelephoneNumber'
+
+   SUP facsimileTelephoneNumber COLLECTIVE )
+
+3.14. Collective International ISDN Number
+
+   The c-InternationalISDNNumber attribute type specifies an
+   international ISDN number for a collection of entries.
+
+      ( 2.5.4.25.1 NAME 'c-InternationalISDNNumber'
+        SUP internationalISDNNumber COLLECTIVE )
 
+</source>
     </section>
   </body>
 </document>

Modified: directory/apacheds/trunk/xdocs/users/configuration.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/configuration.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/configuration.xml (original)
+++ directory/apacheds/trunk/xdocs/users/configuration.xml Sun Oct 30 20:00:37 2005
@@ -1,90 +1,261 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
-    <title>Server Configuration and its JNDI Provider</title>
+    <author email="trustin">trustin</author>
+    <title>Configuration</title>
   </properties>
-  
   <body>
-    <section name="Server-Side JNDI Provider">
+    <p>
+The Apache Directory team introduced new configuration interface of ApacheDS
+from the version 0.9.1.  This page introduces
+it.</p>
+    <section heading="h1" name="The Configuration API">
       <p>
-        The Apache Directory Server contains a JNDI provider for the LDAP
-        namespace.  Unlike the SUN JNDI LDAP Provider which is an LDAP
-        client, the Server-Side JNDI Provider is not.  JNDI operations on
-        Contexts directly tap into the server's database partitions to add,
-        lookup, alter, and search for entries.  There is nothing done over the
-        wire.
-      </p>
+ApacheDS provides its configuration API in the
+{{org.apache.ldap.server.configuration}} package.  This package contains
+concrete configuration instruction classes that you can instantiate and specify
+in your JNDI environment variable.  To put your configuration instruction class
+into the JNDI environment
+variable:</p>
+      <source>Properties env = new Properties();
+env.setProperty( Context.INITIAL_CONTEXT_FACTORY, CoreContextFactory.class.getName() );
+...
 
-      <p>
-        The server leverages its server side JNDI LDAP provider in several ways.
-        First stored procedures written in Java will naturally use JNDI to
-        alter entries using this provider.  Thanks to JNDI the same procedure
-        outside of the server can be tested using the SUN JNDI LDAP provider.
-        This transparency is neat since it makes testing easy.  The
-        server side JNDI provider is also used as the API of choice for
-        integrating the server into other Java applications and servers.  The
-        first InitialContext request to the server side provider fires up the
-        entire server.  So you need not learn anything new to start using and
-        embedding the Apache Directory Server!  Well perhaps you need to know
-        about a few configuration interfaces that are added to the JNDI 
-        environment via a provider specific JNDI property.  This however is 
-        very easy to do as you will soon see.
-      </p>
+// Create a configuration instruction.
+Configuration cfg = new MutableStartupConfiguration();
+...
+
+// Put the configuration instruction to the environment variable.
+env.putAll( cfg.toJndiEnvironment() );
 
+// Execute the instruction you've specified.
+new InitialContext( env );
+</source>
       <p>
-        This document describes the server side JNDI Provider in terms of the
-        custom properties used to control its behavoir in the solid state and
-        for configuring the server on start up.  It also describes the 
-        configuration beans used by the server.
-      </p>
-    </section>
+Now let's find out what kind of instruction you can give to
+ApacheDS.</p>
+      <subsection heading="h2" name="{{StartupConfiguration}}">
+        <p>
+This instruction starts up the ApacheDS if it is not started.  Here's the list
+of known
+properties:</p>
+        <ul nesting="1">
+          <li>
+{{authenticatorConfigurations}} - a collection of {{AuthenticatorConfiguration}}
+s.  {{AuthenticatorConfiguration}} specifies {{Authenticator}} s that
+authenticate a user who accesses the ApacheDS DIT.  (Default: &lt;all default
+authenticators&gt;)</li>
+          <li>
+{{bootstrapSchemas}} - a set of {{BootstrapSchema}} s which are loaded at the
+first time ApacheDS starts up (Default: &lt;all default
+schemas&gt;)</li>
+          <li>
+{{contextPartitionConfigurations}} - a collection of
+{{ContextPartitionConfiguration}} s.  {{ContextPartitionConfiguration}}
+specified {{ContextPartition}} s that consist the ApacheDS DIT.  (Default: no
+context partitions except system
+partition)</li>
+          <li>
+{{accessControl}} - Set to {{true}} if you want to enable access control support
+of the ApacheDS. (Default:
+{{false}})</li>
+          <li>
+{{allowAnonymousAccess}} - Set to {{true}} if you want to enable anonymous
+access. (Default:
+{{true}})</li>
+          <li>
+{{interceptorConfigurations}} - a list of {{InterceptorConfiguration}} s which
+will configure the initial interceptor chain of the ApacheDS (Default: &lt;all
+default
+interceptors&gt;)</li>
+          <li>
+{{testEntries}} - a list of {{javax.naming.directory.Attributes}} which will be
+added to the DIT while the ApacheDS is started up (Default: no test
+entries)</li>
+          <li>
+{{workingDirectory}} - a working directory the content of DIT will be stored to
+(Default:
+{{./server-work/}})</li>
+        </ul>
+        <p>
+You don't need to specify any properties because all properties have the
+default.  Please use {{MutableStartupConfiguration}} to modify any properties
+above.</p>
+      </subsection>
+      <subsection heading="h2" name="{{ShutdownConfiguration}}">
+        <p>
+This instruction shuts down the ApacheDS if it is not already shut down. 
+There's no property to
+configure.</p>
+      </subsection>
+      <subsection heading="h2" name="{{SyncConfiguration}}">
+        <p>
+This instruction flushes out any I/O buffer or write cache.  There's no property
+to
+configure.</p>
+      </subsection>
+      <subsection heading="h2" name="{{AddContextPartitionConfiguration}}">
+        <p>
+This instruction adds a new context partition on-the-fly while the ApacheDS is
+running.  There is only one property, 'contextPartitionConfiguration'.  You can
+specify an appropriate {{ContextPartitionConfiguration}} to plug a context
+partition into the
+ApacheDS.</p>
+      </subsection>
+      <subsection heading="h2" name="{{RemoveContextPartitionConfiguration}}">
+        <p>
+This instruction remove an existing context partition on-the-fly while the
+ApacheDS is running.  There is only one property, 'suffix'.  You can specify the
+suffix of the partition you want to remove from the
+ApacheDS.</p>
+      </subsection>
+      <subsection heading="h2" name="Running and Choosing Multiple Instances">
+        <p>
+You can run multiple instances of ApacheDS by specifying {{instanceId}} to all
+{{Configuration}} instructions.  {{InstanceId}} can be specified as a
+constructor parameter.  Please take a look at the APi documentation (JavaDoc)
+for more
+details.</p>
+        <source>// Create a configuration instruction that affects an ApacheDS instance 'instance4'.
+Configuration cfg = new MutableStartupConfiguration( "instance4" );
+...
 
-    <section name="Server Specific JNDI Properties">
-    </section>
+// Put the configuration instruction to the environment variable.
+env.putAll( cfg.toJndiEnvironment() );
 
-    <section name="Embedding the Apache Directory Server">
+// Execute the instruction you've specified for an ApacheDS instance 'instance4'.
+new InitialContext( env );
+</source>
+      </subsection>
+    </section>
+    <section heading="h1" name="Using Spring Framework">
       <p>
-        Embedding the server is really easy.  Just set the JNDI initial context
-        factory and other security settings along with specific properties
-        to fire her up.  Here's a simple example of code that embeds the server
-        using the minimum configuration information:
+The configuration API is designed to fit tightly
+with
+        <a href="http://www.springframework.org/">Spring Framework</a>
+.  Here is an example beans xml
+file:
       </p>
+      <source>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
 
-<source>
-</source>
+&lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
+  "http://www.springframework.org/dtd/spring-beans.dtd"&gt;
 
-      <p>
-        This code snippet starts up the server on port 389 or the next
-        available port if access to 389 is denied or another server is already
-        bound to that port.  There is only one partition in the system hanging
-        off of the "ou=system" naming context.  The server allows for anonymous
-        binds and has two users preconfigured: a regular test user,
-        <b>uid=akarasulu,ou=users,ou=system</b> with password <i>test</i>, and
-        the super user <b>uid=admin,ou=system</b>, with password <i>secret</i>.
-      </p>
+&lt;beans&gt;
+  &lt;!-- JNDI environment variable --&gt;
+  &lt;bean id="environment" class="org.springframework.beans.factory.config.PropertiesFactoryBean"&gt;
+    &lt;property name="properties"&gt;
+      &lt;props&gt;
+    	  &lt;prop key="asn.1.berlib.provider"&gt;org.apache.ldap.common.berlib.asn1.SnickersProvider&lt;/prop&gt;
+    	  &lt;!--prop key="asn.1.berlib.provider"&gt;org.apache.asn1new.ldap.TwixProvider&lt;/prop--&gt;
+    	  &lt;prop key="java.naming.security.authentication"&gt;simple&lt;/prop&gt;
+    	  &lt;prop key="java.naming.security.principal"&gt;uid=admin,ou=system&lt;/prop&gt;
+          &lt;prop key="java.naming.security.credentials"&gt;secret&lt;/prop&gt;
+          &lt;prop key="java.naming.ldap.attributes.binary"&gt;
+            photo personalSignature audio jpegPhoto javaSerializedData userPassword
+            userCertificate cACertificate authorityRevocationList certificateRevocationList
+            crossCertificatePair x500UniqueIdentifier krb5Key
+          &lt;/prop&gt;
+      &lt;/props&gt;
+    &lt;/property&gt;
+  &lt;/bean&gt;
+  
+  &lt;!-- StartupConfiguration to start ApacheDS --&gt;
+  &lt;bean id="configuration" class="org.apache.ldap.server.configuration.MutableServerStartupConfiguration"&gt;
+    &lt;property name="workingDirectory"&gt;&lt;value&gt;apache.org&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="allowAnonymousAccess"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="accessControlEnabled"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="ldapPort"&gt;&lt;value&gt;10389&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="contextPartitionConfigurations"&gt;
+      &lt;set&gt;
+        &lt;ref bean="apachePartitionConfiguration"/&gt;
+      &lt;/set&gt;
+    &lt;/property&gt;
 
-      <p>
-        <b>WARNING:</b> REMOVE THE TEST USER AND RESET THE PASSWORD ON THE ADMIN
-        USER ACCOUNT AFTER STARTING APACHEDS.
-      </p>
+    &lt;!-- Bootstrap schemas --&gt;
+    &lt;property name="bootstrapSchemas"&gt;
+      &lt;set&gt;
+        &lt;bean class="org.apache.ldap.server.schema.bootstrap.AutofsSchema"/&gt;
+        &lt;bean class="org.apache.ldap.server.schema.bootstrap.CorbaSchema"/&gt;
+        &lt;bean class="org.apache.ldap.server.schema.bootstrap.CoreSchema"/&gt;
 
-      <p>
-        Here's another more invovled configuration:
-      </p>
+        ......
 
-<source>
-</source>
+      &lt;/set&gt;
+    &lt;/property&gt;
+    
+    &lt;!-- Interceptor configurations --&gt;
+    &lt;property name="interceptorConfigurations"&gt;
+      &lt;list&gt;
+        &lt;bean class="org.apache.ldap.server.configuration.MutableInterceptorConfiguration"&gt;
+          &lt;property name="name"&gt;&lt;value&gt;normalizationService&lt;/value&gt;&lt;/property&gt;
+          &lt;property name="interceptor"&gt;
+            &lt;bean class="org.apache.ldap.server.normalization.NormalizationService" /&gt;
+          &lt;/property&gt;
+        &lt;/bean&gt;
+        &lt;bean class="org.apache.ldap.server.configuration.MutableInterceptorConfiguration"&gt;
+          &lt;property name="name"&gt;&lt;value&gt;authenticationService&lt;/value&gt;&lt;/property&gt;
+          &lt;property name="interceptor"&gt;
+            &lt;bean class="org.apache.ldap.server.authn.AuthenticationService" /&gt;
+          &lt;/property&gt;
+        &lt;/bean&gt;
+
+        ......
+
+      &lt;/list&gt;
+    &lt;/property&gt;
+  &lt;/bean&gt;
 
+  &lt;!-- Additional ContextPartitionConfiguration --&gt;
+  &lt;bean id="apachePartitionConfiguration" class="org.apache.ldap.server.configuration.MutableContextPartitionConfiguration"&gt;
+    &lt;property name="name"&gt;&lt;value&gt;apache&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="suffix"&gt;&lt;value&gt;dc=apache,dc=org&lt;/value&gt;&lt;/property&gt;
+    &lt;property name="indexedAttributes"&gt;
+      &lt;set&gt;
+        &lt;value&gt;objectClass&lt;/value&gt;
+        &lt;value&gt;ou&lt;/value&gt;
+        &lt;value&gt;uid&lt;/value&gt;
+      &lt;/set&gt;
+    &lt;/property&gt;
+    &lt;property name="contextEntry"&gt;
+      &lt;value&gt;
+        objectClass: top
+        objectClass: domain
+        objectClass: extensibleObject
+        dc: apache
+      &lt;/value&gt;
+    &lt;/property&gt;
+  &lt;/bean&gt;
+
+  &lt;!-- Custom editors required to launch ApacheDS --&gt;
+  &lt;bean class="org.springframework.beans.factory.config.CustomEditorConfigurer"&gt;
+    &lt;property name="customEditors"&gt;
+      &lt;map&gt;
+        &lt;entry key="javax.naming.directory.Attributes"&gt;
+          &lt;bean class="org.apache.ldap.server.configuration.AttributesPropertyEditor"/&gt;
+        &lt;/entry&gt;
+      &lt;/map&gt;
+   &lt;/property&gt;
+  &lt;/bean&gt;
+&lt;/beans&gt;
+</source>
       <p>
-        This configuration starts up the server on port 10389 with anonymous
-        binds disabled.  The server stores its database files under /var/ldap
-        and creates a new application partition for Apache entries off of the
-        <b>dc=apache,dc=org</b> naming context in addition to the system
-        partition.  If you look closely at /var/ldap you'll see a directory
-        named apache where you'll find even more database files.  These files
-        are the database files for the separate partition apache.org entries.
-      </p>
+With the XML file above, you can start up the ApacheDS with this
+code:</p>
+      <source>Properties env;
+ServerStartupConfiguration cfg;
+
+ApplicationContext factory = new FileSystemXmlApplicationContext( args[0] );
+cfg = ( StartupConfiguration ) factory.getBean( "configuration" );
+env = ( Properties ) factory.getBean( "environment" );
+
+env.setProperty( Context.PROVIDER_URL, "" );
+env.setProperty( Context.INITIAL_CONTEXT_FACTORY, CoreContextFactory.class.getName() );
+env.putAll( cfg.toJndiEnvironment() );
+
+new InitialDirContext( env );
+</source>
     </section>
   </body>
 </document>

Modified: directory/apacheds/trunk/xdocs/users/index.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/index.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/index.xml (original)
+++ directory/apacheds/trunk/xdocs/users/index.xml Sun Oct 30 20:00:37 2005
@@ -1,107 +1,92 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <author email="akarasulu">akarasulu</author>
     <title>User's Guide</title>
   </properties>
-  
   <body>
-    <section name="User's Guide">
+    <section heading="h1" name="User's Guide">
       <p>
-        Here we have assembled a bunch of guides and howto like documents that
-        demonstrate how the server can be used.  Hopefully this will grow into
-        a user's guide.
-      </p>
-
+This is a simple guide to various ApacheDS features to help users get going. 
+It's be no means
+extensive.</p>
       <table>
         <tr>
-          <th>Topic</th>
-          <th>Description</th>
+          <th>
+Topic</th>
+          <th>
+Description</th>
         </tr>
-
         <tr>
           <td>
             <a href="./building.html">Building</a>
           </td>
           <td>
-            Shows how to build the directory server from the repository.
-          </td>
+How to build the directory server from the
+repository.</td>
         </tr>
-
         <tr>
           <td>
             <a href="./authentication.html">Authentication</a>
           </td>
           <td>
-            Demonstrates how to bind to the server as admin and setup other
-            user accounts.
-          </td>
+How to bind to the server and setup custom
+authenticators.</td>
         </tr>
-
         <tr>
           <td>
             <a href="./authorization.html">Authorization</a>
           </td>
           <td>
-            Explains the hardcoded authorization rules and how to replace 
-            them using the basic access control mechanism and ACI.
-          </td>
+How to enable basic access controls and what you get without
+them.</td>
         </tr>
-
         <tr>
           <td>
             <a href="./subentries.html">Subentries</a>
+and the Administrative
+Model
           </td>
           <td>
-            Documents the subentry implementation which 
-            conforms to <a href="http://www.faqs.org/rfcs/rfc3672.html">
-            RFC 3672</a>.
-          </td>
+What they are and how to specify their scope via
+subtreeSpecifications.</td>
         </tr>
-
         <tr>
           <td>
-            <a href="./collective.html">Collective Attributes</a>
+            <a href="./collective.html">Collective</a>
+Attributes
           </td>
           <td>
-            Documents the collective attributes implementation which 
-            conforms to <a href="http://www.faqs.org/rfcs/rfc3671.html">
-            RFC 3671</a>.
-          </td>
+How to use collective
+attributes.</td>
         </tr>
-
         <tr>
           <td>
             <a href="./configuration.html">Configuration</a>
           </td>
           <td>
-            Describes how to configure and control the server.
-          </td>
+How to configure and control the
+server.</td>
         </tr>
-
         <tr>
           <td>
             <a href="./partitions.html">Partitions</a>
           </td>
           <td>
-            A howto on creating context partitions besides the system partition
-            and having them store entries for a specific naming context.
-          </td>
+How to add new partitions besides the system
+partition.</td>
         </tr>
-
         <tr>
           <td>
-            <a href="./plugin.html">Maven Plugin</a>
+Maven
+            <a href="./plugin.html">Plugin</a>
           </td>
           <td>
-            Lists the goals, properties and the steps required to integrate
-            your project with the Maven Plugin for the directory server.
-          </td>
+How to use the plugin to extends the
+schema.</td>
         </tr>
-
       </table>
-
-
     </section>
   </body>
 </document>

Modified: directory/apacheds/trunk/xdocs/users/partitions.xml
URL: http://svn.apache.org/viewcvs/directory/apacheds/trunk/xdocs/users/partitions.xml?rev=329722&r1=329721&r2=329722&view=diff
==============================================================================
--- directory/apacheds/trunk/xdocs/users/partitions.xml (original)
+++ directory/apacheds/trunk/xdocs/users/partitions.xml Sun Oct 30 20:00:37 2005
@@ -1,171 +1,150 @@
 <?xml version="1.0" encoding="UTF-8"?>
+
 <document>
   <properties>
-    <author email="akarasulu@apache.org">Alex Karasulu</author>
+    <author email="akarasulu">akarasulu</author>
     <title>Partitions</title>
   </properties>
-  
   <body>
-    <section name="Partitions">
+    <section heading="h1" name="Introduction">
       <p>
-        Partitions are entry stores assigned to a naming context.  The idea
-        behind a partition is that it stores a subset of the Directory
-        Information Base (DIB).  Partitions can be implemented in any way so
-        long as they adhere to interfaces.
-      </p>
-
-      <subsection name="Status">
-        <p>
-          Presently the server has a single partition implementation.  This
-          implementation is used for both the system partition and user
-          partitions.  It uses <a href="http://jdbm.sourceforge.net/">JDBM</a>
-          as the underlying B+Tree implementation for storing entries.
-        </p>
-
-        <p>
-          Other implementations are possible.  I'm particularly interested in
-          memory based partitions either BTree based or based on something like
-          Prevayer.
-        </p>
-
-        <p>
-          Partitions have simple interfaces that can be used to align any data
-          source to the LDAP data model thereby accessing it via JNDI or via
-          LDAP over the wire.  This makes the server very flexible as a bridge
-          to standardize access to disparate data sources and formats.  Dynamic
-          mapping based backends are also interesting.
-        </p>
-      </subsection>
-
-      <subsection name="System Partition">
-        <p>
-          The system partition is a very special partition that is hardcoded to
-          hang off of the <b>ou=system</b> naming context.  It is always present
-          and contains administrative and operational information needed by the
-          server to operate.  Hence its name.
-        </p>
-
-        <p>
-          The server's subsystems will use this partition to store information
-          critical to their operation.  Things like triggers, stored procedures,
-          access control instructions and schema information can be maintained
-          here.
-        </p>
-      </subsection>
-
-      <subsection name="Root Nexus">
-        <p>
-          Several partitions can be assigned to different naming contexts within
-          the server so long as their names do not overlap such that one
-          partition's naming context is contained within anothers.  The root
-          nexus is a fake partition that does not really store entries.  It maps
-          other entry storing partitions to naming contexts and routes backing
-          store calls to the partition containing the entry associated with the
-          operation.
-       </p>
-      </subsection>
-
-      <subsection name="User Partitions">
-        <p>
-          User partitions are partitions added by users.  When you download and
-          start using the server you may want to create a separate partition to
-          store the entries of your application.  To us user (sometimes also
-          referred to as application) partitions are those that are not the system
-          partition!  In the following section we describe how a user partition
-          can be created in the server.
-        </p>
+Partitions are entry stores assigned to a naming context. The idea behind a
+partition is that it stores a subset of the Directory Information Base (DIB).
+Partitions can be implemented in any way so long as they adhere to
+interfaces.</p>
+      <subsection heading="h2" name="Status">
+        <p>
+Presently the server has a single partition implementation. This implementation
+is used for both the system partition and user partitions. It
+uses
+          <a href="http://jdbm.sourceforge.net/">JDBM</a>
+as the underlying B+Tree implementation for storing
+entries.
+        </p>
+        <p>
+Other implementations are possible. I'm particularly interested in memory based
+partitions either BTree based or based on something like
+Prevayer.</p>
+        <p>
+Partitions have simple interfaces that can be used to align any data source to
+the LDAP data model thereby accessing it via JNDI or via LDAP over the wire.
+This makes the server very flexible as a bridge to standardize access to
+disparate data sources and formats. Dynamic mapping based backends are also
+interesting.</p>
+      </subsection>
+      <subsection heading="h2" name="System Partitions">
+        <p>
+The system partition is a very special partition that is hardcoded to hang off
+of the ou=system naming context. It is always present and contains
+administrative and operational information needed by the server to operate.
+Hence its
+name.</p>
+        <p>
+The server's subsystems will use this partition to store information critical to
+its
+operation.</p>
+      </subsection>
+      <subsection heading="h2" name="Root Nexus">
+        <p>
+Several partitions can be assigned to different naming contexts within the
+server so long as their names do not overlap such that one partition's naming
+context is contained within anothers. The root nexus is a fake partition that
+does not really store entries. It maps other entry storing partitions to naming
+contexts and routes backing store calls to the partition containing the entry
+associated with the
+operation.</p>
+      </subsection>
+      <subsection heading="h2" name="User Paritions">
+        <p>
+User partitions are partitions added by users. When you download and start using
+the server you may want to create a separate partition to store the entries of
+your application. To us user (sometimes also referred to as application)
+partitions are those that are not the system partition! In the following section
+we describe how a user partition can be created in the
+server.</p>
       </subsection>
     </section>
-
-    <section name="Adding User Partitions">
+    <section heading="h1" name="Adding User Paritions">
+      <p>
+Adding new application partitions to the server is a matter of adding
+DirectoryPartitionConfiguration objects to the StartupConfigration added to the
+JNDI environment. These properties are used in both standalone and in embedded
+configurations. We will show you how to configure partitions by example using
+xml configuration files with the standalone application and programatically for
+embedding.</p>
       <p>
-        Adding new application partitions to the server is a matter of
-        adding DirectoryPartitionConfiguration objects to the 
-        StartupConfigration added to the JNDI environment.  These properties 
-        are used in both standalone and in embedded configurations.  We will 
-        show you how to configure partitions by example using xml configuration
-        files with the standalone application and programatically for embedding.
+Until we fill in this section with more specific examples just geared towards
+the configuration of partitions please
+see
+        <a href="./configuration.html">Configuration</a>
+.
       </p>
     </section>
-
-    <section name="Future Progress">
-      <subsection name="Partition Nesting">
-        <p>
-          Today we have some limitations to the way we can partition the DIB.
-          Namely we can't have a partition within a partition and sometimes this
-          makes sense.  Eventually we intend to enable this kind of
-          functionality using a special type of nexus which is both a router
-          and a backing store for entries.  It's smart enough to know what to
-          route verses when to use its own database.  Here's a <a href=
-          "http://issues.apache.org/jira/browse/DIREVE-23">JIRA improvement</a>
-          specifically aimed at achieving this goal.
-        </p>
-      </subsection>
-
-      <subsection name="Partition Variety">
-        <p>
-          Obviously we want as many different kinds of partitions as possible.
-          Some really cool ideas have floated around out there for a while.
-          Here's a list of theoretically possible partition types that might
-          be useful or just cool:
-        </p>
-
-        <ul>
-          <li>
-            Partitions that use JDBC to store entries.  These would probably
-            be way too slow.  However they might be useful if some mapping
-            were to be used to represent an existing application's database
-            schema as an LDAP DIT.  This would allow us to expose any database
-            data via LDAP.
-          </li>
-
-          <li>
-            Partitions using other LDAP servers to store their entries.  Why
-            do this when introducing latency.  Perhaps you want to proxy other
-            servers or make other servers behave like the server.
-          </li>
-
-          <li>
-            A partition that serves out the Windows registry via LDAP.  A
-            standard mechanism to map the Windows registry to an LDAP DIT is
-            pretty simple.  This would be a neat way to expose client machine
-            registry management.
-          </li>
-
-          <li>
-            A partition based on SleepyCat's JE.  I was going to try this
-            and see how it performs against JDBM.
-          </li>
-
-          <li>
-            A partition based on an in-memory BTree implementation.  This would
-            be fast and really cool for storing things like schema info.  It
-            would also be cool for staging data between memory and disk.
-          </li>
-
-          <li>
-            A partition based on Prevalyer.  This is like an in-memory partition
-            but you can save it at the end of the day.  This might be really
-            useful especially for things the system partition which almost
-            always need to be in memory.  The system partition can do this by
-            using really large caches equal to the number of entries in the
-            system partition.
-          </li>
+    <section heading="h1" name="Future">
+      <p>
+Things we'd like to do with the existing partitioning scheme and
+beyond.</p>
+      <subsection heading="h2" name="Paritition Nesting">
+        <p>
+Today we have some limitations to the way we can partition the DIB. Namely we
+can't have a partition within a partition and sometimes this makes sense.
+Eventually we intend to enable this kind of functionality using a special type
+of nexus which is both a router and a backing store for entries. It's smart
+enough to know what to route verses when to use its own database. Here's
+a
+          <a href="http://issues.apache.org/jira/browse/DIREVE-23">JIRA improvement</a>
+specifically aimed at achieving this
+goal.
+        </p>
+      </subsection>
+      <subsection heading="h2" name="Paritition Implementations">
+        <p>
+Obviously we want as many different kinds of partitions as possible. Some really
+cool ideas have floated around out there for a while. Here's a list of
+theoretically possible partition types that might be useful or just
+cool:</p>
+        <ul nesting="1">
+          <li>
+Partitions that use JDBC to store entries. These would probably be way too slow.
+However they might be useful if some mapping were to be used to represent an
+existing application's database schema as an LDAP DIT. This would allow us to
+expose any database data via LDAP.  Great for
+virtualization.</li>
+          <li>
+Partitions using other LDAP servers to store their entries. Why do this when
+introducing latency. Perhaps you want to proxy other servers or make other
+servers behave like the personality of another server all
+together.</li>
+          <li>
+A partition that serves out the Windows registry via LDAP. A standard mechanism
+to map the Windows registry to an LDAP DIT is pretty simple. This would be a
+neat way to expose client machine registry
+management.</li>
+          <li>
+A partition based on an in-memory BTree implementation. This would be fast and
+really cool for storing things like schema info. It would also be cool for
+staging data between memory and
+disk.</li>
+          <li>
+A partition based on Prevalyer. This is like an in-memory partition but you can
+save it at the end of the day. This might be really useful especially for things
+the system partition which almost always need to be in memory. The system
+partition can do this by using really large caches equal to the number of
+entries in the system
+partition.</li>
         </ul>
       </subsection>
-
-      <subsection name="Partitioning entries under a single context?">
+      <subsection heading="h2" name="Partitioning Entries Under a Single Context">
         <p>
-          Other aspirations include entry partitioning within a container
-          context.  Imagine having 250 million entries under
-          <code>ou=citizens,dc=census,dc=gov</code>.  You don't want all 250
-          million in one partition but would like to sub partition these entries
-          under the same context based on some attribute.  Basically we will be
-          using the attribute's value to implement sub partitioning where within
-          a single context we are partitioning entries.  The value is used to
-          hash entries across buckets (the buckets are other partitions).  Yeah
-          this is a bit wild but it would be useful in several situations.
-        </p>
+Other aspirations include entry partitioning within a container context. Imagine
+having 250 million entries under ou=citizens,dc=census,dc=gov. You don't want
+all 250 million in one partition but would like to sub partition these entries
+under the same context based on some attribute. Basically we will be using the
+attribute's value to implement sub partitioning where within a single context we
+are partitioning entries. The value is used to hash entries across buckets (the
+buckets are other partitions). Yeah this is a bit on the heavy duty end but it
+would be useful in several
+situations.</p>
       </subsection>
     </section>
   </body>



Mime
View raw message