You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by ak...@apache.org on 2005/10/31 05:00:43 UTC
svn commit: r329722 [1/2] - in /directory/apacheds/trunk/xdocs: ./ users/
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: <all default
+authenticators>)</li>
+ <li>
+{{bootstrapSchemas}} - a set of {{BootstrapSchema}} s which are loaded at the
+first time ApacheDS starts up (Default: <all default
+schemas>)</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: <all
+default
+interceptors>)</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><?xml version="1.0" encoding="UTF-8"?>
-<source>
-</source>
+<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
+ "http://www.springframework.org/dtd/spring-beans.dtd">
- <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>
+<beans>
+ <!-- JNDI environment variable -->
+ <bean id="environment" class="org.springframework.beans.factory.config.PropertiesFactoryBean">
+ <property name="properties">
+ <props>
+ <prop key="asn.1.berlib.provider">org.apache.ldap.common.berlib.asn1.SnickersProvider</prop>
+ <!--prop key="asn.1.berlib.provider">org.apache.asn1new.ldap.TwixProvider</prop-->
+ <prop key="java.naming.security.authentication">simple</prop>
+ <prop key="java.naming.security.principal">uid=admin,ou=system</prop>
+ <prop key="java.naming.security.credentials">secret</prop>
+ <prop key="java.naming.ldap.attributes.binary">
+ photo personalSignature audio jpegPhoto javaSerializedData userPassword
+ userCertificate cACertificate authorityRevocationList certificateRevocationList
+ crossCertificatePair x500UniqueIdentifier krb5Key
+ </prop>
+ </props>
+ </property>
+ </bean>
+
+ <!-- StartupConfiguration to start ApacheDS -->
+ <bean id="configuration" class="org.apache.ldap.server.configuration.MutableServerStartupConfiguration">
+ <property name="workingDirectory"><value>apache.org</value></property>
+ <property name="allowAnonymousAccess"><value>false</value></property>
+ <property name="accessControlEnabled"><value>false</value></property>
+ <property name="ldapPort"><value>10389</value></property>
+ <property name="contextPartitionConfigurations">
+ <set>
+ <ref bean="apachePartitionConfiguration"/>
+ </set>
+ </property>
- <p>
- <b>WARNING:</b> REMOVE THE TEST USER AND RESET THE PASSWORD ON THE ADMIN
- USER ACCOUNT AFTER STARTING APACHEDS.
- </p>
+ <!-- Bootstrap schemas -->
+ <property name="bootstrapSchemas">
+ <set>
+ <bean class="org.apache.ldap.server.schema.bootstrap.AutofsSchema"/>
+ <bean class="org.apache.ldap.server.schema.bootstrap.CorbaSchema"/>
+ <bean class="org.apache.ldap.server.schema.bootstrap.CoreSchema"/>
- <p>
- Here's another more invovled configuration:
- </p>
+ ......
-<source>
-</source>
+ </set>
+ </property>
+
+ <!-- Interceptor configurations -->
+ <property name="interceptorConfigurations">
+ <list>
+ <bean class="org.apache.ldap.server.configuration.MutableInterceptorConfiguration">
+ <property name="name"><value>normalizationService</value></property>
+ <property name="interceptor">
+ <bean class="org.apache.ldap.server.normalization.NormalizationService" />
+ </property>
+ </bean>
+ <bean class="org.apache.ldap.server.configuration.MutableInterceptorConfiguration">
+ <property name="name"><value>authenticationService</value></property>
+ <property name="interceptor">
+ <bean class="org.apache.ldap.server.authn.AuthenticationService" />
+ </property>
+ </bean>
+
+ ......
+
+ </list>
+ </property>
+ </bean>
+ <!-- Additional ContextPartitionConfiguration -->
+ <bean id="apachePartitionConfiguration" class="org.apache.ldap.server.configuration.MutableContextPartitionConfiguration">
+ <property name="name"><value>apache</value></property>
+ <property name="suffix"><value>dc=apache,dc=org</value></property>
+ <property name="indexedAttributes">
+ <set>
+ <value>objectClass</value>
+ <value>ou</value>
+ <value>uid</value>
+ </set>
+ </property>
+ <property name="contextEntry">
+ <value>
+ objectClass: top
+ objectClass: domain
+ objectClass: extensibleObject
+ dc: apache
+ </value>
+ </property>
+ </bean>
+
+ <!-- Custom editors required to launch ApacheDS -->
+ <bean class="org.springframework.beans.factory.config.CustomEditorConfigurer">
+ <property name="customEditors">
+ <map>
+ <entry key="javax.naming.directory.Attributes">
+ <bean class="org.apache.ldap.server.configuration.AttributesPropertyEditor"/>
+ </entry>
+ </map>
+ </property>
+ </bean>
+</beans>
+</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>