Mailing-List: contact commits-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@directory.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: svn commit: r984856 [1/2] - in
 /directory/sandbox/felixk/apacheds-docs/src:
 docbkx/ main/resources/data/ main/resources/images/
Date: Thu, 12 Aug 2010 16:40:48 -0000
To: commits@directory.apache.org
From: felixk@apache.org
Message-Id: <20100812164049.235E12388A1C@eris.apache.org>

Author: felixk
Date: Thu Aug 12 16:40:48 2010
New Revision: 984856

URL: http://svn.apache.org/viewvc?rev=984856&view=rev
Log:
Starting with Basic User Guide to docbook

Added:
    directory/sandbox/felixk/apacheds-docs/src/main/resources/data/authz_sevenSeas.ldif
    directory/sandbox/felixk/apacheds-docs/src/main/resources/data/captain_hook.ldif
    directory/sandbox/felixk/apacheds-docs/src/main/resources/data/captain_hook_delete.ldif
    directory/sandbox/felixk/apacheds-docs/src/main/resources/data/captain_hook_modify.ldif
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/authentication_options_ls.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/authorization_sample_entries.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/confluence_logon.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/forbidden.gif   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/password_edit_ls.png   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/sample_structure.gif   (with props)
    directory/sandbox/felixk/apacheds-docs/src/main/resources/images/w32_service_properties.png   (with props)
Modified:
    directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/book.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_handling_of_data_within_your_directory.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml?rev=984856&r1=984855&r2=984856&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.xml Thu Aug 12 16:40:48 2010
@@ -6,16 +6,11 @@
   xmlns:ns5="http://www.w3.org/2000/svg"
   xmlns:ns4="http://www.w3.org/1998/Math/MathML"
   xmlns:ns3="http://www.w3.org/1999/xhtml"
-  xmlns:db="http://docbook.org/ns/docbook"
   xml:lang="en">
   <title>Basic User's Guide</title>
   <para>
-    <mediaobject>
-      <imageobject>
-        <imagedata
-          fileref="images/warning.gif"></imagedata>
-      </imageobject>
-    </mediaobject>
+    <graphic
+      fileref="images/warning.gif" />
     Work in progress
     Unfortunately the Basic User's Guide for ApacheDS 1.5 is not finished yet. We have started to move
     and revise the content, things
@@ -45,13 +40,11 @@
     <para>
       We are quite interested to improve the content of this guide. Feel free to provide us feedback:
     </para>
-    <inlinemediaobject>
-      <imageobject>
-        <imagedata
-          fileref="images/email.png"></imagedata>
-      </imageobject>
-    </inlinemediaobject>
-    <email>users@directory.apache.org</email>
+    <para>
+      <graphic
+        fileref="images/email.png" />
+      <email>users@directory.apache.org</email>
+    </para>
   </section>
 
 </chapter>

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/book.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/book.xml?rev=984856&r1=984855&r2=984856&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/book.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/book.xml Thu Aug 12 16:40:48 2010
@@ -7,7 +7,6 @@
   xmlns:ns5="http://www.w3.org/2000/svg"
   xmlns:ns4="http://www.w3.org/1998/Math/MathML"
   xmlns:ns3="http://www.w3.org/1999/xhtml"
-  xmlns:db="http://docbook.org/ns/docbook"
   xml:lang="en">
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
@@ -41,8 +40,7 @@ to you under the Apache License, Version
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
-  <link
-            xlink:href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</link>
+  <ulink url="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</ulink>
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
@@ -58,11 +56,11 @@ under the License.</literallayout>
   </info>
   <preface>
     <title>Work in progress</title>
-    <db:para>
-      Unfortunately the Basic User's Guide for ApacheDS 1.5 is not finished yet. We have started to move and revise the content, things
-      you find here are work in progress but should be valid for ApacheDS 1.5.5. In the meantime you can have a look at
-      the ApacheDS 1.0 Basic User's Guide, which is currently more complete.
-</db:para>
+    <para>
+  Unfortunately the Basic User's Guide for ApacheDS 1.5 is not finished yet. We have started to move and revise the content, things
+  you find here are work in progress but should be valid for ApacheDS 1.5.5. In the meantime you can have a look at
+  the ApacheDS 1.0 Basic User's Guide, which is currently more complete.
+</para>
   </preface>
   <xi:include
     href="basic_user_guide.xml" />

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml?rev=984856&r1=984855&r2=984856&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter-how-to-begin.xml Thu Aug 12 16:40:48 2010
@@ -21,19 +21,19 @@
       <listitem>
         <para>
           <xref
-            linkend="System vision">System vision</xref>
+            linkend="System vision" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Origin and Motives">Origin and Motives</xref>
+            linkend="Origin and Motives" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Resources">Resources</xref>
+            linkend="Resources" />
         </para>
       </listitem>
     </itemizedlist>
@@ -99,12 +99,8 @@
         <figure
           id="50k FT Architecture">
           <title>50k FT Architecture</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/50k-ft-architecture.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/50k-ft-architecture.png" />
         </figure>
       </section>
     </section>
@@ -185,19 +181,19 @@
       <listitem>
         <para>
           <xref
-            linkend="directoriesAndDirectoryServices">Directories and directory services</xref>
+            linkend="directoriesAndDirectoryServices" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="ldapTheLightWeightDirectoryAccessProtocol">LDAP - the Lightweight Directory Access Protocol</xref>
+            linkend="ldapTheLightWeightDirectoryAccessProtocol" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="ldapResources">LDAP Resources</xref>
+            linkend="ldapResources" />
         </para>
       </listitem>
     </itemizedlist>
@@ -307,12 +303,8 @@
         <figure
           id="From X500 to LDAP">
           <title>From X500 to LDAP</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/fromX500toLDAP.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/fromX500toLDAP.png" />
         </figure>
       </section>
       <section>
@@ -382,12 +374,8 @@
         <figure
           id="LDAP-Tools">
           <title>LDAP-Tools</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/ldap-tools.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/ldap-tools.png" />
         </figure>
         <para>
           Very different types of software products may act as LDAP clients, consuming data for authentication,
@@ -427,12 +415,8 @@
           <figure
             id="Cover Understanding and Deploying LDAP Directory Services">
             <title>Cover Understanding and Deploying LDAP Directory Services</title>
-            <mediaobject>
-              <imageobject>
-                <imagedata
-                  fileref="images/cover_howes_100.gif" />
-              </imageobject>
-            </mediaobject>
+            <graphic
+              fileref="images/cover_howes_100.gif" />
           </figure>
           Understanding and Deploying LDAP Directory Services (2nd Edition)
           by Timothy A. Howes, Mark C. Smith, Gordon S.
@@ -447,20 +431,12 @@
           <figure
             id="Cover LDAP fuer Java-Entwickler">
             <title>Cover LDAP fuer Java-Entwickler</title>
-            <mediaobject>
-              <imageobject>
-                <imagedata
-                  fileref="images/cover_zoerner_100.gif" />
-              </imageobject>
-            </mediaobject>
+            <graphic
+              fileref="images/cover_zoerner_100.gif" />
           </figure>
           LDAP fuer Java-Entwickler â Einstieg und Integration.
-          <inlinemediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/de.png" />
-            </imageobject>
-          </inlinemediaobject>
+          <graphic
+            fileref="images/de.png" />
           von Stefan Zoerner
           Software und Support Verlag, 3. aktualisierte Auflage 2007
           ISBN: 978-3-939084-07-5
@@ -505,12 +481,8 @@
                 <ulink
                   url="http://www.mitlinx.de/ldap/">LDAP verstehen mit linx</ulink>
                 , by Petra Haberer
-                <inlinemediaobject>
-                  <imageobject>
-                    <imagedata
-                      fileref="images/de.png" />
-                  </imageobject>
-                </inlinemediaobject>
+                <graphic
+                  fileref="images/de.png" />
               </para>
             </listitem>
           </itemizedlist>
@@ -528,31 +500,31 @@
       <listitem>
         <para>
           <xref
-            linkend="prerequisites">Prerequisites</xref>
+            linkend="prerequisites" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Download a server installer">Download a server installer</xref>
+            linkend="Download a server installer" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Installation on Windows">Installation on Windows</xref>
+            linkend="Installation on Windows" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Installation on Mac OS X">Installation on Mac OS X</xref>
+            linkend="Installation on Mac OS X" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Installation on Linux and Solaris">Installation on Linux and Solaris</xref>
+            linkend="Installation on Linux and Solaris" />
         </para>
       </listitem>
     </itemizedlist>
