You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by fe...@apache.org on 2010/08/12 16:10:56 UTC
svn commit: r984795 - in /directory/sandbox/felixk/apacheds-docs: ./
src/docbkx/ src/main/resources/data/
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><APACHDS_HOME>/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><APACHDS_HOME>/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
+
+
+