directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fel...@apache.org
Subject svn commit: r984795 - in /directory/sandbox/felixk/apacheds-docs: ./ src/docbkx/ src/main/resources/data/
Date Thu, 12 Aug 2010 14:10:56 GMT
Author: felixk
Date: Thu Aug 12 14:10:56 2010
New Revision: 984795

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

Added:
    directory/sandbox/felixk/apacheds-docs/src/main/resources/data/
    directory/sandbox/felixk/apacheds-docs/src/main/resources/data/apache_ds_tutorial.ldif
Modified:
    directory/sandbox/felixk/apacheds-docs/pom.xml
    directory/sandbox/felixk/apacheds-docs/src/docbkx/basic_user_guide.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

Modified: directory/sandbox/felixk/apacheds-docs/pom.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/pom.xml?rev=984795&r1=984794&r2=984795&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/pom.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/pom.xml Thu Aug 12 14:10:56 2010
@@ -90,6 +90,10 @@
                 <copy todir="${project.build.directory}/docbkx/html/images">
                   <fileset dir="src/main/resources/images" />
                 </copy>
+                <!-- Copy the data -->
+                <copy todir="${project.build.directory}/docbkx/html/data">
+                  <fileset dir="src/main/resources/data" />
+                </copy>
               </postProcess>
             </configuration>
           </execution>

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=984795&r1=984794&r2=984795&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 14:10:56 2010
@@ -2,7 +2,6 @@
 <chapter
   version="5.0"
   xmlns="http://docbook.org/ns/docbook"
-  xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:ns5="http://www.w3.org/2000/svg"
   xmlns:ns4="http://www.w3.org/1998/Math/MathML"
@@ -23,8 +22,8 @@
     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
-    <link
-      xlink:href="http://directory.apache.org/apacheds/1.0/apacheds-v10-basic-users-guide.html">ApacheDS 1.0 Basic User's Guide</link>
+    <ulink
+      url="http://directory.apache.org/apacheds/1.0/apacheds-v10-basic-users-guide.html">ApacheDS 1.0 Basic User's Guide</ulink>
     , which is currently more complete.
   </para>
   <section>

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=984795&r1=984794&r2=984795&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 14:10:56 2010
@@ -126,14 +126,14 @@
       </para>
       <para>
         In October 2002 Alex Karasulu founded and registered the
-        <link
-          xlink:href="http://sourceforge.net/projects/ldapd">LDAPd</link>
+        <ulink
+          url="http://sourceforge.net/projects/ldapd">LDAPd</ulink>
         project at SourceForge.net. LDAPd was a a
         pure Java embeddable LDAP v3 protocol daemon built on the Avalon
         framework. Alex donated the code to the Apache
         Software Foundation and the code entered the
-        <link
-          xlink:href="http://incubator.apache.org/">Apache Incubator</link>
+        <ulink
+          url="http://incubator.apache.org/">Apache Incubator</ulink>
         in October 2003. One year later in October of
         2004,
         the Apache Directory Top Level Project (TLP) was formed after
@@ -157,15 +157,15 @@
         mark="bullet">
         <listitem>
           <para>
-            <link
-              xlink:href="http://directory.apache.org/community%26resources/proposal-for-an-apache-directory-project.html">Proposal for an Apache Directory Project</link>
+            <ulink
+              url="http://directory.apache.org/community%26resources/proposal-for-an-apache-directory-project.html">Proposal for an Apache Directory Project</ulink>
             the original proposal for incubation, September 2003.
           </para>
         </listitem>
         <listitem>
           <para>
-            <link
-              xlink:href="http://directory.apache.org/community%26resources/ldap-renaissance.html">Architecting the Modern LDAP Renaissance: The Apache Directory Vision</link>
+            <ulink
+              url="http://directory.apache.org/community%26resources/ldap-renaissance.html">Architecting the Modern LDAP Renaissance: The Apache Directory Vision</ulink>
             , Paper for 1st International Conference on LDAP, September 2007.
           </para>
         </listitem>
@@ -257,8 +257,8 @@
         both directory services and relational databases are actually used. Read how Vikas Mahajan
         describes directories
         and databases as complementary, not competitive, solutions in his excellent article
-        <link
-          xlink:href="http://support.novell.com/techcenter/articles/ana20011101.html">"Should I Use a Directory, a Database, or Both?"</link>
+        <ulink
+          url="http://support.novell.com/techcenter/articles/ana20011101.html">"Should I Use a Directory, a Database, or Both?"</ulink>
         .
       </para>
     </section>
@@ -439,8 +439,8 @@
           Good, Tim Howes
           Addison-Wesley Professional, 2nd Edition 2003
           ISBN: 0-672323-16-8