@@ -651,12 +623,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
       <figure
         id="Windows Installer">
         <title>Windows Installer</title>
-        <mediaobject>
-          <imageobject>
-            <imagedata
-              fileref="images/Windows_Installer.png" />
-          </imageobject>
-        </mediaobject>
+        <graphic
+          fileref="images/Windows_Installer.png" />
       </figure>
       <para>
         To install the ApacheDS as Windows service you need
@@ -683,12 +651,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
       <figure
         id="MacOSX Installer">
         <title>MacOSX Installer</title>
-        <mediaobject>
-          <imageobject>
-            <imagedata
-              fileref="images/MacOSX_Installer.png" />
-          </imageobject>
-        </mediaobject>
+        <graphic
+          fileref="images/MacOSX_Installer.png" />
       </figure>
       <para>From there, you will be guided to install Apache DS on your system.</para>
       <section>
@@ -726,13 +690,13 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <listitem>
           <para>
             <xref
-              linkend="The task and how to accomplish it">The task and how to accomplish it</xref>
+              linkend="The task and how to accomplish it" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Resources_2">Resources</xref>
+              linkend="Resources_2" />
           </para>
         </listitem>
       </itemizedlist>
@@ -760,12 +724,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
           change effect.
         </para>
         <para>
-          <inlinemediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/warning.gif" />
-            </imageobject>
-          </inlinemediaobject>
+          <graphic
+            fileref="images/warning.gif" />
           Due to traditional Unix security restrictions, ports less than 1024 were "trusted". Thus on a Unix-System, a
           non-root process must listen on a port greater than 1023.
         </para>
@@ -778,8 +738,9 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
           <listitem>
             <para>
               <xref
-                linkend="">Configuration Parameters Reference</xref>
-              : A Description of all configuration parameters in server.xml
+                linkend="Configuration Parameters Reference" />
+              : A Description of all configuration parameters in
+              <emphasis>server.xml</emphasis>
             </para>
           </listitem>
         </itemizedlist>
@@ -801,24 +762,16 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="New LDAP Connection">
           <title>New LDAP Connection</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/NewLDAPConnection1.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/NewLDAPConnection1.png" />
         </figure>
         <para>... and in the next step, enter the admin DN uid=admin,ou=system and the current password (default is
           "secret"). Saving the password is not necessary, we will change it anyway. </para>
         <figure
           id="New LDAP Connection 2">
           <title>New LDAP Connection 2</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/NewLDAPConnection2.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/NewLDAPConnection2.png" />
         </figure>
         <para>
           Click
@@ -837,12 +790,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="Entry Editor">
           <title>Entry Editor</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/entryEditor.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/entryEditor.png" />
         </figure>
         <para>The Password Editor dialog shows up; enter the new password. You can optionally select a hash algorithm
           like
@@ -851,12 +800,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="Password Editor">
           <title>Password Editor</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/passwordEditor.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/passwordEditor.png" />
         </figure>
         <para>
           Pressing
@@ -878,12 +823,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="Connection Properties">
           <title>Connection Properties</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/connectionProperties.png" />
-            </imageobject>
-          </mediaobject>
+          <grpahic
+            fileref="images/connectionProperties.png" />
         </figure>
         <para>
           Enter the new password and press
@@ -914,25 +855,25 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <listitem>
           <para>
             <xref
-              linkend="What are partitions?">What are partitions?</xref>
+              linkend="What are partitions?" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Minimal partition definition">Minimal partition definition</xref>
+              linkend="Minimal partition definition" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Adding a partition programmatically">Adding a partition programmatically</xref>
+              linkend="Adding a partition programmatically" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="More configuration options for a JDBM partition">More configuration options for a JDBM partition</xref>
+              linkend="More configuration options for a JDBM partition" />
           </para>
         </listitem>
       </itemizedlist>
@@ -954,12 +895,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="Partitions in Studio after install">
           <title>Partitions in Studio after install</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/partitions_in_studio_after_install.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/partitions_in_studio_after_install.png" />
         </figure>
         <para>The schema subsystem and ApacheDS itself store their information in special partitions, "ou=schema" and
           "ou=system" respectively.</para>
@@ -1000,12 +937,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <figure
           id="Root DSE">
           <title>Root DSE</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/root_dse.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/root_dse.png" />
         </figure>
         <para>Before using the partition (e.g. adding entries), you have to add a context entry. If you plan to load
           LDIF data to your partition anyway, simply provide the context entry (the "root" of your partition) as a first
@@ -1031,12 +964,8 @@ description: The context entry for suffi
         <figure
           id="Partitions in Studio after adding">
           <title>Partitions in Studio after adding</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/partitions_in_studio_after_adding.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/partitions_in_studio_after_adding.png" />
         </figure>
       </section>
       <section
@@ -1178,37 +1107,37 @@ directoryService.getPartitionNexus().add
         <listitem>
           <para>
             <xref
-              linkend="ApacheDS and logging">ApacheDS and logging</xref>
+              linkend="ApacheDS and logging" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Default behavior after installation">Default behavior after installation</xref>
+              linkend="Default behavior after installation" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Adjusting logging to your needs">Adjusting logging to your needs</xref>
+              linkend="Adjusting logging to your needs" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Example configurations">Example configurations</xref>
+              linkend="Example configurations" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Log settings of the Windows daemon process">Log settings of the Windows daemon process</xref>
+              linkend="Log settings of the Windows daemon process" />
           </para>
         </listitem>
         <listitem>
           <para>
             <xref
-              linkend="Resources logging">Resources</xref>
+              linkend="Resources logging" />
           </para>
         </listitem>
       </itemizedlist>
@@ -1521,12 +1450,8 @@ log4j.appender.R.layout.ConversionPatter
 ...
           ]]></programlisting>
           <warning>
-            <mediaobject>
-              <imageobject>
-                <imagedata
-                  fileref="images/forbidden.gif" />
-              </imageobject>
-            </mediaobject>
+            <graphic
+              fileref="images/forbidden.gif" />
             <title>Warning</title>
             <para>"Generating caller location information like with %M or %L is extremely slow. Its use should be
               avoided unless execution speed is not an issue." (from the log4j documentation)</para>
@@ -1578,12 +1503,8 @@ log4j.logger.org.apache.directory.server
         <figure
           id="W32 Service Properties">
           <title>W32 Service Properties</title>
-          <mediaobject>
-            <imageobject>
-              <imagedata
-                fileref="images/w32_service_properties.png" />
-            </imageobject>
-          </mediaobject>
+          <graphic
+            fileref="images/w32_service_properties.png" />
         </figure>
         <para>You can adjust the logging level and a log path. Note that this is for the daemon only. The server itself
           is configured as described above.</para>
@@ -1643,25 +1564,25 @@ log4j.logger.org.apache.directory.server
       <listitem>
         <para>
           <xref
-            linkend="Basic server parameters">Basic server parameters</xref>
+            linkend="Basic server parameters" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="LDAP Clients">LDAP Clients</xref>
+            linkend="LDAP Clients" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="The sample data (Sailors of the seven seas)">The sample data (Sailors of the seven seas)</xref>
+            linkend="The sample data (Sailors of the seven seas)" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Resources RFC 2849">Resources</xref>
+            linkend="Resources RFC 2849" />
         </para>
       </listitem>
     </itemizedlist>
@@ -1763,12 +1684,8 @@ log4j.logger.org.apache.directory.server
       <figure
         id="Sample LDAP tree structure">
         <title>Sample LDAP tree structure</title>
-        <mediaobject>
-          <imageobject>
-            <imagedata
-              fileref="images/sample_structure.gif" />
-          </imageobject>
-        </mediaobject>
+        <graphic
+          fileref="images/sample_structure.gif" />
       </figure>
       <para>This snippet of the file represents a single entry, just to give you an impression of how LDIF files look
         like.</para>
@@ -1794,14 +1711,14 @@ manager: cn=William Bligh,ou=people,o=se
           <para>
             Download and install the server, described im
             <xref
-              linkend="Installing and starting the server">Installing and starting the server</xref>
+              linkend="Installing and starting the server" />
           </para>
         </listitem>
         <listitem>
           <para>
             Configure a partition for the sample date, described in
             <xref
-              linkend="Basic configuration tasks">Basic configuration tasks</xref>
+              linkend="Basic configuration tasks" />
           </para>
         </listitem>
         <listitem>

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml?rev=984856&r1=984855&r2=984856&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_basic_security.xml Thu Aug 12 16:40:48 2010
@@ -19,71 +19,1448 @@
       <listitem>
         <para>
           <xref
-            linkend="What is authentication?">What is authentication?</xref>
+            linkend="What is authentication?" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Simple binds">Simple binds</xref>
+            linkend="Simple binds" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Passwords stored one-way encrypted">Passwords stored one-way encrypted</xref>
+            linkend="Passwords stored one-way encrypted" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Anonymous binds">Anonymous binds</xref>
+            linkend="Anonymous binds" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="How to authenticate a user by uid and password?">How to authenticate a user by uid and password?</xref>
+            linkend="How to authenticate a user by uid and password?" />
         </para>
       </listitem>
       <listitem>
         <para>
           <xref
-            linkend="Resources encryption">Resources</xref>
+            linkend="Resources encryption" />
         </para>
       </listitem>
     </itemizedlist>
     <section
       id="What is authentication?">
       <title>What is authentication?</title>
+      <para>
+        <emphasis
+          role="bold">Authentication</emphasis>
+        is the process of determining whether someone (or something) in fact is what he/she/it asserts to be.
+      </para>
+      <para>
+        Within ApacheDS you will likely want to authenticate clients in order to check whether they are allowed to read,
+        add or manipulate certain data stored within the directory. The latter, i.e. whether an authenticated client is
+        permitted to do something, is deduced during
+        <emphasis
+          role="bold">authorization</emphasis>
+        .
+      </para>
+      <para>Quite often, the process of authentication is delegated to a directory service by other software components.
+        Because in doing so, authentication data (e.g. username, password) and authorization data (e.g. group
+        relationships) are stored and managed centrally in the directory, and all connected software solutions benefit
+        from it. The integration sections of this guide provide examples for Apache Tomcat, Apache HTTP servers, and
+        others.</para>
+      <para>
+        ApacheDS 1.5 supports simple authentication and anonymous binds while storing passwords within
+        <emphasis>userPassword</emphasis>
+        attributes in user entries. Passwords can be stored in clear text or one-way encrypted with a hash algorithm
+        like MD5 or SHA1. Since version 1.5.1, SASL mechanism are supported as well. We start with anonymous binds.
+      </para>
     </section>
     <section
       id="Simple binds">
       <title>Simple binds</title>
+      <para>Authentication via simple bind is widely used. The method is supported by ApacheDS 1.5 for all person
+        entries stored within any partition, if they contain a password attribute. How does it work? An LDAP client
+        provides the DN of a user entry and a password to the server, the parameters of the bind operation. ApacheDS
+        checks whether the given password is the same as the one stored in the userpassword attribute of the given
+        entry. If not, the bind operation fails (LDAP error code 49, LDAP_INVALID_CREDENTIALS), and the user is not
+        authenticated.</para>
+      <section
+        id="Using command line tools">
+        <title>Using command line tools</title>
+        <para>Assume this entry from the Seven Seas partition is stored within the directory (only a fragment with the
+          relevant attributes is shown).</para>
+        <programlisting><![CDATA[
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+cn: Horatio Hornblower
+sn: Hornblower
+userpassword: pass
+...
+        ]]></programlisting>
+        <para>In the following search command, a user tries to bind with the given DN (option -D) but a wrong password
+          (option -w). The bind fails and the command terminates without performing the search.</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
+    -w wrong -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
+ldap_simple_bind: Invalid credentials
+ldap_simple_bind: additional info: Bind failed: null
+        ]]></programlisting>
+        <para>If the user provides the correct password during the call of the ldapsearch command, the bind operation
+          succeeds and the seach operation is performed afterwards.</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
+    -w pass -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
+version: 1
+dn: ou=people,o=sevenSeas
+ou: people
+description: Contains entries which describe persons (seamen)
+objectclass: organizationalUnit
+objectclass: top
+        ]]></programlisting>
+      </section>
+      <section
+        id="Binds from Java components using JNDI">
+        <title>Binds from Java components using JNDI</title>
+        <para>Using JNDI, authentication via simple binds is accomplished by appropriate configuration. One option is to
+          provide the parameters in a Hashtable object like this</para>
+        <example
+          id="Binds from Java components using JNDI listing">
+          <title>Binds from Java components using JNDI</title>
+          <programlisting><![CDATA[
+import java.util.Hashtable;
+
+import javax.naming.Context;
+import javax.naming.InitialContext;
+import javax.naming.NamingEnumeration;
+import javax.naming.NamingException;
+
+public class SimpleBindDemo {
+
+    public static void main(String[] args) throws NamingException {
+
+        if (args.length < 2) {
+            System.err.println("Usage: java SimpleBindDemo <userDN> <password>");
+            System.exit(1);
+        }
+
+        Hashtable env = new Hashtable();
+        env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
+        env.put(Context.PROVIDER_URL, "ldap://zanzibar:10389/o=sevenSeas");
+
+        env.put(Context.SECURITY_AUTHENTICATION, "simple");
+        env.put(Context.SECURITY_PRINCIPAL, args[0]);
+        env.put(Context.SECURITY_CREDENTIALS, args[1]);
+
+        try {
+            Context ctx = new InitialContext(env);
+            NamingEnumeration enm = ctx.list("");
+            while (enm.hasMore()) {
+                System.out.println(enm.next());
+            }
+            ctx.close();
+        } catch (NamingException e) {
+            System.out.println(e.getMessage());
+        }
+    }
+}
+        ]]></programlisting>
+        </example>
+        <para>If the DN of a user entry and the fitting password are provided as command line arguments, the program
+          binds successfully and performs a search:</para>
+        <programlisting><![CDATA[
+$ java SimpleBindDemo "cn=Horatio Hornblower,ou=people,o=sevenSeas" pass
+ou=people: javax.naming.directory.DirContext
+ou=groups: javax.naming.directory.DirContext
+        ]]></programlisting>
+        <para>
+          On the other hand, providing an incorrect password results in a failed bind operation. JNDI maps it to a
+          <emphasis>NamingException</emphasis>
+          :
+        </para>
+        <programlisting><![CDATA[
+$ java SimpleBindDemo "cn=Horatio Hornblower,ou=people,o=sevenSeas" quatsch
+[LDAP: error code 49 - Bind failed: null]
+        ]]></programlisting>
+        <para>
+          In real life, you obviously want to separate most of the configuration data from the source code, for instance
+          with the help of the
+          <emphasis>jndi.properties</emphasis>
+          file.
+        </para>
+      </section>
     </section>
     <section
       id="Passwords stored one-way encrypted">
       <title>Passwords stored one-way encrypted</title>