-          <link
-            xlink:href="http://awprofessional.com/title/0672323168">Book's Homepage (Howes)</link>
+          <ulink
+            url="http://awprofessional.com/title/0672323168">Book's Homepage (Howes)</ulink>
         </para>
         <para>
           LDAP fuer Java-Entwickler
@@ -464,8 +464,8 @@
           von Stefan Zoerner
           Software und Support Verlag, 3. aktualisierte Auflage 2007
           ISBN: 978-3-939084-07-5
-          <link
-            xlink:href="http://www.entwickler-press.de/buecher/ldap/">Webseite zum Buch (Zoerner)</link>
+          <ulink
+            url="http://www.entwickler-press.de/buecher/ldap/">Webseite zum Buch (Zoerner)</ulink>
         </para>
       </section>
       <section>
@@ -475,8 +475,8 @@
           <itemizedlist>
             <listitem>
               <para>
-                <link
-                  xlink:href="http://blogs.sun.com/roller/page/DirectoryManager">cn=Directory Manager - All about Directory Server</link>
+                <ulink
+                  url="http://blogs.sun.com/roller/page/DirectoryManager">cn=Directory Manager - All about Directory Server</ulink>
                 , Sun Blog
               </para>
             </listitem>
@@ -488,22 +488,22 @@
             mark="bullet">
             <listitem>
               <para>
-                <link
-                  xlink:href="http://www.redbooks.ibm.com/abstracts/SG244986.html?Open">Understanding LDAP - Design and Implementation</link>
+                <ulink
+                  url="http://www.redbooks.ibm.com/abstracts/SG244986.html?Open">Understanding LDAP - Design and Implementation</ulink>
                 , IBM RedBook, July 2006
               </para>
             </listitem>
             <listitem>
               <para>
-                <link
-                  xlink:href="http://www.oreillynet.com/pub/a/sysadmin/2006/07/27/demystifying-ldap.html">Demystifying LDAP</link>
+                <ulink
+                  url="http://www.oreillynet.com/pub/a/sysadmin/2006/07/27/demystifying-ldap.html">Demystifying LDAP</ulink>
                 by Brian K. Jones, O'Reilly Network
               </para>
             </listitem>
             <listitem>
               <para>
-                <link
-                  xlink:href="http://www.mitlinx.de/ldap/">LDAP verstehen mit linx</link>
+                <ulink
+                  url="http://www.mitlinx.de/ldap/">LDAP verstehen mit linx</ulink>
                 , by Petra Haberer
                 <inlinemediaobject>
                   <imageobject>
@@ -566,9 +566,9 @@
             <emphasis
               role="bold">Java 5.0</emphasis>
             . We recommend using
-            <link
-              xlink:href="http://java.sun.com/javase/downloads/index.jsp">
-              Sun's JDK</link>
+            <ulink
+              url="http://java.sun.com/javase/downloads/index.jsp">
+              Sun's JDK</ulink>
             , but the server has also been successfully tested
             with JRockit 5.0 and with IBM Java 5.0.
             You can check your
@@ -595,8 +595,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
             <emphasis
               role="bold">384 MB RAM</emphasis>
             for the JVM. That's the default setting, how to change that is described
-            <link
-              xlink:href="http://directory.apache.org/apacheds/1.5/14-basic-configuration-tasks.html#1.4.Basicconfigurationtasks-MemoryAllocation">here</link>
+            <ulink
+              url="http://directory.apache.org/apacheds/1.5/14-basic-configuration-tasks.html#1.4.Basicconfigurationtasks-MemoryAllocation">here</ulink>
           </para>
         </listitem>
       </itemizedlist>
@@ -630,15 +630,15 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
       </para>
       <para>
         You can download them from
-        <link
-          xlink:href="http://directory.apache.org/apacheds/1.5/downloads.html">here</link>
+        <ulink
+          url="http://directory.apache.org/apacheds/1.5/downloads.html">here</ulink>
         .
       </para>
       <para>
         option for people familiar with tools like Subversion and Maven is to built the server from the sources on their
         own. This is described
-        <link
-          xlink:href="http://directory.apache.org/community%26resources/sources.html">here</link>
+        <ulink
+          url="http://directory.apache.org/community%26resources/sources.html">here</ulink>
         .
       </para>
     </section>
@@ -707,8 +707,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
       <title>Installation on Linux and Solaris</title>
       <para>
         The installation for different installers is described on the
-        <link
-          xlink:href="http://directory.apache.org/apacheds/1.5/downloads.html">Apache Directory Server 1.5 Downloads</link>
+        <ulink
+          url="http://directory.apache.org/apacheds/1.5/downloads.html">Apache Directory Server 1.5 Downloads</ulink>
         page.
       </para>
     </section>
@@ -897,8 +897,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
         <itemizedlist>
           <listitem>
             <para>
-              <link
-                xlink:href="http://directory.apache.org/studio/">Apache Directory Studio</link>
+              <ulink
+                url="http://directory.apache.org/studio/">Apache Directory Studio</ulink>
               : The tool used in steps 1 and 2
             </para>
           </listitem>