+      <para>
+        If passwords are stored in the directory in clear like above, the administrator (
+        <emphasis>uid=admin,ou=system</emphasis>
+        ) is able to read them. This holds true even if authorization is enabled. The passwords would also be visible in
+        exported LDIF files. This is often unacceptable.
+      </para>
+      <para>
+        <warning>
+          <graphic
+            fileref="images/forbidden.gif" />
+          Not only the administrator will be able to read your password, or be visible in LDIF files, but if one does
+          not use SSL, the the password is transmitted in clear text above the wire...
+        </warning>
+      </para>
+      <section
+        id="Passwords not stored in clear text">
+        <title>Passwords not stored in clear text</title>
+        <para>
+          ApacheDS does also support simple binds, if user passwords are stored one-way encrypted. An LDAP client, which
+          creates user entries, applies a hash-function (SHA for instance) to the user passwords beforehand, and stores
+          the users with these fingerprints as
+          <emphasis>userpassword</emphasis>
+          values (instead of the clear text values), for instance:
+        </para>
+        <programlisting><![CDATA[
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+cn: Horatio Hornblower
+sn: Hornblower
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+...
+        ]]></programlisting>
+        <para>The value "{SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=" means that SHA (Secure Hash Algorithm) was applied to the
+          password, and "nU4eI71bcnBGqeO0t9tXvY1u5oQ=" was the result (Base-64 encoded). Please note that it is not
+          possible to calculate the source ("pass" in our case) back from the result. This is why it is called one-way
+          encrypted â it is rather difficult to decrypt it. One may guess many times, calculate the hash values (the
+          algorithms are public) and compare the result. But this would take a long time, especially if you choose a
+          more complex password than we did ("pass"). </para>
+      </section>
+      <section
+        id="But how to obtain the hash value for a password?">
+        <title>But how to obtain the hash value for a password?</title>
+        <para>With some lines of code, it is quite easy to accomplish this task programatically in Java:</para>
+        <example
+          id="Obtain the hash value for a password programatically">
+          <title>Obtain the hash value for a password programatically</title>
+          <programlisting><![CDATA[
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import sun.misc.BASE64Encoder;
+
+public class DigestDemo {
+    public static void main(String[] args) throws NoSuchAlgorithmException {
+        String password = "pass";
+        String algorithm = "SHA";
+        
+        // Calculate hash value
+        MessageDigest md = MessageDigest.getInstance(algorithm);
+        md.update(password.getBytes());
+        byte[] bytes = md.digest();
+        
+        // Print out value in Base64 encoding
+        BASE64Encoder base64encoder = new BASE64Encoder();
+        String hash = base64encoder.encode(bytes);        
+        System.out.println('{'+algorithm+'}'+hash);
+    }
+}
+      ]]></programlisting>
+        </example>
+        <para>The output is "{SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=".</para>
+        <para>
+          Another option is to use command line tools to calculate the hash value; the
+          <ulink
+            url="http://www.openssl.org/">OpenSSL</ulink>
+          project provides such
+          stuff. Furthermore many UI LDAP tools allow you to store passwords automatically
+          encrypted with the hash
+          algorithm of your choice. See below
+          <ulink
+            url="http://directory.apache.org/studio/">Apache Directory Studio</ulink>
+          as an example. The dialog automatically shows up
+          if a userPassword attribute is to be manipulated (added,
+          changed).
+        </para>
+        <figure
+          id="Password Editor figure">
+          <title>Password Editor</title>
+          <graphic
+            fileref="images/password_edit_ls.png" />
+        </figure>
+      </section>
+      <section
+        id="From an LDAP client point of view">
+        <title>From an LDAP client point of view</title>
+        <para>From an LDAP client point of view, the behavior during authentication is the same as with passwords stored
+          in clear. During a simple bind, a client sends DN and password (unencrypted, i.e. no hash algorithm applied)
+          to the server. If ApacheDS detects, that the user password for the given DN is stored in the directory with a
+          hash function applied, it calculates the hash value of the given password with the appropriate algorithm (this
+          is why the algorithm is stored together with the hashed password). Afterwards it compares the result with the
+          stored attribute value. In case of a match, the bind operation ends successfully:</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\ 
+    -w pass -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
+version: 1
+dn: ou=people,o=sevenSeas
+ou: people
+description: Contains entries which describe persons (seamen)
+objectclass: organizationalUnit
+objectclass: top
+      ]]></programlisting>
+        <para>
+          Providing the hashed value of the
+          <emphasis>userPassword</emphasis>
+          attribute instead of the original value will be rejected by ApacheDS:
+        </para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
+    -w "{SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=" -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
+ldap_simple_bind: Invalid credentials
+ldap_simple_bind: additional info: Bind failed: null
+      ]]></programlisting>
+        <para>This is intended. If someone was able to catch this value (from an LDIF export for instance), s/he must
+          still provide the password itself in order to get authenticated.</para>
+        <para>
+          <warning>
+            <graphic
+              fileref="images/warning.gif" />
+            <emphasis
+              role="bold">Be Warned: Limited security added</emphasis>
+            <para>Please note that storing user passwords one-way encrypted only adds limited security. During the bind
+              operation, the credentials are still transmitted unencrypted, if no SSL/TLS communication is used (thus
+              you should definitely consider to do so). </para>
+            <para>Furthermore, if someone gets an LDIF file with userpassword values digested with SHA etc., s/he may be
+              able to determine some of the passwords with brute force. Calculation of hash functions can be done very
+              fast, and the attacker can attempt millions of values with ease, without you getting notice of it.
+              Therefore protect your data, even if one-way encryption is applied to the passwords!</para>
+          </warning>
+        </para>
+      </section>
     </section>
     <section
       id="Anonymous binds">
       <title>Anonymous binds</title>
+      <para>In some occasions it is appropriate to allow LDAP clients to permit operations without authentication. If
+        data managed by the directory service is well known by all clients, it is not uncommon to allow search
+        operations (not manipulation) within this data to all clients â without providing credentials. An example for
+        this are enterprise wide telephone books, if clients access the directory service from the intranet.</para>
+      <section
+        id="Enable/disable anonymous binds">
+        <title>Enable/disable anonymous binds</title>
+        <para>
+          Anonymous access is enabled by default. Changing this is one of the basic configuration tasks. If you use
+          the
+          server standalone configured with a
+          <emphasis>server.xml</emphasis>
+          file, you can enable/disable it by changing the value for
+          property
+          <emphasis>allowAnonymousAccess</emphasis>
+          in the Spring bean definition for bean
+          <emphasis>defaultDirectoryService</emphasis>
+          , as depicted in
+          the following fragment:
+        </para>
+        <programlisting><![CDATA[
+<defaultDirectoryService id="directoryService" instanceId="default"
+                           ...
+                           allowAnonymousAccess="false"
+                           ...>
+      ]]></programlisting>
+        <para>A restart of the server is necessary for this change to take effect.</para>
+      </section>
+      <section
+        id="Example: Server behavior with anonymous binds disabled">
+        <title>Example: Server behavior with anonymous binds disabled</title>
+        <para>Now the same command performed against ApacheDS 1.5 with anonymous access enabled as described above. The
+          behavior is different â the entry is visible.</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
+version: 1
+dn: ou=people,o=sevenSeas
+ou: people
+description: Contains entries which describe persons (seamen)
+objectclass: organizationalUnit
+objectclass: top
+      ]]></programlisting>
+      </section>
+      <section
+        id="Other clients">
+        <title>Other clients</title>
+        <para>
+          The examples above have used a command line tool. Of course graphical tools and programmatical access (JNDI
+          etc.) allow anonymous binds as well. Below is a screen shot from the configuration dialog of
+          <ulink
+            url="http://directory.apache.org/studio/">Apache Directory Studio</ulink>
+          as an example. During configuration of the connection data ("New LDAP Connection", for instance), the option
+          <emphasis>Anonymous Authentication</emphasis>
+          leads to anonymous binds. Other UI tools offer this feature as well.
+        </para>
+        <figure
+          id="Anonymous Authentication figure">
+          <title>Anonymous Authentication</title>
+          <graphic
+            fileref="images/authentication_options_ls.png" />
+        </figure>
+        <para>
+          <warning>
+            <graphic
+              fileref="images/warning.gif" />
+            <emphasis
+              role="bold">Use this feature wisely</emphasis>
+            <para>
+              With anonymous access enabled it is not only possible to search the directory without providing username
+              and password. With autorization disabled, anonymous users may also be able to modify data. It is therefore
+              highly recommended to enable and configure the authorization subsystem as well. Learn more about
+              authorization in the
+              <xref
+                linkend="Basic authorization" />
+              section
+            </para>
+          </warning>
+        </para>
+      </section>
     </section>
     <section
       id="How to authenticate a user by uid and password?">
       <title>How to authenticate a user by uid and password?</title>
+      <para>
+        If you want to use simple binds with user DN and password within a Java component, in order to authenticate
+        users programatically, in practice one problem arises: Most users do not know their DN. Therefore they will not
+        be able to enter it. And even if they know it, it would be frequently very laborious due to the length of the
+        DN. It would be easier for a user if s/he only has to probvide a short, unique
+        <emphasis>ID</emphasis>
+        and the password, like in this
+        web form
+      </para>
+      <figure
+        id="Authenticate a user by uid and password figure">
+        <title>Authenticate a user by uid and password</title>
+        <graphic
+          fileref="images/confluence_logon.png" />
+      </figure>
+      <para>
+        Usually the ID is an attribute within the user's entry. In our sample data (Seven Seas), each user entry
+        contains the
+        <emphasis>uid</emphasis>
+        attribute, for instance uid=hhornblo for Captain Hornblower:
+      </para>
+      <programlisting><![CDATA[
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Horatio Hornblower
+description: Capt. Horatio Hornblower, R.N
+givenname: Horatio
+sn: Hornblower
+uid: hhornblo
+mail: hhornblo@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+      ]]></programlisting>
+      <para>But how to authenticate a user who provides "hhornblo"/"pass" instead of "cn=Horatio
+        Hornblower,ou=people,o=sevenSeas"/"pass" with the help of ApacheDS?</para>
+      <section
+        id="An algorithm">
+        <title>An algorithm</title>
+        <para>In order to accomplish this task programmatically, one option is to perform the following steps</para>
+      </section>
+      <section>
+        <title>Arguments</title>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <emphasis>uid</emphasis>
+              of a user (e.g. "hhornblow")
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              <emphasis>password</emphasis>
+              proclaimed to be correct for the user
+            </para>
+          </listitem>
+        </itemizedlist>
+      </section>
+      <section>
+        <title>Steps</title>
+        <orderedlist>
+          <listitem>
+            <para>Bind to ApacheDS anonymously, or with the DN of a technical user. In both cases it must be possible to
+              search the directory afterwards (authorization has to be configured that way)</para>
+          </listitem>
+          <listitem>
+            <para>
+              Perform a search operation with an appropriate filter to find the user entry for the given ID, in our case
+              "(&amp;(objectClass=inetorgperson)(uid=hhornblo))"
+              <itemizedlist
+                mark="opencircle">
+                <listitem>
+                  <para>If the search result is empty, the user does not exist â terminate</para>
+                </listitem>
+                <listitem>
+                  <para>If the search result contains more than one entry, the given ID is not unique, this is likely a
+                    data error within your directory</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              Bind to ApacheDS with the DN of the entry found in the previous search, and the
+              <emphasis>password</emphasis>
+              provided as argument
+              <itemizedlist
+                mark="opencircle">
+                <listitem>
+                  <para>If the bind operation fails, the password is wrong, and the result is false (not authenticated)
+                  </para>
+                </listitem>
+                <listitem>
+                  <para>If the bind is successful, authenticate the user</para>
+                </listitem>
+              </itemizedlist>
+            </para>
+          </listitem>
+        </orderedlist>
+      </section>
+      <section
+        id="Sample code with JNDI">
+        <title>Sample code with JNDI</title>
+        <para>The algorithm described above is implemented by many software solutions which are able to integrate LDAP
+          directories. You will learn more about some of them and their configuration options within a later section of
+          this guide</para>
+        <para>For illustration purposes, here is a simple Java program which performs the steps with the help of JNDI.
+          It uses anonymous bind for the first step, hence it must be enabled (replace with a technical user, if it
+          better meets your requirements).</para>
+        <example
+          id="Sample code with JNDI example">
+          <title>Sample code with JNDI</title>
+          <programlisting><![CDATA[
+import java.util.Hashtable;
+import javax.naming.Context;
+import javax.naming.NamingEnumeration;
+import javax.naming.NamingException;
+import javax.naming.directory.DirContext;
+import javax.naming.directory.InitialDirContext;
+import javax.naming.directory.SearchControls;
+import javax.naming.directory.SearchResult;
+
+public class AdvancedBindDemo {
+
+    public static void main(String[] args) throws NamingException {
+
+        if (args.length < 2) {
+            System.err.println("Usage: java AdvancedBindDemo <uid> <password>");
+            System.exit(1);
+        }
+
+        Hashtable env = new Hashtable();
+        env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
+        env.put(Context.PROVIDER_URL, "ldap://zanzibar:10389/");
+        env.put(Context.SECURITY_AUTHENTICATION, "simple");
+        
+        String uid = args[0];
+        String password = args[1];
+
+        DirContext ctx = null;
+        try {            
+            // Step 1: Bind anonymously            
+            ctx = new InitialDirContext(env);
+            
+            // Step 2: Search the directory
+            String base = "o=sevenSeas";
+            String filter = "(&(objectClass=inetOrgPerson)(uid={0}))";           
+            SearchControls ctls = new SearchControls();
+            ctls.setSearchScope(SearchControls.SUBTREE_SCOPE);
+            ctls.setReturningAttributes(new String[0]);
+            ctls.setReturningObjFlag(true);
+            NamingEnumeration enm = ctx.search(base, filter, new String[] { uid }, ctls);
+            
+            String dn = null;
+            if (enm.hasMore()) {
+                SearchResult result = (SearchResult) enm.next();
+                dn = result.getNameInNamespace();
+                
+                System.out.println("dn: "+dn);
+            }
+            
+            if (dn == null || enm.hasMore()) {
+                // uid not found or not unique
+                throw new NamingException("Authentication failed");
+            }
+            
+            // Step 3: Bind with found DN and given password
+            ctx.addToEnvironment(Context.SECURITY_PRINCIPAL, dn);
+            ctx.addToEnvironment(Context.SECURITY_CREDENTIALS, password);
+            // Perform a lookup in order to force a bind operation with JNDI
+            ctx.lookup(dn);
+            System.out.println("Authentication successful");
+            
+        } catch (NamingException e) {
+            System.out.println(e.getMessage());
+        } finally {
+            ctx.close();
+        }
+    }
+}
+      ]]></programlisting>
+        </example>
+        <para>Some example calls:</para>
+        <programlisting><![CDATA[
+$ java AdvancedBindDemo unknown sailor
+Authentication failed
+
+$ java AdvancedBindDemo hornblo pass
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+Authentication successful
+
+$ java AdvancedBindDemo hornblo quatsch
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+[LDAP: error code 49 - Bind failed: null]
+      ]]></programlisting>
+        <para>
+          The examples consist of an unknown user (an
+          <emphasis>inetOrgPerson</emphasis>
+          entry with uid=unknown does not exist), a successful authenttication, and an attempt with an existing uid but
+          a wrong password.
+        </para>
+      </section>
     </section>
     <section
       id="Resources encryption">
       <title>Resources</title>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <ulink
+              url="http://www.faqs.org/rfcs/rfc2829.html">RFC 2829</ulink>
+            Authentication Methods for LDAP
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <ulink
+              url="http://www.secure-hash-algorithm-md5-sha-1.co.uk/">The Secure Hash Algorithm Directory</ulink>
+            MD5, SHA-1 and HMAC Resources
+          </para>
+        </listitem>
+      </itemizedlist>
     </section>
   </section>
   <section
     id="Basic authorization">
     <title>Basic authorization</title>