@@ -945,8 +945,8 @@ HotSpot(TM) Client VM (build 1.5.0_06-b0
           particular partition are stored below some naming context called the partition suffix.</para>
         <para>
           The default implementation of partitions is based on
-          <link
-            xlink:href="http://jdbm.sourceforge.net/">JDBM</link>
+          <ulink
+            url="http://jdbm.sourceforge.net/">JDBM</ulink>
           B+Trees (but it's possible to add custom partition implementations). The ApacheDS default configuration
           contains a a data partition with the suffix "dc=example,dc=com". The image below shows the suffixes of a
           freshly installed ApacheDS within Apache Directory Studio.
@@ -1128,41 +1128,44 @@ directoryService.getPartitionNexus().add
         <para>Here is a list of the used attributes, their default values and meaning</para>
         <table
           id="More configuration options for a JDBM partition table">
-          <caption>More configuration options for a JDBM partition</caption>
-          <thead>
-            <tr>
-              <td>Property</td>
-              <td>Default value</td>
-              <td>Description</td>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>id</td>
-              <td></td>
-              <td>(required) uniquely identifies the partition</td>
-            </tr>
-            <tr>
-              <td>suffix</td>
-              <td></td>
-              <td>(required) an LDAP DN ("dc=example, dc=com", for instance)</td>
-            </tr>
-            <tr>
-              <td>cacheSize</td>
-              <td>-1</td>
-              <td>cache size expressed as a number of entries</td>
-            </tr>
-            <tr>
-              <td>optimizerEnabled</td>
-              <td>true</td>
-              <td></td>
-            </tr>
-            <tr>
-              <td>syncOnWrite</td>
-              <td>true</td>
-              <td>sync disks on every write operation</td>
-            </tr>
-          </tbody>
+          <title>More configuration options for a JDBM partition</title>
+          <tgroup
+            cols="3">
+            <thead>
+              <row>
+                <entry>Property</entry>
+                <entry>Default value</entry>
+                <entry>Description</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>id</entry>
+                <entry></entry>
+                <entry>(required) uniquely identifies the partition</entry>
+              </row>
+              <row>
+                <entry>suffix</entry>
+                <entry></entry>
+                <entry>(required) an LDAP DN ("dc=example, dc=com", for instance)</entry>
+              </row>
+              <row>
+                <entry>cacheSize</entry>
+                <entry>-1</entry>
+                <entry>cache size expressed as a number of entries</entry>
+              </row>
+              <row>
+                <entry>optimizerEnabled</entry>
+                <entry>true</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry>syncOnWrite</entry>
+                <entry>true</entry>
+                <entry>sync disks on every write operation</entry>
+              </row>
+            </tbody>
+          </tgroup>
         </table>
       </section>
     </section>
@@ -1214,11 +1217,11 @@ directoryService.getPartitionNexus().add
         <title>ApacheDS and logging</title>
         <para>
           ApacheDS 1.5 uses
-          <link
-            xlink:href="http://www.slf4j.org/">SLF4J</link>
+          <ulink
+            url="http://www.slf4j.org/">SLF4J</ulink>
           as its logging solution. This is a simple facade for various logging APIs. The default for ApacheDS 1.5 is
-          <link
-            xlink:href="http://logging.apache.org/log4j/">log4j</link>
+          <ulink
+            url="http://logging.apache.org/log4j/">log4j</ulink>
           .
         </para>
       </section>
@@ -1229,8 +1232,8 @@ directoryService.getPartitionNexus().add
           By default, ApacheDS writes log files in the directory
           <emphasis>&lt;APACHDS_HOME&gt;/var/log/</emphasis>
           . Besides stdout, a
-          <link
-            xlink:href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/RollingFileAppender.html">RollingFileAppender</link>
+          <ulink
+            url="http://logging.apache.org/log4j/docs/api/org/apache/log4j/RollingFileAppender.html">RollingFileAppender</ulink>
           is used to collect warnings and errors. It
           backups the log files when they reach a certain size.
         </para>
@@ -1272,26 +1275,335 @@ log4j.logger.org.apache.directory.shared
           </programlisting>
         </example>
         <para>In this file "R" is configured like this:</para>
+        <table
+          id="Configuration RollingFileAppender table">
+          <title>Configuration RollingFileAppender</title>
+          <tgroup
+            cols="3">
+            <thead>
+              <row>
+                <entry>Property name</entry>
+                <entry>Value in file above</entry>
+                <entry>Meaning</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry>File</entry>
+                <entry>apacheds-rolling.log</entry>
+                <entry>
+                  path to the output log file, in our case relative to
+                  <emphasis>var/log</emphasis>
+                </entry>
+              </row>
+              <row>
+                <entry>MaxFileSize</entry>
+                <entry>1024KB</entry>
+                <entry>maximum size that the output file is allowed to reach before being rolled over to backup files
+                </entry>
+              </row>
+              <row>
+                <entry>MaxBackupIndex</entry>
+                <entry>5</entry>
+                <entry>number of backup files kept</entry>
+              </row>
+              <row>
+                <entry>ConversionPattern</entry>
+                <entry>[%d{HH:mm:ss}] %p [%c] - %m%n</entry>
+                <entry>format string for logging events</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+        <para>If the default logging does not meet your requirements, you can easily adjust the configuration to your
+          needs.</para>
       </section>
       <section
         id="Adjusting logging to your needs">
         <title>Adjusting logging to your needs</title>
+        <section
+          id="Log file location (where the log files are placed)">
+          <title>Log file location (where the log files are placed)</title>
+          <para>
+            By default the log files are placed at
+            <emphasis>&lt;APACHDS_HOME&gt;/var/log/</emphasis>
+            , but that can be changed.
+          </para>
+          <section>
+            <subtitle>Linux/MacOS/Solaris</subtitle>
+            <para>
+              On this systems the location of the log files is configured via an entry in
+              <emphasis
+                role="bold">/bin/server.init</emphasis>
+              . Look for the following lines and change it to your preferences:
+            </para>
+            <example>
+              <title>Log file location Linux/MacOS/Solaris</title>
+              <programlisting><![CDATA[
+$DAEMON_HOME/apacheds \
+...
+-outfile $SERVER_HOME/var/log/apacheds-stdout.log \
+-errfile $SERVER_HOME/var/log/apacheds-stderr.log \
+...    
+$APACHEDS_HOME start
+              ]]></programlisting>
+            </example>
+          </section>
+          <section>
+            <subtitle>Windows</subtitle>
+            <para>
+              On Windows you can use the configuration wizard for the service as shown in the screenshot above. To
+              adjust the log path you have to adjust the values of
+              <emphasis
+                role="bold">Redirect Stdout</emphasis>
+              and
+              <emphasis
+                role="bold">Redirect Stderror</emphasis>
+              .
+            </para>
+          </section>
+        </section>
+        <section
+          id="Log level (how detailed the logs are)">
+          <title>Log level (how detailed the logs are)</title>
+          <para>The following log levels from log4j are used for messages within ApacheDS:</para>
+          <table
+            id="Log level">
+            <title>Log level</title>
+            <tgroup
+              cols="2">
+              <thead>
+                <row>
+                  <entry>Level</entry>
+                  <entry>Description from log4j documentation</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>DEBUG</entry>
+                  <entry>designates fine-grained informational events that are most useful to debug an application
+                  </entry>
+                </row>
+                <row>
+                  <entry>INFO</entry>
+                  <entry>designates informational messages that highlight the progress of the application at
+                    coarse-grained
+                    level</entry>
+                </row>
+                <row>
+                  <entry>WARN</entry>
+                  <entry>designates potentially harmful situations</entry>
+                </row>
+                <row>
+                  <entry>ERROR</entry>
+                  <entry>designates error events that might still allow the application to continue running</entry>
+                </row>
+                <row>
+                  <entry>FATAL</entry>
+                  <entry>designates very severe error events that will presumably lead the application to abort </entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+          <para>
+            The default (global) log level in the configuration is
+            <emphasis>WARN</emphasis>
+            . All messages of level WARN and more severe (ERROR, FATAL) are written to the rolling log file. The easiest
+            way to get finer log messages is to change it like this
+          </para>
+          <programlisting><![CDATA[
+log4j.rootCategory=DEBUG, stdout, R
+...
+          ]]></programlisting>
+          <para>detailed log messages took much file space and time and therefore should only be enabled globally in
+            order to analyze problems.</para>
+          <para>is possible to configure the logging more fine grained by using categories. Within the default
+            configuration there are some examples:</para>
+          <programlisting><![CDATA[
+...
+# with these we'll not get innundated when switching to DEBUG
+log4j.logger.org.apache.directory.shared.ldap.name=WARN
+log4j.logger.org.springframework=WARN
+log4j.logger.org.apache.directory.shared.codec=WARN
+log4j.logger.org.apache.directory.shared.asn1=WARN
+          ]]></programlisting>
+          <para>
+            If the global level is switched to DEBUG, these definitions override the setting with WARN for certain areas
+            and therefore keep the file a little bit smaller. Learn more about the concept of categories in the
+            <ulink
+              url="http://logging.apache.org/log4j/docs/manual.html">Short introduction to log4j</ulink>
+            .
+          </para>
+        </section>
+        <section
+          id="Format for log messages">
+          <title>Format for log messages</title>
+          <para>
+            The format of each line within a log file is controlled by a pattern. For the
+            <emphasis>RollingFileAppender</emphasis>
+            in the default configuration it looks like this
+          </para>
+          <programlisting><![CDATA[
+...
+log4j.appender.R.layout=org.apache.log4j.PatternLayout
+log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
+...
+        ]]></programlisting>
+          <para>Some examples lines within the log file, formatted with the pattern "[%d{HH:mm:ss}] %p [%c] - %m%n" are:
+          </para>
+          <programlisting><![CDATA[
+...
+[12:29:03] WARN [org.apache.directory.server.core.DefaultDirectoryService]
+    - You didn't change the admin password of directory service instance 'default'.
+    Please update the admin password as soon as possible to prevent a possible security breach.
+...
+[12:29:05] INFO [org.apache.directory.server.jndi.ServerContextFactory]
+    - Successful bind of an LDAP Service (636) is complete.
+[12:29:05] INFO [org.apache.directory.server.Service] - server: started in 6750 milliseconds
+...
+        ]]></programlisting>
+          <para>The pattern uses the following conversion characters:</para>
+          <table
+            id="Log file output patterns">
+            <title>Log file output patterns</title>
+            <tgroup
+              cols="2">
+              <thead>
+                <row>
+                  <entry>Character</entry>
+                  <entry>Outputs</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>%d</entry>
+                  <entry>date of the logging event in the given format. like "12:29:05" for %d{HH:mm:ss}</entry>
+                </row>
+                <row>
+                  <entry>%p</entry>
+                  <entry>priority (level) of the logging event, like "INFO" or "WARN"</entry>
+                </row>
+                <row>
+                  <entry>%c</entry>
+                  <entry>category of the logging event, like "org.apache.directory.server.Service"</entry>
+                </row>
+                <row>
+                  <entry>%m</entry>
+                  <entry>application supplied message associated with the logging event</entry>
+                </row>
+                <row>
+                  <entry>%n</entry>
+                  <entry>platform dependent line separator</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </table>
+          <para>
+            The
+            <ulink
+              url="http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html">javadoc of log4j</ulink>
+            contains a table with all valid %-characters and their meaning.
+          </para>
+          <para>
+            Simple adjust the pattern in the
+            <emphasis>log4j.properties</emphasis>
+            file to get the log format of your choice, for instance
+          </para>
+          <programlisting><![CDATA[
+log4j.appender.R.layout.ConversionPattern=[%d{dd.MM.yyyy HH:mm:ss}] %p: %c{1}.%M() - %m%n
+          ]]></programlisting>
+          <para>leads to messages of this form:</para>
+          <programlisting><![CDATA[
+...
+[29.12.2006 13:50:44] INFO: ServerContextFactory.startLDAP0() 
+    - Successful bind of an LDAP Service (636) is complete.
+[29.12.2006 13:50:44] INFO: Service.init() - server: started in 3016 milliseconds
+...
+          ]]></programlisting>
+          <warning>
+            <mediaobject>
+              <imageobject>
+                <imagedata
+                  fileref="images/forbidden.gif" />
+              </imageobject>
+            </mediaobject>
+            <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>
+          </warning>
+        </section>
+        <section
+          id="Advanced log4j configuration">
+          <title>Advanced log4j configuration</title>
+          <para>
+            You can take advantage of other features of log4j as well, such as other appenders like the daily
+            rolling
+            file appender. And you can configure logging to make it easier for you to view the messages with
+            tools like
+            Log Factor 5 or
+            <ulink
+              url="http://logging.apache.org/log4j/docs/chainsaw.html">Chainsaw</ulink>
+            .
+          </para>
+          <para>
+            Learn more about log4j and related tools at its
+            <ulink
+              url="http://logging.apache.org/log4j/docs/index.html">homepage</ulink>
+            .
+          </para>
+        </section>
       </section>
       <section
         id="Example configurations">
         <title>Example configurations</title>
+        <para>The following example could be used to log all incoming search, add, delete, modify and moddn requests:
+        </para>
+        <example
+          id="Example log4j configuration">
+          <title>Example log4j.properties configuration</title>
+          <programlisting><![CDATA[
+log4j.logger.org.apache.directory.server.ldap.handlers.SearchHandler=DEBUG
+log4j.logger.org.apache.directory.server.ldap.handlers.AddHandler=DEBUG
+log4j.logger.org.apache.directory.server.ldap.handlers.DeleteHandler=DEBUG
+log4j.logger.org.apache.directory.server.ldap.handlers.ModifyHandler=DEBUG
+log4j.logger.org.apache.directory.server.ldap.handlers.ModifyDnHandler=DEBUG
+        ]]></programlisting>
+        </example>
       </section>
       <section
         id="Log settings of the Windows daemon process">
         <title>Log settings of the Windows daemon process</title>
+        <para>After installation on Windows, you have the option to configure the ApacheDS Windows Service (you can do
+          this later as well). If you do so, one option pane is dedicated to logging:</para>
+        <figure
+          id="W32 Service Properties">
+          <title>W32 Service Properties</title>
+          <mediaobject>
+            <imageobject>
+              <imagedata
+                fileref="images/w32_service_properties.png" />
+            </imageobject>
+          </mediaobject>
+        </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>
       </section>
       <section
         id="Resources logging">
         <title>Resources</title>
+        <itemizedlist>
+          <listitem>
+            <para>
+              <ulink
+                url="http://logging.apache.org/log4j/docs/manual.html">Short introduction to log4j</ulink>
+            </para>
+          </listitem>
+        </itemizedlist>
       </section>
     </section>
 
-    <section>
+    <section
+      id="Enable and disable anonymous access">
       <title>Enable and disable anonymous access</title>
       <para>This section briefly describes how to enable and disable anonymous access.</para>
       <para>Anonymous access to the server is enabled by default. This includes read and write access! </para>
@@ -1315,13 +1627,204 @@ log4j.logger.org.apache.directory.shared
         their name (distinguished name) and password in order to bind to the directory service.</para>
       <para>
         Learn more about authentication option in the corresponding section of this guide
-        <xref>here</xref>
+        <xref
+          linkend="Authentication options">here</xref>
         .
       </para>
     </section>
   </section>
 
-  <section>
+  <section
+    id="About the sample configurations and sample directory data">
     <title>About the sample configurations and sample directory data</title>
+    <para>This section describes basic parameters used throughout the examples in this guide. It also introduces the
+      sample directory "Sailors of the seven seas", and other requisites you need.</para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <xref
+            linkend="Basic server parameters">Basic server parameters</xref>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="LDAP Clients">LDAP Clients</xref>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="The sample data (Sailors of the seven seas)">The sample data (Sailors of the seven seas)</xref>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Resources RFC 2849">Resources</xref>
+        </para>
+      </listitem>
+    </itemizedlist>
+    <section
+      id="Basic server parameters">
+      <title>Basic server parameters</title>
+      <para>In the following sections we assume that you will install, configure and run Apache Directory Server on a
+        host with the following host name using the parameters given in the following table:</para>
+      <table
+        id="Basic server parameters table">
+        <title>Basic server parameters</title>
+        <tgroup
+          cols="2">
+          <thead>
+            <row>
+              <entry>Parameter name</entry>
+              <entry>Parameter value</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>Hostname</entry>
+              <entry>zanzibar</entry>
+            </row>
+            <row>
+              <entry>Port</entry>
+              <entry>10389</entry>
+            </row>
+            <row>
+              <entry>Suffix ("Base DN")</entry>
+              <entry>o=sevenSeas</entry>
+            </row>
+            <row>
+              <entry>Admin user DN</entry>
+              <entry>uid=admin,ou=system</entry>
+            </row>
+            <row>
+              <entry>Admin user password</entry>
+              <entry>secret</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+      <para>
+        Before you start playing with the data make sure that you have added a partition with the suffix o=sevenSeas to
+        the server. How to do this is described
+        <xref
+          linkend="Basic configuration tasks">here</xref>
+        .
+      </para>
+      <para>In order to increase recognition, all examples of the Basic User's Guide use these values. Adjust them to
+        your needs (especially the password).</para>
+    </section>
+    <section
+      id="LDAP Clients">
+      <title>LDAP Clients</title>
+      <para>LDAP is a client/server protocol. Hence you need an LDAP client to connect remotely to the Apache Directory
+        Server (or at least the directory part of it, to be precise). There are different options here. Because the
+        protocol is standardized, you may use every LDAP compliant client. This is comparable to HTTP, where you can use
+        each web browser to communicate with virtually each web server, and totally different to relational databases.
+        The latter have a (more or less) standardized query language (SQL), but vendors tend to use individual network
+        access protocols. In practice, the LDAP situation is even better than HTTP, because there were no LDAP browser
+        wars ...</para>
+      <para>Many software components may act as an LDAP client. Normally they use LDAP libraries to connect. In the
+        following sections you meet LDAP clients with GUI and LDAP command line tools. Some Java programming examples
+        which takes advantage of JNDI are provided as well.</para>
+      <para>In other sections you will learn how E-Mail clients like Mozilla Thunderbird and application servers like
+        Apache Tomcat connect to Apache Directory server, either to use the data stored in the directory (e.g. mail
+        addresses) or to perform authentication and authorization.</para>
+      <para>
+        Recapitulating the Basic User's Guide describes connecting to the server with tools provided by ApacheDS as well
+        as third party products. In all cases the examples will use the connection data depicted above (
+        <emphasis>ldap://zanzibar:10389/o=sevenSeas</emphasis>
+        )
+      </para>
+    </section>
+    <section
+      id="The sample data (Sailors of the seven seas)">
+      <title>The sample data (Sailors of the seven seas)"</title>
+      <para>
+        The file
+        <ulink
+          url="data/apache_ds_tutorial.ldif">apache_ds_tutorial.ldif</ulink>
+        contains some sample data, which is used in the following sections. It is a
+        text file in the so called
+        <emphasis
+          role="bold">LDIF</emphasis>
+        format. LDIF stands for LDAP Data Interchange Format. It is widely adopted in
+        the LDAP world and standardized in
+        <ulink
+          url="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</ulink>
+        . Therefore you are able to import our sample data into other
+        directory solutions as well, not only into Apache
+        Directory Server.
+      </para>
+      <para>The sample directory tree contains entries for persons and groups. These are structured in sub trees
+        (ou=people and ou=groups), see image below. The person entries describe sailors (historic and fictional), the
+        group entries bundle them. An example for a group is the ship crew of HMS Bounty.</para>
+      <figure
+        id="Sample LDAP tree structure">
+        <title>Sample LDAP tree structure</title>
+        <mediaobject>
+          <imageobject>
+            <imagedata
+              fileref="images/sample_structure.gif" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+      <para>This snippet of the file represents a single entry, just to give you an impression of how LDIF files look
+        like.</para>
+      <programlisting><![CDATA[
+...
+# Entry for Fletcher Christian
+#
+dn: cn=Fletcher Christian,ou=people,o=sevenSeas
+cn: Fletcher Christian
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+sn: Christian
+givenName: Fletcher
+description: Lieutenant Fletcher Christian
+manager: cn=William Bligh,ou=people,o=sevenSeas
+...
+        ]]></programlisting>
+      <para>There are different ways to import the data. Generally perform the following steps:</para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            Download and install the server, described im
+            <xref
+              linkend="Installing and starting the server">Installing and starting the server</xref>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Configure a partition for the sample date, described in
+            <xref
+              linkend="Basic configuration tasks">Basic configuration tasks</xref>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Import the data, for instance using
+            <ulink
+              url="http://directory.apache.org/studio/">Apache Directory Studio</ulink>
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
+    <section
+      id="Resources RFC 2849">
+      <title>Resources</title>
+      <itemizedlist>
+        <listitem>
+          <para>
+            <ulink
+              url="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</ulink>
+            The LDAP Data Interchange Format (LDIF) – Technical Specification
+          </para>
+        </listitem>
+      </itemizedlist>
+    </section>
   </section>
 </chapter>

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=984795&r1=984794&r2=984795&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 14:10:56 2010
@@ -7,16 +7,83 @@
   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>
-  <section>
+  <title>Basic Security</title>
+  <section
+    id="Authentication options">
     <title>Authentication options</title>
+    <para>This section describes the authentication options of ApacheDS 1.5. Anonymous and simple binds are supported,
+      as well as SASL mechanisms. Configuring and using the first two of them is described below with the help of
+      examples.</para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <xref
+            linkend="What is authentication?">What is authentication?</xref>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Simple binds">Simple binds</xref>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Passwords stored one-way encrypted">Passwords stored one-way encrypted</xref>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Anonymous binds">Anonymous binds</xref>
+        </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>
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <xref
+            linkend="Resources encryption">Resources</xref>
+        </para>
+      </listitem>
+    </itemizedlist>
+    <section
+      id="What is authentication?">
+      <title>What is authentication?</title>
+    </section>
+    <section
+      id="Simple binds">
+      <title>Simple binds</title>
+    </section>
+    <section
+      id="Passwords stored one-way encrypted">
+      <title>Passwords stored one-way encrypted</title>
+    </section>
+    <section
+      id="Anonymous binds">
+      <title>Anonymous binds</title>
+    </section>
+    <section
+      id="How to authenticate a user by uid and password?">
+      <title>How to authenticate a user by uid and password?</title>
+    </section>
+    <section
+      id="Resources encryption">
+      <title>Resources</title>
+    </section>
   </section>
-  <section>
+  <section
+    id="Basic authorization">
     <title>Basic authorization</title>
   </section>
-  <section>
+  <section
+    id="How to enable SSL">
     <title>How to enable SSL</title>
   </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=984795&r1=984794&r2=984795&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 14:10:56 2010
@@ -9,5 +9,5 @@
   xmlns:ns3="http://www.w3.org/1999/xhtml"
   xmlns:db="http://docbook.org/ns/docbook"
   xml:lang="en">
-  <title>Basic Security</title>
+  <title>Handling of data within your directory </title>
 </chapter>

Added: directory/sandbox/felixk/apacheds-docs/src/main/resources/data/apache_ds_tutorial.ldif
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/main/resources/data/apache_ds_tutorial.ldif?rev=984795&view=auto
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/main/resources/data/apache_ds_tutorial.ldif (added)
+++ directory/sandbox/felixk/apacheds-docs/src/main/resources/data/apache_ds_tutorial.ldif Thu Aug 12 14:10:56 2010
@@ -0,0 +1,219 @@
+# Sample LDIF data for the ApacheDS v1.0 Basic User's Guide
+#
+# Some sailors and their ships
+# userpassword for all persons is "pass"
+#
+version: 1
+
+dn: ou=people,o=sevenSeas
+objectclass: organizationalUnit
+objectclass: top
+description: Contains entries which describe persons (seamen)
+ou: people
+
+dn: ou=groups,o=sevenSeas
+objectclass: organizationalUnit
+objectclass: top
+description: Contains entries which describe groups (crews, for instance)
+ou: groups
+
+dn: ou=crews,ou=groups,o=sevenSeas
+objectclass: organizationalUnit
+objectclass: top
+description: Contains entries which describe ship crews
+ou: crews
+
+dn: ou=ranks,ou=groups,o=sevenSeas
+objectclass: organizationalUnit
+objectclass: top
+description: Contains entries which describe naval ranks (e.g. captain)
+ou: ranks
+
+# HMS Lydia Crew
+# --------------
+
+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=
+
+dn: cn=William Bush,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: William Bush
+description: Lt. William Bush
+givenname: William
+manager: cn=Horatio Hornblower,ou=people,o=sevenSeas
+sn: Bush
+uid: wbush
+mail: wbush@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=Thomas Quist,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Thomas Quist
+description: Seaman Quist
+givenname: Thomas
+manager: cn=Horatio Hornblower,ou=people,o=sevenSeas
+sn: Quist
+uid: tquist
+mail: tquist@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=Moultrie Crystal,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Moultrie Crystal
+description: Lt. Crystal
+givenname: Moultrie
+manager: cn=Horatio Hornblower,ou=people,o=sevenSeas
+sn: Crystal
+uid: mchrysta
+mail: mchrysta@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas
+objectclass: groupOfUniqueNames
+objectclass: top
+cn: HMS Lydia
+uniquemember: cn=Horatio Hornblower,ou=people,o=sevenSeas
+uniquemember: cn=William Bush,ou=people,o=sevenSeas
+uniquemember: cn=Thomas Quist,ou=people,o=sevenSeas
+uniquemember: cn=Moultrie Crystal,ou=people,o=sevenSeas
+
+# HMS Victory Crew
+# ----------------
+
+dn: cn=Horatio Nelson,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Horatio Nelson
+description: Lord Horatio Nelson
+givenname: Horatio
+sn: Nelson
+uid: hnelson
+mail: hnelson@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=Thomas Masterman Hardy,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Thomas Masterman Hardy
+description: Sir Thomas Masterman Hardy
+givenname: Thomas
+manager: cn=Horatio Nelson,ou=people,o=sevenSeas
+sn: Hardy
+uid: thardy
+mail: thardy@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=Cornelius Buckley,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Cornelius Buckley
+description: LM Cornelius Buckley
+givenname: Cornelius
+manager: cn=Horatio Nelson,ou=people,o=sevenSeas
+sn: Buckley
+uid: cbuckley
+mail: cbuckley@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=HMS Victory,ou=crews,ou=groups,o=sevenSeas
+objectclass: groupOfUniqueNames
+objectclass: top
+cn: HMS Victory
+uniquemember: cn=Horatio Nelson,ou=people,o=sevenSeas
+uniquemember: cn=Thomas Masterman Hardy,ou=people,o=sevenSeas
+uniquemember: cn=Cornelius Buckley,ou=people,o=sevenSeas
+
+# HMS Bounty Crew
+# ---------------
+
+dn: cn=William Bligh,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: William Bligh
+description: Captain William Bligh
+givenname: William
+sn: Bligh
+uid: wbligh
+mail: wbligh@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=Fletcher Christian,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: Fletcher Christian
+description: Lieutenant Fletcher Christian
+givenname: Fletcher
+manager: cn=William Bligh,ou=people,o=sevenSeas
+sn: Christian
+uid: fchristi
+mail: fchristi@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=John Fryer,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: John Fryer
+description: Master John Fryer
+givenname: John
+manager: cn=William Bligh,ou=people,o=sevenSeas
+sn: Fryer
+uid: jfryer
+mail: jfryer@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+dn: cn=John Hallett,ou=people,o=sevenSeas
+objectclass: person
+objectclass: organizationalPerson
+objectclass: inetOrgPerson
+objectclass: top
+cn: John Hallett
+description: Midshipman John Hallett
+givenname: John
+manager: cn=William Bligh,ou=people,o=sevenSeas
+sn: Hallett
+uid: jhallett
+mail: jhallett@royalnavy.mod.uk
+userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
+
+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
+uniquemember: cn=John Hallett,ou=people,o=sevenSeas
+
+
+



Mime
View raw message