+    <para>This section describes the default authorization functionality of ApacheDS 1.5, which is very simple. On the
+      other hand, it is inadequate for most serious deployments. Therefore a basic example to the "real" authorization
+      subsystem is provided as well.</para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <xref
+            linkend="What is authorization?" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Default authorization behavior for directory operations" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Simple example for the ACI subsystem" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Verification, that it works" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Resources Basic Authorization" />
+        </para>
+      </listitem>
+    </itemizedlist>
+    <section
+      id="What is authorization?">
+      <title>What is authorization?</title>
+      <para>After authentication of a user or an application (or more generally an LDAP client) against the directory
+        server (or attaining anonymous access respectively), certain LDAP operations will be granted or rejected,
+        according to configuration and certain rules. This process of granting access is called authorization.</para>
+      <para>
+        Authorization for directory operations is not strictly standardized in the LDAP world,
+        <ulink
+          url="http://www.faqs.org/rfcs/rfc2829.html">RFC 2829</ulink>
+        describes
+        various scenarios and concepts, but does not enforce a concrete implementation. Thus each product comes
+        with its
+        own authorization feature. So does ApacheDS. A powerful authorization subsystem is provided since
+        version 0.9.3,
+        but disabled as a default.
+      </para>
+      <section
+        id="Authorization for directory operations vs. group membership">
+        <title>Authorization for directory operations vs. group membership</title>
+        <para>
+          In order to accomplish their authorization functionality, software components often take advantage of LDAP
+          groups stored within the directory.
+          <emphasis>groupOfNames</emphasis>
+          and
+          <emphasis>groupOfUniqueNames</emphasis>
+          are common object classes for groups
+          entries; they contain the DNs of their members (users, other groups) as
+          attribute values.
+        </para>
+        <para>In order to illustrate this, the "Seven Seas" example partition contains such group entries below
+          "ou=groups,o=sevenSeas". Here the entry of a group describing the HMS Bounty crew (before the mutiny) in LDIF
+          format.</para>
+        <programlisting><![CDATA[
+dn: cn=HMS Bounty,ou=crews,ou=groups,o=sevenSeas
+objectclass: groupOfUniqueNames
+objectclass: top
+cn: HMS Bounty
+uniquemember: cn=William Bligh,ou=people,o=sevenSeas
+uniquemember: cn=Fletcher Christian,ou=people,o=sevenSeas
+uniquemember: cn=John Fryer,ou=people,o=sevenSeas
+...
+          ]]></programlisting>
+        <para>
+          In such a scenario, a user, who is directly or indirectly member of a certain group is permitted to do
+          something. The software component acts as a normal LDAP client and determines group belonging with the help of
+          ordinary search operations. This is widely used but has nothing to do with the authorization for directory
+          operations as described in this section (except that the client needs the permission to search the data).
+          Learn more about best practices in this area in the article
+          <ulink
+            url="http://middleware.internet2.edu/dir/groups/docs/internet2-mace-dir-groups-best-practices-200210.htm">Practices in Directory Groups</ulink>
+          . Further examples in
+          this guide are the Tomcat and Apache HTTPD integration sections.
+        </para>
+      </section>
+    </section>
+    <section
+      id="Default authorization behavior for directory operations">
+      <title>Default authorization behavior for directory operations</title>
+      <para>Without access controls enabled all 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.</para>
+      <section
+        id="Sample data within 'ou=users,ou=system'">
+        <title>Sample data within "ou=users,ou=system"</title>
+        <para>
+          In addition to our brave sailors below
+          <emphasis>ou=people,o=sevenSeas</emphasis>
+          , assume the following to entries present within
+          <emphasis>ou=users,ou=system</emphasis>
+          :
+        </para>
+        <figure
+          id="Authorization sample entire figure">
+          <title>Authorization sample entire</title>
+          <graphic
+            fileref="images/authorization_sample_entries.png" />
+        </figure>
+        <programlisting><![CDATA[
+dn: cn=Tori Amos,ou=users,ou=system
+objectclass: person
+objectclass: top
+sn: Amos
+cn: Tori Amos
+userpassword: amos
+
+dn: cn=Kate Bush,ou=users,ou=system
+objectclass: person
+objectclass: top
+sn: Bush
+cn: Kate Bush
+userpassword: bush
+        ]]></programlisting>
+        <para>
+          They are used in the following examples, in conjunction with
+          <emphasis>o=sevenSeas</emphasis>
+          , to describe the default authorization rules.
+        </para>
+      </section>
+      <section
+        id="Rules and sample operations">
+        <title>Rules and sample operations</title>
+        <para>Without ACIs the server automatically protects, hides, the admin user from everyone but the admin user.
+          Here a sample search operation in order to demonstrate this protection. The same command is submitted three
+          times with different users.</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\
+    -b "ou=system" -s one "(uid=admin)" dn
+version: 1
+dn: uid=admin,ou=system
+
+$ ldapsearch -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
+    -b "ou=system" -s one "(uid=admin)" dn
+
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Tori Amos,ou=users,ou=system" -w amos \\
+    -b "ou=system" -s one "(uid=admin)" dn
+
+$
+        ]]></programlisting>
+        <para>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.</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\
+    -b "ou=users,ou=system" -s one "(objectclass=*)" dn
+version: 1
+dn: cn=Tori Amos,ou=users,ou=system
+
+dn: cn=Kate Bush,ou=users,ou=system
+
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Kate Bush,ou=users,ou=system" -w bush \\
+    -b "ou=users,ou=system" -s one "(objectclass=*)" dn
+version: 1
+dn: cn=Kate Bush,ou=users,ou=system
+
+$ ldapsearch -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
+    -b "ou=users,ou=system" -s one "(objectclass=*)" dn
+
+$ ldapsearch -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
+    -b "ou=people,o=sevenSeas" -s one "(objectclass=*)" dn
+version: 1
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+
+dn: cn=William Bush,ou=people,o=sevenSeas
+
+dn: cn=Thomas Masterman Hardy,ou=people,o=sevenSeas
+
+dn: cn=Cornelius Buckley,ou=people,o=sevenSeas
+
+dn: cn=William Bligh,ou=people,o=sevenSeas
+...
+$
+        ]]></programlisting>
+        <para>
+          Groups defined using
+          <emphasis>groupOfNames</emphasis>
+          or
+          <emphasis>groupOfUniqueNames</emphasis>
+          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.
+        </para>
+      </section>
+      <section
+        id="Is this sufficient?">
+        <title>Is this sufficient?</title>
+        <para>For simple configurations the described rules 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 documentation on how to specify access control information in the Advanced User's Guide.</para>
+      </section>
+    </section>
+    <section
+      id="Simple example for the ACI subsystem">
+      <title>Simple example for the ACI subsystem</title>
+      <para>As an appetizer for the stunning ACI subsystem (ACI = access control item) within ApacheDS, we provide a
+        simple yet realistic example. It manifests the following requirements</para>
+      <section
+        id="Requirements met">
+        <title>Requirements met</title>
+        <orderedlist>
+          <listitem>
+            <para>Suffix "o=sevenSeas" used as Access Control Specific Area</para>
+          </listitem>
+          <listitem>
+            <para>User "cn=Horatio Nelson,ou=people,o=sevenSeas" should be able to perform all operations (delete, add,
+              ...) below the base "o=sevenSeas"</para>
+          </listitem>
+          <listitem>
+            <para>Other users and anonymous users should only be able to search and compare (no add, modify etc.)</para>
+          </listitem>
+          <listitem>
+            <para>Other users and anonymous users should not be able to read the userPassword attribute</para>
+          </listitem>
+        </orderedlist>
+      </section>
+      <section
+        id="Enable the ACI Subsystem">
+        <title>Enable the ACI Subsystem</title>
+        <para>
+          The authorization (ACI) subsystem is disabled by default. If you use the server standalone configured with
+          a
+          <emphasis>server.xml</emphasis>
+          file, you can enable it by changing the value for property
+          <emphasis>accessControlEnabled</emphasis>
+          in the Spring
+          bean definition for bean
+          <emphasis>defaultDirectoryService</emphasis>
+          , as depicted in the following fragment:
+        </para>
+        <programlisting><![CDATA[
+<defaultDirectoryService id="directoryService" instanceId="default"
+                           ...
+                           accessControlEnabled="true"
+                           ...>
+        ]]></programlisting>
+        <para>A restart of the server is necessary for this change to take effect.</para>
+      </section>
+      <section
+        id="Further configuration tasks to perform afterwards">
+        <title>Further configuration tasks to perform afterwards</title>
+        <orderedlist>
+          <listitem>
+            <para>
+              Create an operational attribute
+              <emphasis>administrativeRole</emphasis>
+              with value "accessControlSpecificArea" in the entry "o=sevenSeas".
+            </para>
+          </listitem>
+          <listitem>
+            <para>Create a subentry subordinate to "o=sevenSeas" to grant all operations' permissions to "cn=Horatio
+              Nelson,ou=people,o=sevenSeas", who acts as directory manager</para>
+            <para>The subentry should contain the following attributes and values:</para>
+            <programlisting><![CDATA[
+cn="sevenSeasAuthorizationRequirementsACISubentry"
+subtreeSpecification="{}"
+prescriptiveACI="{
+                   identificationTag "directoryManagerFullAccessACI",
+                   precedence 11,
+                   authenticationLevel simple,
+                   itemOrUserFirst userFirst:
+                   {
+                     userClasses
+                     {
+                       name { "cn=Horatio Nelson,ou=people,o=sevenSeas" }
+                     },
+                     userPermissions
+                     { 
+                       {
+                         protectedItems
+                         {
+                           entry, allUserAttributeTypesAndValues
+                         },
+                         grantsAndDenials
+                         {
+                           grantAdd, grantDiscloseOnError, grantRead,
+                           grantRemove, grantBrowse, grantExport, grantImport,
+                           grantModify, grantRename, grantReturnDN,
+                           grantCompare, grantFilterMatch, grantInvoke
+                         } 
+                       }
+                     }
+                   } 
+                 }"
+        ]]></programlisting>
+          </listitem>
+          <listitem>
+            <para>A new attribute value should added to the previously created Subentry's prescriptiveACI attribute to
+              grant search and compare permissions to all users.</para>
+            <para>The new value:</para>
+            <programlisting><![CDATA[
+prescriptiveACI="{
+                   identificationTag "allUsersSearchAndCompareACI",
+                   precedence 10,
+                   authenticationLevel simple,
+                   itemOrUserFirst userFirst:
+                   {
+                     userClasses
+                     {
+                       allUsers
+                     },
+                     userPermissions
+                     { 
+                       {
+                         protectedItems
+                         {
+                           entry, allUserAttributeTypesAndValues
+                         },
+                         grantsAndDenials
+                         {
+                           grantRead, grantBrowse, grantReturnDN,
+                           grantCompare, grantFilterMatch, grantDiscloseOnError 
+                         } 
+                       }
+                     }
+                   } 
+                 }"
+        ]]></programlisting>
+          </listitem>
+          <listitem>
+            <para>
+              A new attribute value should added to the previously created Subentry's prescriptiveACI attribute to deny
+              search and compare permissions for
+              <emphasis>userPassword</emphasis>
+              attribute to all users.
+            </para>
+            <para>The new value:</para>
+            <programlisting><![CDATA[
+prescriptiveACI="{
+                   identificationTag "preventAllUsersFromReadingUserPasswordAttributeACI",
+                   precedence 10,
+                   authenticationLevel simple,
+                   itemOrUserFirst userFirst:
+                   {
+                     userClasses
+                     {
+                       allUsers
+                     },
+                     userPermissions
+                     { 
+                       {
+                         protectedItems
+                         {
+                           attributeType { userPassword }
+                         },
+                         grantsAndDenials
+                         {
+                           denyRead, denyCompare, denyFilterMatch
+                         } 
+                       }
+                     }
+                   } 
+                 }"
+
+        ]]></programlisting>
+          </listitem>
+        </orderedlist>
+        <para>The two values given in 3 and 4 can be combined in a single value as:</para>
+        <programlisting><![CDATA[
+prescriptiveACI="{
+                   identificationTag "allUsersACI",
+                   precedence 10,
+                   authenticationLevel none,
+                   itemOrUserFirst userFirst:
+                   {
+                     userClasses
+                     {
+                       allUsers
+                     },
+                     userPermissions
+                     { 
+                       {
+                         protectedItems { entry, allUserAttributeTypesAndValues },
+                         grantsAndDenials { grantRead, grantBrowse, grantReturnDN,
+                                            grantCompare, grantFilterMatch, grantDiscloseOnError } 
+                       },
+                       {
+                         protectedItems { attributeType { userPassword } },
+                         grantsAndDenials { denyRead, denyCompare, denyFilterMatch }
+                       }
+                     }
+                   } 
+                 }"
+        ]]></programlisting>
+      </section>
+      <section
+        id="LDIF for this configuration">
+        <title>LDIF for this configuration</title>
+        <para>
+          The following LDIF file (
+          <ulink
+            url="data/authz_sevenSeas.ldif">authz_sevenSeas.ldif</ulink>
+          ) provides a set of changes made to directory entries in the
+          "Seven Seas" data. In total it performs the steps
+          described above.
+        </para>
+        <programlisting><![CDATA[
+# File authz_sevenSeas.ldif
+#
+# Create an operational attribute "administrativeRole"
+# with value "accessControlSpecificArea" in the entry "o=sevenSeas".
+#
+dn: o=sevenSeas
+changetype: modify
+add: administrativeRole
+administrativeRole: accessControlSpecificArea
+
+# Create a subentry subordinate to "o=sevenSeas" to grant all operations' permissions 
+# to "cn=Horatio Nelson,ou=people,o=sevenSeas", to grant search and compare permissions
+# to all users and to deny search and compare permissions for userPassword attribute to all users. 
+#
+dn: cn=sevenSeasAuthorizationRequirementsACISubentry,o=sevenSeas
+changetype: add
+objectclass: top
+objectclass: subentry
+objectclass: accessControlSubentry
+cn: sevenSeasAuthorizationRequirementsACISubentry
+subtreeSpecification: {}
+prescriptiveACI: {
+    identificationTag "directoryManagerFullAccessACI",
+    precedence 11,
+    authenticationLevel simple,
+    itemOrUserFirst userFirst:
+    {
+      userClasses
+      {
+        name { "cn=Horatio Nelson,ou=people,o=sevenSeas" }
+      },
+      userPermissions
+      { 
+        {
+          protectedItems
+          {
+            entry, allUserAttributeTypesAndValues
+          },
+          grantsAndDenials
+          {
+            grantAdd, grantDiscloseOnError, grantRead,
+            grantRemove, grantBrowse, grantExport, grantImport,
+            grantModify, grantRename, grantReturnDN,
+            grantCompare, grantFilterMatch, grantInvoke
+          } 
+        }
+      }
+    } 
+  }
+prescriptiveACI: {
+    identificationTag "allUsersACI",
+    precedence 10,
+    authenticationLevel none,
+    itemOrUserFirst userFirst:
+    {
+      userClasses
+      {
+        allUsers
+      },
+      userPermissions
+      { 
+        {
+          protectedItems { entry, allUserAttributeTypesAndValues },
+          grantsAndDenials { grantRead, grantBrowse, grantReturnDN,
+                             grantCompare, grantFilterMatch, grantDiscloseOnError } 
+        },
+        {
+          protectedItems { attributeType { userPassword } },
+          grantsAndDenials { denyRead, denyCompare, denyFilterMatch }
+        }
+      }
+    }
+  }
+        ]]></programlisting>
+        <para>To apply this configuration to the sample data partition, you can perform an ldapmodify with the LDIF as
+          agrument:</para>
+        <programlisting><![CDATA[
+$ ldapmodify -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret -f authz_sevenSeas.ldif
+modifying entry o=sevenSeas
+
+adding new entry cn=sevenSeasAuthorizationRequirementsACISubentry,o=sevenSeas
+$
+        ]]></programlisting>
+        <para>It is also possible to use graphical tools; some of them offer the feature to perform operations given in
+          LDIF.</para>
+      </section>
+    </section>
+    <section
+      id="Verification, that it works">
+      <title>Verification, that it works</title>
+      <para>After successfully applying the changes to the sample partition, one may ask how to check whether it works.
+        We therefore perform some operations with the help of command line tools. Some will be permitted, some will not
+        (and cause an appropriate error message). It would also be able to check this with the help of graphical tools
+        (you might like to do this instead). But it is easier to document the parameters used with the help command line
+        arguments.</para>
+      <section
+        id="Performing some search operations in order to read data">
+        <title>Performing some search operations in order to read data</title>
+        <para>Bind as user "William Bush" and search for entries which match "(uid=hhornblo)". Expected behavior: We are
+          able to read the attributes of entry "cn=Horatio Hornblower,ou=people,o=sevenSeas" (the only entry which
+          matches the filter). The password attribute should not be visible. It works as desired: </para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
+    -b "o=sevenSeas" -s sub "(uid=hhornblo)"
+version: 1
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+mail: hhornblo@royalnavy.mod.uk
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Horatio Hornblower
+uid: hhornblo
+givenname: Horatio
+description: Capt. Horatio Hornblower, R.N
+sn: Hornblower
+        ]]></programlisting>
+        <para>
+          In the described configuration, the user "Horatio Nelson" acts as a directory manager below "o=sevenSeas".
+          Hence he should basically be allowed to do everything. He should even be able to see other users'
+          <emphasis>userPassword</emphasis>
+          values. In our case, the hash function SHA was applied to them:
+        </para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
+    -b "o=sevenSeas" -s sub "(objectclass=person)
+" uid userPassword
+version: 1
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+uid: hhornblo
+
+dn: cn=William Bush,ou=people,o=sevenSeas
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+uid: wbush
+
+dn: cn=Thomas Quist,ou=people,o=sevenSeas
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+uid: tquist
+...
+        ]]></programlisting>
+        <para>But "Horation Nelson" is not able to perform searches in other areas than "o=sevenSeas" to see the
+          entries. Of course our global ApacheDS administrator "uid=admin,ou=system" is still able to see them:</para>
+        <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
+    -b "ou=system" -s sub "(objectclass=person)"
+
+$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\
+    -b "ou=system" -s sub "(objectclass=person)"
+version: 1
+dn: uid=admin,ou=system
+sn: administrator
+cn: system administrator
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+userpassword: secret
+uid: admin
+displayName: Directory Superuser
+
+dn: cn=Tori Amos,ou=users,ou=system
+cn: Tori Amos
+userpassword: amos
+objectclass: person
+objectclass: top
+sn: Amos
+...
+        ]]></programlisting>
+      </section>
+      <section
+        id="Trying to manipulate data">
+        <title>Trying to manipulate data</title>
+        <para>Until now the authorization only hided data (entries, attributes) from users with insufficient access
+          rights. Let's perform some operations which try to manipulate the directory data!</para>
+        <section
+          id="Adding an entry">
+          <title>Adding an entry</title>
+          <para>
+            First we try to add a new user to the "Seven Seas" partition. The data for the entry is inspired by "Peter
+            Pan" and provided by this LDIF file (
+            <ulink
+              url="data/captain_hook.ldif">captain_hook.ldif</ulink>
+            ):
+          </para>
+          <programlisting><![CDATA[
+# File captain_hook.ldif
+dn: cn=James Hook,ou=people,o=sevenSeas
+objectclass: inetOrgPerson
+objectclass: organizationalPerson
+objectclass: person
+objectclass: top
+cn: James Hook
+description: A pirate captain and Peter Pan's nemesis
+sn: Hook
+mail: jhook@neverland
+userpassword: peterPan
+        ]]></programlisting>
+          <para>An anonymous user is not allowed to create new entries, as the following error message shows:</para>
+          <programlisting><![CDATA[
+$ ldapmodify -h zanzibar -p 10389 -a -f captain_hook.ldif
+adding new entry cn=James Hook,ou=people,o=sevenSeas
+ldap_add: Insufficient access
+ldap_add: additional info: failed to add entry cn=James Hook,ou=people,o=sevenSeas: null
+$
+        ]]></programlisting>
+          <para>The same holds true for all "Seven Seas"-user other than "Horatio Nelson". The latter is permitted to do
+            so:</para>
+          <programlisting><![CDATA[
+$ ldapmodify -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
+    -a -f captain_hook.ldif
+adding new entry cn=James Hook,ou=people,o=sevenSeas
+ldap_add: Insufficient access
+ldap_add: additional info: failed to add entry cn=James Hook,ou=people,o=sevenSeas: null
+
+$ ldapmodify -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
+    -a -f captain_hook.ldif
+adding new entry cn=James Hook,ou=people,o=sevenSeas
+$
+        ]]></programlisting>
+          <para>
+            Afterwards a new entry is successfully created within the "Seven Seas" partition by user "Horatio Nelson".
+            The '+' sign in the attributes list of the
+            <emphasis>ldapsearch</emphasis>
+            command causes ApacheDS to return the operational attributes, which demonstrate this.
+          </para>
+          <programlisting><![CDATA[
+$ ldapsearch -h zanzibar -p 10389 -b "o=sevenSeas" -s sub "(cn=James Hook)" +
+version: 1
+dn: cn=James Hook,ou=people,o=sevenSeas
+accessControlSubentries: cn=sevenSeasAuthorizationRequirementsACISubentry,o=sevenSeas
+creatorsName: cn=Horatio Nelson,ou=people,o=sevenSeas
+createTimestamp: 20061203140109Z
+        ]]></programlisting>
+        </section>
+        <section
+          id="Modifying an entry">
+          <title>Modifying an entry</title>
+          <para>
+            As a further example which tries to write to the directory, we add a new value to the description attribute
+            of the freshly created entry for Captain Hook. With a change entry in an LDIF file, it looks like this (file
+            <ulink
+              url="data/captain_hook_modify.ldif">captain_hook_modify.ldif</ulink>
+            ):
+          </para>
+          <programlisting><![CDATA[
+# File captain_hook_modify.ldif
+dn: cn=James Hook,ou=people,o=sevenSeas
+changetype: modify
+add: description
+description: Wears an iron hook in place of his right hand
+-
+        ]]></programlisting>
+          <para>
+            Performing the modification with the
+            <emphasis>ldapmodify</emphasis>
+            command line tool again fails for users other than "Horation Nelson" (who is allowed to due to the
+            authorization configuration) and "uid=admin,ou=system".
+          </para>
+          <programlisting><![CDATA[
+$ ldapmodify -h zanzibar -p 10389 -f captain_hook_modify.ldif
+modifying entry cn=James Hook,ou=people,o=sevenSeas
+ldap_modify: Insufficient access
+ldap_modify: additional info: failed to modify entry cn=James Hook,ou=people,o=sevenSeas: null
+
+$ ldapmodify -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\ 
+    -f captain_hook_modify.ldif
+modifying entry cn=James Hook,ou=people,o=sevenSeas
+ldap_modify: Insufficient access
+ldap_modify: additional info: failed to modify entry cn=James Hook,ou=people,o=s
+evenSeas: null
+
+$ ldapmodify -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
+    -f captain_hook_modify.ldif
+modifying entry cn=James Hook,ou=people,o=sevenSeas
+        ]]></programlisting>
+        </section>
+        <section
+          id="Deleting an entry">
+          <title>Deleting an entry</title>
+          <para>
+            Now it is finale time. A demonstration on how to delete the villain's entry from the directory. With an LDIF
+            file (
+            <ulink
+              url="data/captain_hook_delete.ldif">captain_hook_delete.ldif</ulink>
+            ) with an appropriate change entry, this can easily be accomplished, if the bind user is allowed to do so.
+          </para>
+          <programlisting><![CDATA[
+# File captain_hook_delete.ldif
+dn: cn=James Hook,ou=people,o=sevenSeas
+changetype: delete
+        ]]></programlisting>
+          <para>
+            Applying this file with the help of
+            <emphasis>ldapmodify</emphasis>
+            results in a behavior comparable to the modification. Anonymous or "normal" users (like "William Bush") are
+            not permitted to delete Captain Hook's entry. The user "Horatio Nelson", our directory manager for "Seven
+            Seas", is:
+          </para>
+          <programlisting><![CDATA[
+$ ldapmodify -h zanzibar -p 10389 -f captain_hook_delete.ldif
+deleting entry cn=James Hook,ou=people,o=sevenSeas
+ldap_delete: Insufficient access
+ldap_delete: additional info: failed to delete entry cn=James Hook,ou=people,o=sevenSeas: null
+
+$ ldapmodify -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
+    -f captain_hook_delete.ldif
+deleting entry cn=James Hook,ou=people,o=sevenSeas
+ldap_delete: Insufficient access
+ldap_delete: additional info: failed to delete entry cn=James Hook,ou=people,o=sevenSeas: null
+
+$ ldapmodify -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
+    -f captain_hook_delete.ldif
+deleting entry cn=James Hook,ou=people,o=sevenSeas
+$
+        ]]></programlisting>
+          <para>The entry "cn=James Hook,ou=people,o=sevenSeas" has been successfully deleted from the partition. Our
+            little demonstration on how the ACI subsystem with a realistic configuration behaves end here. Learn more
+            about it in the Advanced User's Guide.</para>
+        </section>
+      </section>
+    </section>
+    <section
+      id="Resources Basic Authorization">
+      <title>Resources</title>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <ulink
+              url="http://middleware.internet2.edu/dir/groups/docs/internet2-mace-dir-groups-best-practices-200210.htm">Practices in Directory Groups</ulink>
+            describes how to use groups within LDAP directories. Highly recommended.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            The
+            <ulink
+              url="http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=DIRxSRVx11&amp;title=ApacheDS%20v1.0%20Advanced%20User%27s%20Guide&amp;linkCreation=true&amp;fromPageId=55244">ApacheDS v1.0 Advanced User's Guide</ulink>
+            provides a detailed authorization chapter
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            <ulink
+              url="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</ulink>
+            The LDAP Data Interchange Format (LDIF) is used extensively in this section
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
   </section>
   <section
     id="How to enable SSL">
     <title>How to enable SSL</title>
+    <para>This section describes the transport layer security options for LDAP, and especially how to enable LDAPS on
+      ApacheDS.</para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <xref
+            linkend="Transport layer security and LDAP" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Server configuration" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Verification, Clients" />
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Resources SSL" />
+        </para>
+      </listitem>
+    </itemizedlist>
+    <section
+      id="Transport layer security and LDAP">
+      <title>Transport layer security and LDAP</title>
+    </section>
+    <section
+      id="Server configuration">
+      <title>Server configuration</title>
+    </section>
+    <section
+      id="Verification, Clients">
+      <title>Verification, Clients</title>
+    </section>
+    <section
+      id="Resources SSL">
+      <title>Resources</title>
+    </section>
   </section>
 </chapter>

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_handling_of_data_within_your_directory.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_handling_of_data_within_your_directory.xml?rev=984856&r1=984855&r2=984856&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_handling_of_data_within_your_directory.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_handling_of_data_within_your_directory.xml Thu Aug 12 16:40:48 2010
@@ -7,7 +7,6 @@
   xmlns:ns5="http://www.w3.org/2000/svg"
   xmlns:ns4="http://www.w3.org/1998/Math/MathML"
   xmlns:ns3="http://www.w3.org/1999/xhtml"
-  xmlns:db="http://docbook.org/ns/docbook"
   xml:lang="en">
   <title>Handling of data within your directory </title>
 </chapter>

Modified: directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml?rev=984856&r1=984855&r2=984856&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/docbkx/chapter_integrating_apacheds_with_other_programs.xml Thu Aug 12 16:40:48 2010
@@ -7,7 +7,6 @@
   xmlns:ns5="http://www.w3.org/2000/svg"
   xmlns:ns4="http://www.w3.org/1998/Math/MathML"
   xmlns:ns3="http://www.w3.org/1999/xhtml"
-  xmlns:db="http://docbook.org/ns/docbook"
   xml:lang="en">
   <title>Integrating ApacheDS with other programs</title>
   <section>