You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by sz...@apache.org on 2010/08/29 22:23:53 UTC
svn commit: r990643 - in
/directory/apacheds-manuals/trunk/src/basic-user-guide: book.xml
chapter-how-to-begin.xml chapter-how-to-begin/chapter-how-to-begin.xml
Author: szoerner
Date: Sun Aug 29 20:23:53 2010
New Revision: 990643
URL: http://svn.apache.org/viewvc?rev=990643&view=rev
Log:
moved one chapter in a separate folder. Will continue to do this with the rest
Added:
directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml
Removed:
directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin.xml
Modified:
directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml
Modified: directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml
URL: http://svn.apache.org/viewvc/directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml?rev=990643&r1=990642&r2=990643&view=diff
==============================================================================
--- directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml (original)
+++ directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml Sun Aug 29 20:23:53 2010
@@ -62,16 +62,16 @@ under the License.</literallayout>
the ApacheDS 1.0 Basic User's Guide, which is currently more complete.
</para>
</preface>
- <xi:include
- href="chapter-basic-user-guide.xml" />
- <xi:include
- href="chapter-how-to-begin.xml" />
- <xi:include
- href="chapter-handling-of-data-within-your-directory.xml" />
- <xi:include
- href="chapter-basic-security.xml" />
- <xi:include
- href="chapter-integrating-apacheds-with-other-programs.xml" />
+
+ <xi:include href="chapter-basic-user-guide.xml" />
+
+ <xi:include href="chapter-how-to-begin/chapter-how-to-begin.xml" />
+
+ <xi:include href="chapter-handling-of-data-within-your-directory.xml" />
+
+ <xi:include href="chapter-basic-security.xml" />
+
+ <xi:include href="chapter-integrating-apacheds-with-other-programs.xml" />
<index> ... </index>
Added: directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml
URL: http://svn.apache.org/viewvc/directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml?rev=990643&view=auto
==============================================================================
--- directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml (added)
+++ directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml Sun Aug 29 20:23:53 2010
@@ -0,0 +1,1830 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under
+ the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may
+ obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to
+ in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+ ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under
+ the License. -->
+<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"
+ xmlns:ns3="http://www.w3.org/1999/xhtml"
+ xml:lang="en">
+ <title>How to begin</title>
+
+ <section
+ id="What Apache Directory Server is">
+ <title>What Apache Directory Server is</title>
+ <para>
+ This section describes what Apache Directory Server (abbreviated ApacheDS) is, and where it comes from.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="System vision" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Origin and Motives" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Resources" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section
+ id="System vision">
+ <title>
+ System vision</title>
+ <para>
+ ApacheDS 1.5 is an embeddable, extendable, standards compliant, modern LDAP server written entirely in Java,
+ and available
+ under the Apache Software License. Other network protocols like Kerberos and NTP are supported as
+ well (and even
+ more may be added), but basically (and especially for this introduction guide) ApacheDS is an LDAP
+ server.</para>
+ <para>
+ <emphasis>Embeddable</emphasis>
+ means that it is possible to configure, start and stop ApacheDS from other Java components,
+ especially
+ application servers, and the server runs within the same VM. The solution has already been
+ successfully embedded
+ in Apache Geronimo, JBoss, and others. The fact that the server is embeddable is quite
+ interesting, nevertheless
+ you also have the deployment option to run the server standalone, for instance as a
+ Windows service. Perhaps you
+ know this situation from other LDAP servers â open source (like OpenLDAP) as well
+ as commercial ones (like Sun
+ Java System Directory Server). This guide is dedicated to people that are new to
+ ApacheDS. The guide concentrates
+ on installing, configuring and running ApacheDS in a standalone configuration.
+ </para>
+ <para>
+ <emphasis>Extendable</emphasis>
+ means that the modern architecture of the solution provides many extension points. Write your own
+ partitions to
+ store directory data, interceptors to add functionality, etc. by implementing certain interfaces
+ and plugging
+ them in using Spring.
+ </para>
+ <para>
+ <emphasis>Standard</emphasis>
+ compliant means that ApacheDS 1.5 adheres to all RFCs relevant to
+ LDAPv3. Please note that version 1.0 of the
+ server has been successfully certified by the Open Group in September
+ 2006 ("LDAP certified"). Thus LDAP clients
+ may rightly expect that ApacheDS behaves like they expect.
+ </para>
+ <para>
+ <emphasis>Modern</emphasis>
+ means
+ that ApacheDS aims modernize the LDAP territory, as well as it favors standards compliance. New rich
+ integration
+ tier constructs like LDAP Stored Procedures and Triggers are being built on top of existing
+ standards.
+ </para>
+ <para>
+ <emphasis>Entirely</emphasis>
+ written in Java means that the software compiles and runs on a huge number of hardware and software platforms.
+ Native installers are available for Windows, MacOS and Solaris (both SPARC and intel platform), but in fact the
+ set of possible targets is by far more extensive.
+ </para>
+ <section
+ id="Architectural overview">
+ <title>Architectural overview</title>
+ <figure
+ id="50k FT Architecture">
+ <title>50k FT Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/50k-ft-architecture.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ <section
+ id="Origin and Motives">
+ <title>Origin and Motives</title>
+ <para>
+ Through his experiences with enterprise LDAP directories, Alex Karasulu, realized there is a great need
+ for
+ rich integration tier constructs like LDAP Stored Procedures, Triggers, and Views. In 2001 he set out to
+ alter
+ the OpenLDAP server to offer support for these useful facilities which are present in relational databases
+ but
+ missing in the LDAP world. Alex's attempts failed due to the complexity of the software which was brittle,
+ and
+ difficult to manage. As C code ported to several platforms, the OpenLDAP code base, had several #IFDEF
+ conditional pre-compiler directives that made it difficult to change the code. At this point Alex thought about
+ implementing a new LDAP server in pure Java. Thanks to NIO this was finally possible using the 1.4 JDK.
+ </para>
+ <para>
+ In October 2002 Alex Karasulu founded and registered the
+ <link
+ xlink:href="http://sourceforge.net/projects/ldapd">LDAPd</link>
+ 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>
+ in October 2003. One year later in October of
+ 2004,
+ the Apache Directory Top Level Project (TLP) was formed after
+ a successful incubation with the now called
+ Apache
+ Directory Server as its flagship product. After 4 years of
+ development, in October 2006, Apache Directory
+ Server
+ 1.0 was released as an Open Group certified LDAPv3 protocol
+ server. The certification has been renewed in
+ September 2007.
+ </para>
+ <para>Having a standards compliant and modern LDAP server, Apache Directory Team is now working on Identity and
+ Access Management solutions leveraging the directory technology.
+ </para>
+ </section>
+ <section
+ id="Resources">
+ <title>Resources</title>
+ <itemizedlist>
+ <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>
+ 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>
+ , Paper for 1st International Conference on LDAP, September 2007.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section
+ id="Some Background. Directories, directory services and LDAP">
+ <title>Some Background. Directories, directory services and LDAP</title>
+ <para>This section provides a brief overview about directories, directory services and LDAP. Furthermore you find
+ links to different resources (books, online resources, ...), which may act as introduction to the topic. If you
+ are
+ already an LDAP expert, you'll probably skip this section.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="directoriesAndDirectoryServices" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="ldapTheLightWeightDirectoryAccessProtocol" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="ldapResources" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section
+ id="directoriesAndDirectoryServices">
+ <title>Directories and directory services</title>
+ <para>Generally speaking, a directory is a collection or list of data. Real world examples are telephone books
+ (public or within organizations), church/land registers and listings of works (e.g. the Koechel-index, which
+ lists
+ all compositions of Mozart). All these examples have the purpose to preserve information and to make it
+ available
+ on demand to whom it may concern.</para>
+ <para>
+ Within information technology the term
+ <emphasis
+ role="bold">directory</emphasis>
+ is used for a special kind of data storage. It allows the
+ structured storage and efficient retrieval of objects
+ which are often derived from the real world (e.g. persons,
+ IT equipment). Characteristic:
+ <itemizedlist>
+ <listitem>
+ <para>
+ all data is stored in so called
+ <emphasis
+ role="bold">entries</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>the set of entries within a directory forms a tree (hierarchical database)</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ A
+ <emphasis
+ role="bold">directory service</emphasis>
+ is a solution which offers users access to the information stored in the directory. A
+ directory assistance (call
+ center agent) is a good real world example for such a service. Within information
+ technologies, such services are
+ normally provided by software components. Directory services provide access to
+ the content of a directory via a
+ well-defined interface. If a network is used, an appropriate protocol has to be
+ defined. LDAP (see below) is such
+ a
+ protocol.
+ </para>
+ <para>
+ The real world examples mentioned above may be stored in such a directory, although other types of storage
+ systems
+ can be more appropriate (this depends on circumstance/requirements). At first sight directories compete
+ thereby as
+ data storage with the established relational data bases. However in the most large enterprises and
+ organizations
+ 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>
+ .
+ </para>
+ </section>
+ <section
+ id="ldapTheLightWeightDirectoryAccessProtocol">
+ <title>LDAP â the Lightweight Directory Access Protocol</title>
+ <section
+ id="What is it? Some history">
+ <title>What is it? Some history</title>
+ <para>
+ The comprehensive standard
+ <emphasis
+ role="bold">X.500</emphasis>
+ , finalized in 1988, builds the foundation for many of today's directory
+ solutions. Within this standard, the
+ client accesses the server via the Directory Access Protocol (
+ <emphasis
+ role="bold">DAP</emphasis>
+ ), which
+ is OSI protocol stack based. With the Internet boom in the nineties, the accessibility of directories
+ via
+ TCP/IP
+ became more and more important. Hence a TCP/IP-based access method, which in functionality was a
+ subset
+ of DAP,
+ was standardized in 1993: the
+ <emphasis
+ role="bold">Lightweight Directory Access Protocol (LDAP)</emphasis>
+ . First LDAP implementations
+ were
+ gateway solutions, they mediated between LDAP clients and X.500 servers. In
+ 1995
+ the University of
+ Michigan
+ presented the first native LDAP server; in the meantime the work is continued by
+ the
+ OpenLDAP project.
+ 1996
+ Netscape followed with the first commercial LDAP server (Netscape Directory Server,
+ foundation of several
+ later
+ LDAP servers). Other examples (among many others) include Microsoft Active Directory
+ and Novell
+ eDirectory. The
+ figure below shows the development of directory protocols from X.500/DAP to LDAP.
+ </para>
+ <figure
+ id="From X500 to LDAP">
+ <title>From X500 to LDAP</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/fromX500toLDAP.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section
+ id="Information model primer">
+ <title>Information model primer</title>
+ <para>
+ Within the information model of LDAP, data is stored in entries, which build up a hierarchical, tree like
+ structure. Each entry has a unique name (
+ <emphasis
+ role="bold">DN, Distinguished Name</emphasis>
+ ), which depicts its position within the tree.
+ An
+ entry consists of key/value pairs, the
+ <emphasis
+ role="bold">attributes</emphasis>
+ . Some attributes may occur more than once within an entry
+ (single or multi valued, e.g. a person can have more
+ than one telephone number). So called
+ <emphasis
+ role="bold">object classes</emphasis>
+ define, which attributes an entry may have, and which of them are required. The classes build up a hierarchy
+ with
+ <emphasis
+ role="bold">top</emphasis>
+ as root; there is a parallelism to the object oriented world. top forces only the attribute
+ objectclass, which
+ assigns an entry its object classes. A
+ <emphasis
+ role="bold">schema</emphasis>
+ consists object classes and attribute types,
+ and therefore defines, what kind of entries can be stored within
+ the
+ directory. Directory servers ship a
+ schema
+ out-of-the-box, often with elements standardized by RFCs. In
+ addition,
+ most directory solutions allow
+ you to
+ define custom object classes and attributes. But in practice,
+ the
+ pre-defined
+ elements are used.
+ Sometimes
+ they
+ get extended according to special requirements.
+ </para>
+ </section>
+ <section
+ id="Common applications of LDAP based directories">
+ <title>Common applications of LDAP based directories</title>
+ <para>LDAP operations include entry creation, modification, deletion and search. As a general rule, LDAP
+ directories are optimized for read and search operations, at the cost of write performance. Data, which will
+ be
+ modified often, therefore better suits in a relational database, which offers better support for
+ transactions and
+ referential integrity as well. Directories are rather used if comparatively stable data has
+ to
+ be provided
+ centrally. </para>
+ <para>Common examples are network resources (printers, services) and user data (including credentials and rights
+ for the resources). As a notable feature, many directory products offer replicas, which permit better access
+ times and higher availability especially in geographically dispersed organizations. Not for nothing, the most
+ common LDAP application is the enterprise phone book. That even Microsoft Outlook may be an LDAP client in
+ this
+ case - most average users probably don't know.</para>
+ </section>
+ <section
+ id="Examples of software components which support LDAP">
+ <title>Examples of software components which support LDAP</title>
+ <figure
+ id="LDAP-Tools">
+ <title>LDAP-Tools</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/ldap-tools.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Very different types of software products may act as LDAP clients, consuming data for authentication,
+ authorization or data presentation etc.
+ <itemizedlist>
+ <listitem>
+ <para>E-Mail clients (e.g. Mozilla Thunderbird)</para>
+ </listitem>
+ <listitem>
+ <para>LDAP tools (e.g. Apache Directory Studio)</para>
+ </listitem>
+ <listitem>
+ <para>Web servers (e.g. Apache Tomcat, Apache HTTP Server)</para>
+ </listitem>
+ <listitem>
+ <para>Mail servers (e.g. Apache James)</para>
+ </listitem>
+ <listitem>
+ <para>...</para>
+ </listitem>
+ </itemizedlist>
+ Configuration details for several of these programs in conjunction with ApacheDS are described in later
+ sections.
+ </para>
+ </section>
+ </section>
+ <section
+ id="ldapResources">
+ <title>LDAP resources</title>
+ <section
+ id="Books">
+ <title>Books</title>
+ <para>There are several good LDAP books available. Here are two examples which provide sample chapters on their
+ homepages.</para>
+ <para>
+ Understanding and Deploying LDAP Directory Services
+ <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>
+ </figure>
+ Understanding and Deploying LDAP Directory Services (2nd Edition)
+ by Timothy A. Howes, Mark C. Smith, Gordon S.
+ 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>
+ </para>
+ <para>
+ LDAP fuer Java-Entwickler
+ <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>
+ </figure>
+ LDAP fuer Java-Entwickler â Einstieg und Integration.
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/de.png" />
+ </imageobject>
+ </mediaobject>
+ 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>
+ </para>
+ </section>
+ <section
+ id="Articles, forums, blogs and other online resources">
+ <title>Articles, forums, blogs and other online resources</title>
+ <section
+ id="Blogs">
+ <title>Blogs</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link
+ xlink:href="http://blogs.sun.com/roller/page/DirectoryManager">cn=Directory Manager - All about Directory Server</link>
+ , Sun Blog
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section
+ id="Articles and other online resources">
+ <title>Articles and other online resources</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link
+ xlink:href="http://www.redbooks.ibm.com/abstracts/SG244986.html?Open">Understanding LDAP - Design and Implementation</link>
+ , 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>
+ by Brian K. Jones, O'Reilly Network
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link
+ xlink:href="http://www.mitlinx.de/ldap/">LDAP verstehen mit linx</link>
+ , by Petra Haberer
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/de.png" />
+ </imageobject>
+ </mediaobject>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ </section>
+ </section>
+
+ <section
+ id="Installing and starting the server">
+ <title>Installing and starting the server</title>
+ <para>This section describes how ApacheDS can be installed and started on different platforms.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="prerequisites" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Download a server installer" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Installation on Windows" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Installation on Mac OS X" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Installation on Linux and Solaris" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section
+ id="prerequisites">
+ <title>Prerequisites</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <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>
+ , but the server has also been successfully tested
+ with JRockit 5.0 and with IBM Java 5.0.
+ You can check your
+ java installation with:
+ <para>
+ <screen>java -version</screen>
+ </para>
+ this should response something like:
+ <para>
+ <screen><![CDATA[
+java version "1.5.0_06"
+Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
+Java
+HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode)
+ ]]></screen>
+ </para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>using Linux: you must have a X11 graphical interface</para>
+ </listitem>
+ <listitem>
+ <para>
+ <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>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section
+ id="Download a server installer">
+ <title>Download a server installer</title>
+ <para>
+ We provide native installers for several platforms:
+ <itemizedlist>
+ <listitem>
+ <para>Windows (exe)</para>
+ </listitem>
+ <listitem>
+ <para>Mac OS X (dmg)</para>
+ </listitem>
+ <listitem>
+ <para>Solaris x86 and SPARC (pkg)</para>
+ </listitem>
+ <listitem>
+ <para>Debian package (deb)</para>
+ </listitem>
+ <listitem>
+ <para>RPM package (rpm)</para>
+ </listitem>
+ <listitem>
+ <para>Linux Binary (bin)</para>
+ </listitem>
+ </itemizedlist>
+ Additional we provide an zip and tar.gz archive suitable for any platform.
+ </para>
+ <para>
+ You can download them from
+ <link
+ xlink:href="http://directory.apache.org/apacheds/1.5/downloads.html">here</link>
+ .
+ </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>
+ .
+ </para>
+ </section>
+ <section
+ id="Installation on Windows">
+ <title>Installation on Windows</title>
+ <para>Installing can be easily done using the Windows installer. Its interface and functionality is similar to
+ other
+ wizard based installers.</para>
+ <figure
+ id="Windows Installer">
+ <title>Windows Installer</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/Windows_Installer.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ To install the ApacheDS as Windows service you need
+ <emphasis
+ role="bold">Administrator</emphasis>
+ privileges.
+ </para>
+ <section
+ id="Starting and stopping the server Windows">
+ <title>Starting and stopping the server</title>
+ <para>
+ The server can be started and stopped with Windows Services manager (
+ <emphasis
+ role="bold">Control Panel > Administrative Tools > Services</emphasis>
+ ). You must be admin to do this.
+ </para>
+ <para>From there, you can easily start, stop and restart Apache DS.</para>
+ </section>
+ </section>
+ <section
+ id="Installation on Mac OS X">
+ <title>Installation on Mac OS X</title>
+ <para>To install Apache DS on Mac OS X, simply open the downloaded DMG file and then the "Apache Directory Server
+ Installer.pkg" in it.</para>
+ <figure
+ id="MacOSX Installer">
+ <title>MacOSX Installer</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/MacOSX_Installer.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>From there, you will be guided to install Apache DS on your system.</para>
+ <section
+ id="Starting and stopping the server MacOSX">
+ <title>Starting and stopping the server</title>
+ <para>On Mac OS X, Apache DS is installed as a launchd service and is loaded at startup time (and upon
+ successful
+ installation).</para>
+ <para>You can stop the server by unloading the launchd service with the following command line:</para>
+ <code>sudo launchctl unload /Library/LaunchDaemons/org.apache.directory.server.plist</code>
+ <para>You can start the server by loading the launchd service with the following command line:</para>
+ <code>sudo launchctl load /Library/LaunchDaemons/org.apache.directory.server.plist</code>
+ </section>
+ </section>
+ <section
+ id="Installation on Linux and Solaris">
+ <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>
+ page.
+ </para>
+ </section>
+ </section>
+
+ <section
+ id="Basic configuration tasks">
+ <title>Basic configuration tasks</title>
+ <section
+ id="Changing the server port for LDAP">
+ <title>Changing the server port for LDAP</title>
+ <para>This section describes how to change to port for the LDAP protocol.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="The task and how to accomplish it" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Resources_2" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section
+ id="The task and how to accomplish it">
+ <title>The task and how to accomplish it</title>
+ <para>By default the LDAP server listens on port 10389 (unencrypted or StartTLS) and 10636 (SSL). It is quite
+ common to run LDAP on 389, which is the well-known port for this protocol. Of course other options are
+ imaginable as well. Changing the LDAP port is a good example for adjusting the existing Spring configuration
+ as
+ introduced in the last section.</para>
+ <para>
+ Just pick the "ldapServer"-bean from the server.xml file
+ <programlisting><![CDATA[
+ <ldapServer id="ldapServer"
+ ...>
+ <transports>
+ <tcpTransport address="0.0.0.0" port="10389" nbThreads="8" backLog="50" enableSSL="false"/>
+ <tcpTransport address="localhost" port="10636" enableSSL="true"/>
+ </transports>
+ ...
+ </ldapServer>
+ ]]></programlisting>
+ and change the values of port to your needs. You have to restart the server afterwards in order to take this
+ change effect.
+ </para>
+ <important>
+ 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.
+ </important>
+ </section>
+ <section
+ id="Resources_1">
+ <title>Resources</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="Configuration Parameters Reference" />
+ : A Description of all configuration parameters in
+ <emphasis>server.xml</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section>
+ <title>Changing the admin password</title>
+ <para>This section describes the steps necessary to change the administrator password. Follow the instructions
+ provided here step by step.</para>
+
+ <section
+ id="Step one: Changing the value in the system partition">
+ <title>Step one: Changing the value in the system partition</title>
+ <para>While the server is up and running, change the value of the userPassword attribute of the admin
+ (uid=admin,ou=system) via LDAP. There are several ways to accomplish this task. In the following, we use the
+ Eclipse based Apache Directory Studio.</para>
+ <para>A new LDAP connection with this tool is created via "New Connection ..." from the Connections view. Enter
+ your connection data in the first step ...</para>
+ <figure
+ id="New LDAP Connection">
+ <title>New LDAP Connection</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/NewLDAPConnection1.png" />
+ </imageobject>
+ </mediaobject>
+ </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>
+ </figure>
+ <para>
+ Click
+ <emphasis>Finish</emphasis>
+ to establish the connection.
+ </para>
+ <para>
+ Afterwards, modify the value of the
+ <emphasis>userPassword</emphasis>
+ attribute of the entry
+ <emphasis>uid=admin,ou=system</emphasis>
+ . Navigate to the entry in the DIT (
+ <emphasis>LDAP Browser</emphasis>
+ view), and double click the attribute in the Entry Editor view:
+ </para>
+ <figure
+ id="Entry Editor">
+ <title>Entry Editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/entryEditor.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>The Password Editor dialog shows up; enter the new password. You can optionally select a hash algorithm
+ like
+ SHA. In this case, the password will be stored one-way encrypted in the attribute value â not a bad idea.
+ </para>
+ <figure
+ id="Password Editor">
+ <title>Password Editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/passwordEditor.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Pressing
+ <emphasis>OK</emphasis>
+ stores the new value. Close the connection and shutdown the server.
+ </para>
+ </section>
+ <section
+ id="Step two: Verification">
+ <title>Step two: Verification</title>
+ <para>
+ Verify that you can login as admin with the new password. With Apache Directory Studio, you can change the
+ properties of the existing connection profile via a right click in the
+ <emphasis>Connections</emphasis>
+ view and a selection of the
+ <emphasis>Properties</emphasis>
+ menu item. The following dialog appears:
+ </para>
+ <figure
+ id="Connection Properties">
+ <title>Connection Properties</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/connectionProperties.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Enter the new password and press
+ <emphasis>OK</emphasis>
+ . Establishing a connection should now work.
+ </para>
+ </section>
+ <section
+ id="Resources_2">
+ <title>Resources</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link
+ xlink:href="http://directory.apache.org/studio/">Apache Directory Studio</link>
+ : The tool used in steps 1 and 2
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+
+ <section
+ id="Adding your own partition resp. suffix">
+ <title>Adding your own partition resp. suffix</title>
+ <para>This section describes how to add your own data partition.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="What are partitions?" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Minimal partition definition" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Adding a partition programmatically" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="More configuration options for a JDBM partition" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section
+ id="What are partitions?">
+ <title>What are partitions?</title>
+ <para>In ApacheDS entries are stored in partitions. Each partition contains a complete entry tree, also referred
+ to as a DIT. Multiple partitions may exist and the entry trees they contain are disconnected from each other,
+ meaning that changes to entries in partition A would never affect entries in partition B. The entries in a
+ 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>
+ 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.
+ </para>
+ <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>
+ </figure>
+ <para>The schema subsystem and ApacheDS itself store their information in special partitions, "ou=schema" and
+ "ou=system" respectively.</para>
+ </section>
+ <section
+ id="Minimal partition definition">
+ <title>Minimal partition definition</title>
+ <para>For the examples in the following sections, we want to add a partition with the suffix "o=sevenSeas". This
+ requires editing of the server.xml file, and injecting a first entry, associated with the root of this
+ partition (here, "o=sevenseas") .</para>
+ <para>
+ Open the
+ <emphasis>server.xml</emphasis>
+ file for your directory instance in your favorite editor and look for the following element with name
+ partitions.
+ </para>
+ <programlisting><![CDATA[
+...
+ <partitions>
+ ...
+ <jdbmPartition id="example" cacheSize="100" suffix="dc=example,dc=com" optimizerEnabled="true"
+ syncOnWrite="true">
+ <indexedAttributes>
+ ...
+ </indexedAttributes>
+ </jdbmPartition>
+ </partitions>
+...
+ ]]></programlisting>
+ <para>
+ Save the
+ <emphasis>server.xml</emphasis>
+ file and restart the server. The server has a new suffix now, but no context entry has been created for it. If
+ you connect with an LDAP Browser (Apache Directory Studio for instance), the partition is only visible in the
+ Root DSE. Below the Entry Editor of Directory Studio for the Root DSE after connecting to an ApacheDS instance
+ configured like above.
+ </para>
+ <figure
+ id="Root DSE">
+ <title>Root DSE</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata
+ fileref="../images/root_dse.png" />
+ </imageobject>
+ </mediaobject>
+ </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
+ data set. In our example it might look like this:</para>
+ <programlisting><![CDATA[
+dn: o=sevenSeas
+o: sevenSeas
+objectClass: top
+objectClass: organization
+description: The context entry for suffix o=sevenSeas
+ ]]>
+ </programlisting>
+ <para>It is also possible to import a file to ApacheDS which only contains such an entry, of cause. Here is an
+ example on how to procede for the seven seas :</para>
+ <para>In the LDAP Browser of Directory Studio, right click on the DIT entry and select "Import -> LDIF
+ Import...". A file selections dialog appears. Browse to the LDIF file and click Finish. The entry (or entries,
+ if you provide more of them) will be added to to partition.</para>
+ <para>
+ The following image depicts the partitions after reconnecting with Apache Directory Studio (
+ <emphasis>LDAP Browser</emphasis>
+ view).
+ </para>
+ <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>
+ </figure>
+ </section>
+ <section
+ id="Loading the context entry automatically on startup">
+ <title>Loading the context entry automatically on startup</title>
+ <para>
+ If you don't want to launch Apache Studio, or to inject the LDIF file using a command line tool, you can
+ also
+ tells the server to load the file when it will be laucnhed the first time. Just create a ldif file
+ containing
+ the context entry, and add some tag into the
+ <emphasis>server.xml</emphasis>
+ file. For instance, you have created the
+ <emphasis
+ role="bold">sevenSeasRoot.ldif</emphasis>
+ file containing
+ </para>
+ <programlisting><![CDATA[
+# SevenSeas root context entry
+dn: o=sevenSeas
+o: sevenSeas
+objectClass: top
+objectClass: organization
+description: The context entry for suffix o=sevenSeas
+ ]]></programlisting>
+ <para>
+ Now just modify the
+ <emphasis>server.xml</emphasis>
+ file to add this line :
+ </para>
+ <programlisting><![CDATA[
+...
+ <apacheDS id="apacheDS"
+ synchPeriodMillis="15000"
+ allowAnonymousAccess="false">
+
+ <directoryService>#directoryService</directoryService>
+
+ We load the SevenSeas root context entry here
+ <ldifDirectory>sevenSeasRoot.ldif</ldifDirectory>
+...
+ ]]></programlisting>
+ <para>The contextEntry will be loaded when the server will be started the first time.</para>
+ </section>
+ <section
+ id="Adding a partition programmatically">
+ <title>Adding a partition programmatically</title>
+ <para>The same o=sevenseas partition can be created through the application code using the Partition and
+ DirectoryService API</para>
+ <para>Here is the sample code to create a new partition o=sevenseas and its context entry programmatically
+ </para>
+ <example
+ id="Sample code to create a new partition">
+ <title>Sample code to create a new partition</title>
+ <programlisting><![CDATA[
+JdbmPartition sevenseasPartition = new JdbmPartition();
+sevenseasPartition.setId("sevenseas");
+sevenseasPartition.setSuffix("o=sevenseas");
+sevenseasPartition.setCacheSize(1000);
+sevenseasPartition.init(directoryService);
+
+// Create some indices (optional)
+Set<Index<?,ServerEntry>> indexedAttrs = new HashSet<Index<?, ServerEntry>>();
+indexedAttrs.add( new JdbmIndex<Object, ServerEntry>("objectClass"));
+indexedAttrs.add( new JdbmIndex<Object, ServerEntry>("o"));
+sevenseasPartition.setIndexedAttributes( indexedAttrs );
+
+//Add partition to the directory service
+directoryService.addPartition(sevenseasPartition);
+
+// start the directory service
+directoryService.startup();
+
+// create the context entry
+ServerEntry entry = new DefaultServerEntry( directoryService.getRegistries(), new LdapDN( "o=sevenseas") );
+entry.put( "objectClass", "top", "organization" );
+entry.put("o","sevenseas");
+
+// add the context entry
+AddContextPartitionOperationContext adOpContext = new AddContextPartitionOperationContext( directoryService.getAdminSession(), sevenseasPartition );
+adOpContext.add( entry, null );
+directoryService.getPartitionNexus().addContextPartition( adOpContext );
+ ]]></programlisting>
+ </example>
+ </section>
+ <section
+ id="More configuration options for a JDBM partition">
+ <title>More configuration options for a JDBM partition</title>
+ <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">
+ <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>
+
+ <section
+ id="Configure logging">
+ <title>Configure logging</title>
+ <para>In order to detect and analyze problems, adjusting the log level of a server can be a valuable tool. This
+ section describes how to configure logging within a standalone ApacheDS.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xref
+ linkend="ApacheDS and logging" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Default behavior after installation" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Adjusting logging to your needs" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Example configurations" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Log settings of the Windows daemon process" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Resources logging" />
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section
+ id="ApacheDS and logging">
+ <title>ApacheDS and logging</title>
+ <para>
+ ApacheDS 1.5 uses
+ <link
+ xlink:href="http://www.slf4j.org/">SLF4J</link>
+ 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>
+ .
+ </para>
+ </section>
+ <section
+ id="Default behavior after installation">
+ <title>Default behavior after installation</title>
+ <para>
+ 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>
+ is used to collect warnings and errors. It
+ backups the log files when they reach a certain size.
+ </para>
+ <para>
+ Here is what the default configuration file
+ <emphasis>log4j.properties</emphasis>
+ , which is located in
+ <emphasis><APACHDS_HOME>/conf/</emphasis>
+ , looks like.
+ The name of the RollingFileAppender is "R":
+ </para>
+ <example
+ id="Configuration RollingFileAppender">
+ <title>Configuration RollingFileAppender</title>
+ <programlisting><![CDATA[
+log4j.rootCategory=WARN, stdout, R
+
+log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+
+log4j.appender.R=org.apache.log4j.RollingFileAppender
+log4j.appender.R.File=apacheds-rolling.log
+
+log4j.appender.R.MaxFileSize=1024KB
+# Keep some backup files
+log4j.appender.R.MaxBackupIndex=5
+
+log4j.appender.R.layout=org.apache.log4j.PatternLayout
+log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
+
+log4j.appender.stdout.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
+
+# 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>
+ </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
+ id="Linux/MacOS/Solaris">
+ <title>Linux/MacOS/Solaris</title>
+ <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>
+ <screen><![CDATA[
+$DAEMON_HOME/apacheds \
+...
+-outfile $SERVER_HOME/var/log/apacheds-stdout.log \
+-errfile $SERVER_HOME/var/log/apacheds-stderr.log \
+...
+$APACHEDS_HOME start
+ ]]></screen>
+ </example>
+ </section>
+ <section
+ id="Windows">
+ <title>Windows</title>
+ <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
+ <link
+ xlink:href="http://logging.apache.org/log4j/docs/manual.html">Short introduction to log4j</link>
+ .
+ </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>
+ <screen><![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
+...
+ ]]></screen>
+ <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
+ <link
+ xlink:href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html">javadoc of log4j</link>
+ 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>
+ <screen><![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
+...
+ ]]></screen>
+ <warning>
+ <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
+ <link
+ xlink:href="http://logging.apache.org/log4j/docs/chainsaw.html">Chainsaw</link>
+ .
+ </para>
+ <para>
+ Learn more about log4j and related tools at its
+ <link
+ xlink:href="http://logging.apache.org/log4j/docs/index.html">homepage</link>
+ .
+ </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>
+ <link
+ xlink:href="http://logging.apache.org/log4j/docs/manual.html">Short introduction to log4j</link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </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>
+ <para>
+ If you use the server standalone configured with a
+ <emphasis>server.xml</emphasis>
+ file, you can disable anonymous binds 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. Afterwards, all clients have to provide
+ 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
+ linkend="Authentication options">here</xref>
+ .
+ </para>
+ </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" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="LDAP Clients" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="The sample data (Sailors of the seven seas)" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xref
+ linkend="Resources RFC 2849" />
+ </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
+ <link
+ xlink:href="data/apache_ds_tutorial.ldif">apache_ds_tutorial.ldif</link>
+ 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
+ <link
+ xlink:href="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</link>
+ . 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" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Configure a partition for the sample date, described in
+ <xref
+ linkend="Basic configuration tasks" />
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Import the data, for instance using
+ <link
+ xlink:href="http://directory.apache.org/studio/">Apache Directory Studio</link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section
+ id="Resources RFC 2849">
+ <title>Resources</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link
+ xlink:href="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</link>
+ The LDAP Data Interchange Format (LDIF) â Technical Specification
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+</chapter>
Re: svn commit: r990643 - in /directory/apacheds-manuals/trunk/src/basic-user-guide:
book.xml chapter-how-to-begin.xml chapter-how-to-begin/chapter-how-to-begin.xml
Posted by Stefan Zoerner <st...@labeo.de>.
Felix Knecht wrote:
> Hi Stefan
>
> Images don't work for the html generated site anymore.
Thank you for the heads up. I have started to create subdirectories
and separate (smaller) XML-files for the content in order to make the
guide easier to manage. The problem with the images was present in PDF
(fixed), I will check the HTML output ...
Greetings from Hamburg,
StefanZ
Re: svn commit: r990643 - in /directory/apacheds-manuals/trunk/src/basic-user-guide:
book.xml chapter-how-to-begin.xml chapter-how-to-begin/chapter-how-to-begin.xml
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi Stefan
Images don't work for the html generated site anymore.
Felix
On 08/29/10 22:23, szoerner@apache.org wrote:
> Author: szoerner
> Date: Sun Aug 29 20:23:53 2010
> New Revision: 990643
>
> URL: http://svn.apache.org/viewvc?rev=990643&view=rev
> Log:
> moved one chapter in a separate folder. Will continue to do this with the rest
>
> Added:
> directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml
> Removed:
> directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin.xml
> Modified:
> directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml
>
> Modified: directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml
> URL: http://svn.apache.org/viewvc/directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml?rev=990643&r1=990642&r2=990643&view=diff
> ==============================================================================
> --- directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml (original)
> +++ directory/apacheds-manuals/trunk/src/basic-user-guide/book.xml Sun Aug 29 20:23:53 2010
> @@ -62,16 +62,16 @@ under the License.</literallayout>
> the ApacheDS 1.0 Basic User's Guide, which is currently more complete.
> </para>
> </preface>
> - <xi:include
> - href="chapter-basic-user-guide.xml" />
> - <xi:include
> - href="chapter-how-to-begin.xml" />
> - <xi:include
> - href="chapter-handling-of-data-within-your-directory.xml" />
> - <xi:include
> - href="chapter-basic-security.xml" />
> - <xi:include
> - href="chapter-integrating-apacheds-with-other-programs.xml" />
> +
> + <xi:include href="chapter-basic-user-guide.xml" />
> +
> + <xi:include href="chapter-how-to-begin/chapter-how-to-begin.xml" />
> +
> + <xi:include href="chapter-handling-of-data-within-your-directory.xml" />
> +
> + <xi:include href="chapter-basic-security.xml" />
> +
> + <xi:include href="chapter-integrating-apacheds-with-other-programs.xml" />
>
> <index> ... </index>
>
>
> Added: directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml
> URL: http://svn.apache.org/viewvc/directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml?rev=990643&view=auto
> ==============================================================================
> --- directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml (added)
> +++ directory/apacheds-manuals/trunk/src/basic-user-guide/chapter-how-to-begin/chapter-how-to-begin.xml Sun Aug 29 20:23:53 2010
> @@ -0,0 +1,1830 @@
> +<?xml version="1.0" encoding="utf-8"?>
> +<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file
> + distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under
> + the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may
> + obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to
> + in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
> + ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under
> + the License. -->
> +<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"
> + xmlns:ns3="http://www.w3.org/1999/xhtml"
> + xml:lang="en">
> + <title>How to begin</title>
> +
> + <section
> + id="What Apache Directory Server is">
> + <title>What Apache Directory Server is</title>
> + <para>
> + This section describes what Apache Directory Server (abbreviated ApacheDS) is, and where it comes from.
> + </para>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="System vision" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Origin and Motives" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Resources" />
> + </para>
> + </listitem>
> + </itemizedlist>
> + <section
> + id="System vision">
> + <title>
> + System vision</title>
> + <para>
> + ApacheDS 1.5 is an embeddable, extendable, standards compliant, modern LDAP server written entirely in Java,
> + and available
> + under the Apache Software License. Other network protocols like Kerberos and NTP are supported as
> + well (and even
> + more may be added), but basically (and especially for this introduction guide) ApacheDS is an LDAP
> + server.</para>
> + <para>
> + <emphasis>Embeddable</emphasis>
> + means that it is possible to configure, start and stop ApacheDS from other Java components,
> + especially
> + application servers, and the server runs within the same VM. The solution has already been
> + successfully embedded
> + in Apache Geronimo, JBoss, and others. The fact that the server is embeddable is quite
> + interesting, nevertheless
> + you also have the deployment option to run the server standalone, for instance as a
> + Windows service. Perhaps you
> + know this situation from other LDAP servers â open source (like OpenLDAP) as well
> + as commercial ones (like Sun
> + Java System Directory Server). This guide is dedicated to people that are new to
> + ApacheDS. The guide concentrates
> + on installing, configuring and running ApacheDS in a standalone configuration.
> + </para>
> + <para>
> + <emphasis>Extendable</emphasis>
> + means that the modern architecture of the solution provides many extension points. Write your own
> + partitions to
> + store directory data, interceptors to add functionality, etc. by implementing certain interfaces
> + and plugging
> + them in using Spring.
> + </para>
> + <para>
> + <emphasis>Standard</emphasis>
> + compliant means that ApacheDS 1.5 adheres to all RFCs relevant to
> + LDAPv3. Please note that version 1.0 of the
> + server has been successfully certified by the Open Group in September
> + 2006 ("LDAP certified"). Thus LDAP clients
> + may rightly expect that ApacheDS behaves like they expect.
> + </para>
> + <para>
> + <emphasis>Modern</emphasis>
> + means
> + that ApacheDS aims modernize the LDAP territory, as well as it favors standards compliance. New rich
> + integration
> + tier constructs like LDAP Stored Procedures and Triggers are being built on top of existing
> + standards.
> + </para>
> + <para>
> + <emphasis>Entirely</emphasis>
> + written in Java means that the software compiles and runs on a huge number of hardware and software platforms.
> + Native installers are available for Windows, MacOS and Solaris (both SPARC and intel platform), but in fact the
> + set of possible targets is by far more extensive.
> + </para>
> + <section
> + id="Architectural overview">
> + <title>Architectural overview</title>
> + <figure
> + id="50k FT Architecture">
> + <title>50k FT Architecture</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/50k-ft-architecture.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + </section>
> + </section>
> + <section
> + id="Origin and Motives">
> + <title>Origin and Motives</title>
> + <para>
> + Through his experiences with enterprise LDAP directories, Alex Karasulu, realized there is a great need
> + for
> + rich integration tier constructs like LDAP Stored Procedures, Triggers, and Views. In 2001 he set out to
> + alter
> + the OpenLDAP server to offer support for these useful facilities which are present in relational databases
> + but
> + missing in the LDAP world. Alex's attempts failed due to the complexity of the software which was brittle,
> + and
> + difficult to manage. As C code ported to several platforms, the OpenLDAP code base, had several #IFDEF
> + conditional pre-compiler directives that made it difficult to change the code. At this point Alex thought about
> + implementing a new LDAP server in pure Java. Thanks to NIO this was finally possible using the 1.4 JDK.
> + </para>
> + <para>
> + In October 2002 Alex Karasulu founded and registered the
> + <link
> + xlink:href="http://sourceforge.net/projects/ldapd">LDAPd</link>
> + 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>
> + in October 2003. One year later in October of
> + 2004,
> + the Apache Directory Top Level Project (TLP) was formed after
> + a successful incubation with the now called
> + Apache
> + Directory Server as its flagship product. After 4 years of
> + development, in October 2006, Apache Directory
> + Server
> + 1.0 was released as an Open Group certified LDAPv3 protocol
> + server. The certification has been renewed in
> + September 2007.
> + </para>
> + <para>Having a standards compliant and modern LDAP server, Apache Directory Team is now working on Identity and
> + Access Management solutions leveraging the directory technology.
> + </para>
> + </section>
> + <section
> + id="Resources">
> + <title>Resources</title>
> + <itemizedlist>
> + <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>
> + 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>
> + , Paper for 1st International Conference on LDAP, September 2007.
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + </section>
> +
> + <section
> + id="Some Background. Directories, directory services and LDAP">
> + <title>Some Background. Directories, directory services and LDAP</title>
> + <para>This section provides a brief overview about directories, directory services and LDAP. Furthermore you find
> + links to different resources (books, online resources, ...), which may act as introduction to the topic. If you
> + are
> + already an LDAP expert, you'll probably skip this section.</para>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="directoriesAndDirectoryServices" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="ldapTheLightWeightDirectoryAccessProtocol" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="ldapResources" />
> + </para>
> + </listitem>
> + </itemizedlist>
> + <section
> + id="directoriesAndDirectoryServices">
> + <title>Directories and directory services</title>
> + <para>Generally speaking, a directory is a collection or list of data. Real world examples are telephone books
> + (public or within organizations), church/land registers and listings of works (e.g. the Koechel-index, which
> + lists
> + all compositions of Mozart). All these examples have the purpose to preserve information and to make it
> + available
> + on demand to whom it may concern.</para>
> + <para>
> + Within information technology the term
> + <emphasis
> + role="bold">directory</emphasis>
> + is used for a special kind of data storage. It allows the
> + structured storage and efficient retrieval of objects
> + which are often derived from the real world (e.g. persons,
> + IT equipment). Characteristic:
> + <itemizedlist>
> + <listitem>
> + <para>
> + all data is stored in so called
> + <emphasis
> + role="bold">entries</emphasis>
> + </para>
> + </listitem>
> + <listitem>
> + <para>the set of entries within a directory forms a tree (hierarchical database)</para>
> + </listitem>
> + </itemizedlist>
> + </para>
> + <para>
> + A
> + <emphasis
> + role="bold">directory service</emphasis>
> + is a solution which offers users access to the information stored in the directory. A
> + directory assistance (call
> + center agent) is a good real world example for such a service. Within information
> + technologies, such services are
> + normally provided by software components. Directory services provide access to
> + the content of a directory via a
> + well-defined interface. If a network is used, an appropriate protocol has to be
> + defined. LDAP (see below) is such
> + a
> + protocol.
> + </para>
> + <para>
> + The real world examples mentioned above may be stored in such a directory, although other types of storage
> + systems
> + can be more appropriate (this depends on circumstance/requirements). At first sight directories compete
> + thereby as
> + data storage with the established relational data bases. However in the most large enterprises and
> + organizations
> + 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>
> + .
> + </para>
> + </section>
> + <section
> + id="ldapTheLightWeightDirectoryAccessProtocol">
> + <title>LDAP â the Lightweight Directory Access Protocol</title>
> + <section
> + id="What is it? Some history">
> + <title>What is it? Some history</title>
> + <para>
> + The comprehensive standard
> + <emphasis
> + role="bold">X.500</emphasis>
> + , finalized in 1988, builds the foundation for many of today's directory
> + solutions. Within this standard, the
> + client accesses the server via the Directory Access Protocol (
> + <emphasis
> + role="bold">DAP</emphasis>
> + ), which
> + is OSI protocol stack based. With the Internet boom in the nineties, the accessibility of directories
> + via
> + TCP/IP
> + became more and more important. Hence a TCP/IP-based access method, which in functionality was a
> + subset
> + of DAP,
> + was standardized in 1993: the
> + <emphasis
> + role="bold">Lightweight Directory Access Protocol (LDAP)</emphasis>
> + . First LDAP implementations
> + were
> + gateway solutions, they mediated between LDAP clients and X.500 servers. In
> + 1995
> + the University of
> + Michigan
> + presented the first native LDAP server; in the meantime the work is continued by
> + the
> + OpenLDAP project.
> + 1996
> + Netscape followed with the first commercial LDAP server (Netscape Directory Server,
> + foundation of several
> + later
> + LDAP servers). Other examples (among many others) include Microsoft Active Directory
> + and Novell
> + eDirectory. The
> + figure below shows the development of directory protocols from X.500/DAP to LDAP.
> + </para>
> + <figure
> + id="From X500 to LDAP">
> + <title>From X500 to LDAP</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/fromX500toLDAP.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + </section>
> + <section
> + id="Information model primer">
> + <title>Information model primer</title>
> + <para>
> + Within the information model of LDAP, data is stored in entries, which build up a hierarchical, tree like
> + structure. Each entry has a unique name (
> + <emphasis
> + role="bold">DN, Distinguished Name</emphasis>
> + ), which depicts its position within the tree.
> + An
> + entry consists of key/value pairs, the
> + <emphasis
> + role="bold">attributes</emphasis>
> + . Some attributes may occur more than once within an entry
> + (single or multi valued, e.g. a person can have more
> + than one telephone number). So called
> + <emphasis
> + role="bold">object classes</emphasis>
> + define, which attributes an entry may have, and which of them are required. The classes build up a hierarchy
> + with
> + <emphasis
> + role="bold">top</emphasis>
> + as root; there is a parallelism to the object oriented world. top forces only the attribute
> + objectclass, which
> + assigns an entry its object classes. A
> + <emphasis
> + role="bold">schema</emphasis>
> + consists object classes and attribute types,
> + and therefore defines, what kind of entries can be stored within
> + the
> + directory. Directory servers ship a
> + schema
> + out-of-the-box, often with elements standardized by RFCs. In
> + addition,
> + most directory solutions allow
> + you to
> + define custom object classes and attributes. But in practice,
> + the
> + pre-defined
> + elements are used.
> + Sometimes
> + they
> + get extended according to special requirements.
> + </para>
> + </section>
> + <section
> + id="Common applications of LDAP based directories">
> + <title>Common applications of LDAP based directories</title>
> + <para>LDAP operations include entry creation, modification, deletion and search. As a general rule, LDAP
> + directories are optimized for read and search operations, at the cost of write performance. Data, which will
> + be
> + modified often, therefore better suits in a relational database, which offers better support for
> + transactions and
> + referential integrity as well. Directories are rather used if comparatively stable data has
> + to
> + be provided
> + centrally. </para>
> + <para>Common examples are network resources (printers, services) and user data (including credentials and rights
> + for the resources). As a notable feature, many directory products offer replicas, which permit better access
> + times and higher availability especially in geographically dispersed organizations. Not for nothing, the most
> + common LDAP application is the enterprise phone book. That even Microsoft Outlook may be an LDAP client in
> + this
> + case - most average users probably don't know.</para>
> + </section>
> + <section
> + id="Examples of software components which support LDAP">
> + <title>Examples of software components which support LDAP</title>
> + <figure
> + id="LDAP-Tools">
> + <title>LDAP-Tools</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/ldap-tools.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + <para>
> + Very different types of software products may act as LDAP clients, consuming data for authentication,
> + authorization or data presentation etc.
> + <itemizedlist>
> + <listitem>
> + <para>E-Mail clients (e.g. Mozilla Thunderbird)</para>
> + </listitem>
> + <listitem>
> + <para>LDAP tools (e.g. Apache Directory Studio)</para>
> + </listitem>
> + <listitem>
> + <para>Web servers (e.g. Apache Tomcat, Apache HTTP Server)</para>
> + </listitem>
> + <listitem>
> + <para>Mail servers (e.g. Apache James)</para>
> + </listitem>
> + <listitem>
> + <para>...</para>
> + </listitem>
> + </itemizedlist>
> + Configuration details for several of these programs in conjunction with ApacheDS are described in later
> + sections.
> + </para>
> + </section>
> + </section>
> + <section
> + id="ldapResources">
> + <title>LDAP resources</title>
> + <section
> + id="Books">
> + <title>Books</title>
> + <para>There are several good LDAP books available. Here are two examples which provide sample chapters on their
> + homepages.</para>
> + <para>
> + Understanding and Deploying LDAP Directory Services
> + <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>
> + </figure>
> + Understanding and Deploying LDAP Directory Services (2nd Edition)
> + by Timothy A. Howes, Mark C. Smith, Gordon S.
> + 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>
> + </para>
> + <para>
> + LDAP fuer Java-Entwickler
> + <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>
> + </figure>
> + LDAP fuer Java-Entwickler â Einstieg und Integration.
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/de.png" />
> + </imageobject>
> + </mediaobject>
> + 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>
> + </para>
> + </section>
> + <section
> + id="Articles, forums, blogs and other online resources">
> + <title>Articles, forums, blogs and other online resources</title>
> + <section
> + id="Blogs">
> + <title>Blogs</title>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <link
> + xlink:href="http://blogs.sun.com/roller/page/DirectoryManager">cn=Directory Manager - All about Directory Server</link>
> + , Sun Blog
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + <section
> + id="Articles and other online resources">
> + <title>Articles and other online resources</title>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <link
> + xlink:href="http://www.redbooks.ibm.com/abstracts/SG244986.html?Open">Understanding LDAP - Design and Implementation</link>
> + , 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>
> + by Brian K. Jones, O'Reilly Network
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <link
> + xlink:href="http://www.mitlinx.de/ldap/">LDAP verstehen mit linx</link>
> + , by Petra Haberer
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/de.png" />
> + </imageobject>
> + </mediaobject>
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + </section>
> + </section>
> + </section>
> +
> + <section
> + id="Installing and starting the server">
> + <title>Installing and starting the server</title>
> + <para>This section describes how ApacheDS can be installed and started on different platforms.</para>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="prerequisites" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Download a server installer" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Installation on Windows" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Installation on Mac OS X" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Installation on Linux and Solaris" />
> + </para>
> + </listitem>
> + </itemizedlist>
> + <section
> + id="prerequisites">
> + <title>Prerequisites</title>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <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>
> + , but the server has also been successfully tested
> + with JRockit 5.0 and with IBM Java 5.0.
> + You can check your
> + java installation with:
> + <para>
> + <screen>java -version</screen>
> + </para>
> + this should response something like:
> + <para>
> + <screen><![CDATA[
> +java version "1.5.0_06"
> +Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-b05)
> +Java
> +HotSpot(TM) Client VM (build 1.5.0_06-b05, mixed mode)
> + ]]></screen>
> + </para>
> + </para>
> + </listitem>
> + <listitem>
> + <para>using Linux: you must have a X11 graphical interface</para>
> + </listitem>
> + <listitem>
> + <para>
> + <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>
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + <section
> + id="Download a server installer">
> + <title>Download a server installer</title>
> + <para>
> + We provide native installers for several platforms:
> + <itemizedlist>
> + <listitem>
> + <para>Windows (exe)</para>
> + </listitem>
> + <listitem>
> + <para>Mac OS X (dmg)</para>
> + </listitem>
> + <listitem>
> + <para>Solaris x86 and SPARC (pkg)</para>
> + </listitem>
> + <listitem>
> + <para>Debian package (deb)</para>
> + </listitem>
> + <listitem>
> + <para>RPM package (rpm)</para>
> + </listitem>
> + <listitem>
> + <para>Linux Binary (bin)</para>
> + </listitem>
> + </itemizedlist>
> + Additional we provide an zip and tar.gz archive suitable for any platform.
> + </para>
> + <para>
> + You can download them from
> + <link
> + xlink:href="http://directory.apache.org/apacheds/1.5/downloads.html">here</link>
> + .
> + </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>
> + .
> + </para>
> + </section>
> + <section
> + id="Installation on Windows">
> + <title>Installation on Windows</title>
> + <para>Installing can be easily done using the Windows installer. Its interface and functionality is similar to
> + other
> + wizard based installers.</para>
> + <figure
> + id="Windows Installer">
> + <title>Windows Installer</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/Windows_Installer.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + <para>
> + To install the ApacheDS as Windows service you need
> + <emphasis
> + role="bold">Administrator</emphasis>
> + privileges.
> + </para>
> + <section
> + id="Starting and stopping the server Windows">
> + <title>Starting and stopping the server</title>
> + <para>
> + The server can be started and stopped with Windows Services manager (
> + <emphasis
> + role="bold">Control Panel > Administrative Tools > Services</emphasis>
> + ). You must be admin to do this.
> + </para>
> + <para>From there, you can easily start, stop and restart Apache DS.</para>
> + </section>
> + </section>
> + <section
> + id="Installation on Mac OS X">
> + <title>Installation on Mac OS X</title>
> + <para>To install Apache DS on Mac OS X, simply open the downloaded DMG file and then the "Apache Directory Server
> + Installer.pkg" in it.</para>
> + <figure
> + id="MacOSX Installer">
> + <title>MacOSX Installer</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/MacOSX_Installer.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + <para>From there, you will be guided to install Apache DS on your system.</para>
> + <section
> + id="Starting and stopping the server MacOSX">
> + <title>Starting and stopping the server</title>
> + <para>On Mac OS X, Apache DS is installed as a launchd service and is loaded at startup time (and upon
> + successful
> + installation).</para>
> + <para>You can stop the server by unloading the launchd service with the following command line:</para>
> + <code>sudo launchctl unload /Library/LaunchDaemons/org.apache.directory.server.plist</code>
> + <para>You can start the server by loading the launchd service with the following command line:</para>
> + <code>sudo launchctl load /Library/LaunchDaemons/org.apache.directory.server.plist</code>
> + </section>
> + </section>
> + <section
> + id="Installation on Linux and Solaris">
> + <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>
> + page.
> + </para>
> + </section>
> + </section>
> +
> + <section
> + id="Basic configuration tasks">
> + <title>Basic configuration tasks</title>
> + <section
> + id="Changing the server port for LDAP">
> + <title>Changing the server port for LDAP</title>
> + <para>This section describes how to change to port for the LDAP protocol.</para>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="The task and how to accomplish it" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Resources_2" />
> + </para>
> + </listitem>
> + </itemizedlist>
> + <section
> + id="The task and how to accomplish it">
> + <title>The task and how to accomplish it</title>
> + <para>By default the LDAP server listens on port 10389 (unencrypted or StartTLS) and 10636 (SSL). It is quite
> + common to run LDAP on 389, which is the well-known port for this protocol. Of course other options are
> + imaginable as well. Changing the LDAP port is a good example for adjusting the existing Spring configuration
> + as
> + introduced in the last section.</para>
> + <para>
> + Just pick the "ldapServer"-bean from the server.xml file
> + <programlisting><![CDATA[
> + <ldapServer id="ldapServer"
> + ...>
> + <transports>
> + <tcpTransport address="0.0.0.0" port="10389" nbThreads="8" backLog="50" enableSSL="false"/>
> + <tcpTransport address="localhost" port="10636" enableSSL="true"/>
> + </transports>
> + ...
> + </ldapServer>
> + ]]></programlisting>
> + and change the values of port to your needs. You have to restart the server afterwards in order to take this
> + change effect.
> + </para>
> + <important>
> + 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.
> + </important>
> + </section>
> + <section
> + id="Resources_1">
> + <title>Resources</title>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="Configuration Parameters Reference" />
> + : A Description of all configuration parameters in
> + <emphasis>server.xml</emphasis>
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + </section>
> + <section>
> + <title>Changing the admin password</title>
> + <para>This section describes the steps necessary to change the administrator password. Follow the instructions
> + provided here step by step.</para>
> +
> + <section
> + id="Step one: Changing the value in the system partition">
> + <title>Step one: Changing the value in the system partition</title>
> + <para>While the server is up and running, change the value of the userPassword attribute of the admin
> + (uid=admin,ou=system) via LDAP. There are several ways to accomplish this task. In the following, we use the
> + Eclipse based Apache Directory Studio.</para>
> + <para>A new LDAP connection with this tool is created via "New Connection ..." from the Connections view. Enter
> + your connection data in the first step ...</para>
> + <figure
> + id="New LDAP Connection">
> + <title>New LDAP Connection</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/NewLDAPConnection1.png" />
> + </imageobject>
> + </mediaobject>
> + </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>
> + </figure>
> + <para>
> + Click
> + <emphasis>Finish</emphasis>
> + to establish the connection.
> + </para>
> + <para>
> + Afterwards, modify the value of the
> + <emphasis>userPassword</emphasis>
> + attribute of the entry
> + <emphasis>uid=admin,ou=system</emphasis>
> + . Navigate to the entry in the DIT (
> + <emphasis>LDAP Browser</emphasis>
> + view), and double click the attribute in the Entry Editor view:
> + </para>
> + <figure
> + id="Entry Editor">
> + <title>Entry Editor</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/entryEditor.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + <para>The Password Editor dialog shows up; enter the new password. You can optionally select a hash algorithm
> + like
> + SHA. In this case, the password will be stored one-way encrypted in the attribute value â not a bad idea.
> + </para>
> + <figure
> + id="Password Editor">
> + <title>Password Editor</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/passwordEditor.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + <para>
> + Pressing
> + <emphasis>OK</emphasis>
> + stores the new value. Close the connection and shutdown the server.
> + </para>
> + </section>
> + <section
> + id="Step two: Verification">
> + <title>Step two: Verification</title>
> + <para>
> + Verify that you can login as admin with the new password. With Apache Directory Studio, you can change the
> + properties of the existing connection profile via a right click in the
> + <emphasis>Connections</emphasis>
> + view and a selection of the
> + <emphasis>Properties</emphasis>
> + menu item. The following dialog appears:
> + </para>
> + <figure
> + id="Connection Properties">
> + <title>Connection Properties</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/connectionProperties.png" />
> + </imageobject>
> + </mediaobject>
> + </figure>
> + <para>
> + Enter the new password and press
> + <emphasis>OK</emphasis>
> + . Establishing a connection should now work.
> + </para>
> + </section>
> + <section
> + id="Resources_2">
> + <title>Resources</title>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <link
> + xlink:href="http://directory.apache.org/studio/">Apache Directory Studio</link>
> + : The tool used in steps 1 and 2
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + </section>
> +
> + <section
> + id="Adding your own partition resp. suffix">
> + <title>Adding your own partition resp. suffix</title>
> + <para>This section describes how to add your own data partition.</para>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="What are partitions?" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Minimal partition definition" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Adding a partition programmatically" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="More configuration options for a JDBM partition" />
> + </para>
> + </listitem>
> + </itemizedlist>
> + <section
> + id="What are partitions?">
> + <title>What are partitions?</title>
> + <para>In ApacheDS entries are stored in partitions. Each partition contains a complete entry tree, also referred
> + to as a DIT. Multiple partitions may exist and the entry trees they contain are disconnected from each other,
> + meaning that changes to entries in partition A would never affect entries in partition B. The entries in a
> + 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>
> + 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.
> + </para>
> + <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>
> + </figure>
> + <para>The schema subsystem and ApacheDS itself store their information in special partitions, "ou=schema" and
> + "ou=system" respectively.</para>
> + </section>
> + <section
> + id="Minimal partition definition">
> + <title>Minimal partition definition</title>
> + <para>For the examples in the following sections, we want to add a partition with the suffix "o=sevenSeas". This
> + requires editing of the server.xml file, and injecting a first entry, associated with the root of this
> + partition (here, "o=sevenseas") .</para>
> + <para>
> + Open the
> + <emphasis>server.xml</emphasis>
> + file for your directory instance in your favorite editor and look for the following element with name
> + partitions.
> + </para>
> + <programlisting><![CDATA[
> +...
> + <partitions>
> + ...
> + <jdbmPartition id="example" cacheSize="100" suffix="dc=example,dc=com" optimizerEnabled="true"
> + syncOnWrite="true">
> + <indexedAttributes>
> + ...
> + </indexedAttributes>
> + </jdbmPartition>
> + </partitions>
> +...
> + ]]></programlisting>
> + <para>
> + Save the
> + <emphasis>server.xml</emphasis>
> + file and restart the server. The server has a new suffix now, but no context entry has been created for it. If
> + you connect with an LDAP Browser (Apache Directory Studio for instance), the partition is only visible in the
> + Root DSE. Below the Entry Editor of Directory Studio for the Root DSE after connecting to an ApacheDS instance
> + configured like above.
> + </para>
> + <figure
> + id="Root DSE">
> + <title>Root DSE</title>
> + <mediaobject>
> + <imageobject>
> + <imagedata
> + fileref="../images/root_dse.png" />
> + </imageobject>
> + </mediaobject>
> + </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
> + data set. In our example it might look like this:</para>
> + <programlisting><![CDATA[
> +dn: o=sevenSeas
> +o: sevenSeas
> +objectClass: top
> +objectClass: organization
> +description: The context entry for suffix o=sevenSeas
> + ]]>
> + </programlisting>
> + <para>It is also possible to import a file to ApacheDS which only contains such an entry, of cause. Here is an
> + example on how to procede for the seven seas :</para>
> + <para>In the LDAP Browser of Directory Studio, right click on the DIT entry and select "Import -> LDIF
> + Import...". A file selections dialog appears. Browse to the LDIF file and click Finish. The entry (or entries,
> + if you provide more of them) will be added to to partition.</para>
> + <para>
> + The following image depicts the partitions after reconnecting with Apache Directory Studio (
> + <emphasis>LDAP Browser</emphasis>
> + view).
> + </para>
> + <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>
> + </figure>
> + </section>
> + <section
> + id="Loading the context entry automatically on startup">
> + <title>Loading the context entry automatically on startup</title>
> + <para>
> + If you don't want to launch Apache Studio, or to inject the LDIF file using a command line tool, you can
> + also
> + tells the server to load the file when it will be laucnhed the first time. Just create a ldif file
> + containing
> + the context entry, and add some tag into the
> + <emphasis>server.xml</emphasis>
> + file. For instance, you have created the
> + <emphasis
> + role="bold">sevenSeasRoot.ldif</emphasis>
> + file containing
> + </para>
> + <programlisting><![CDATA[
> +# SevenSeas root context entry
> +dn: o=sevenSeas
> +o: sevenSeas
> +objectClass: top
> +objectClass: organization
> +description: The context entry for suffix o=sevenSeas
> + ]]></programlisting>
> + <para>
> + Now just modify the
> + <emphasis>server.xml</emphasis>
> + file to add this line :
> + </para>
> + <programlisting><![CDATA[
> +...
> + <apacheDS id="apacheDS"
> + synchPeriodMillis="15000"
> + allowAnonymousAccess="false">
> +
> + <directoryService>#directoryService</directoryService>
> +
> + We load the SevenSeas root context entry here
> + <ldifDirectory>sevenSeasRoot.ldif</ldifDirectory>
> +...
> + ]]></programlisting>
> + <para>The contextEntry will be loaded when the server will be started the first time.</para>
> + </section>
> + <section
> + id="Adding a partition programmatically">
> + <title>Adding a partition programmatically</title>
> + <para>The same o=sevenseas partition can be created through the application code using the Partition and
> + DirectoryService API</para>
> + <para>Here is the sample code to create a new partition o=sevenseas and its context entry programmatically
> + </para>
> + <example
> + id="Sample code to create a new partition">
> + <title>Sample code to create a new partition</title>
> + <programlisting><![CDATA[
> +JdbmPartition sevenseasPartition = new JdbmPartition();
> +sevenseasPartition.setId("sevenseas");
> +sevenseasPartition.setSuffix("o=sevenseas");
> +sevenseasPartition.setCacheSize(1000);
> +sevenseasPartition.init(directoryService);
> +
> +// Create some indices (optional)
> +Set<Index<?,ServerEntry>> indexedAttrs = new HashSet<Index<?, ServerEntry>>();
> +indexedAttrs.add( new JdbmIndex<Object, ServerEntry>("objectClass"));
> +indexedAttrs.add( new JdbmIndex<Object, ServerEntry>("o"));
> +sevenseasPartition.setIndexedAttributes( indexedAttrs );
> +
> +//Add partition to the directory service
> +directoryService.addPartition(sevenseasPartition);
> +
> +// start the directory service
> +directoryService.startup();
> +
> +// create the context entry
> +ServerEntry entry = new DefaultServerEntry( directoryService.getRegistries(), new LdapDN( "o=sevenseas") );
> +entry.put( "objectClass", "top", "organization" );
> +entry.put("o","sevenseas");
> +
> +// add the context entry
> +AddContextPartitionOperationContext adOpContext = new AddContextPartitionOperationContext( directoryService.getAdminSession(), sevenseasPartition );
> +adOpContext.add( entry, null );
> +directoryService.getPartitionNexus().addContextPartition( adOpContext );
> + ]]></programlisting>
> + </example>
> + </section>
> + <section
> + id="More configuration options for a JDBM partition">
> + <title>More configuration options for a JDBM partition</title>
> + <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">
> + <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>
> +
> + <section
> + id="Configure logging">
> + <title>Configure logging</title>
> + <para>In order to detect and analyze problems, adjusting the log level of a server can be a valuable tool. This
> + section describes how to configure logging within a standalone ApacheDS.</para>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <xref
> + linkend="ApacheDS and logging" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Default behavior after installation" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Adjusting logging to your needs" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Example configurations" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Log settings of the Windows daemon process" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Resources logging" />
> + </para>
> + </listitem>
> + </itemizedlist>
> + <section
> + id="ApacheDS and logging">
> + <title>ApacheDS and logging</title>
> + <para>
> + ApacheDS 1.5 uses
> + <link
> + xlink:href="http://www.slf4j.org/">SLF4J</link>
> + 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>
> + .
> + </para>
> + </section>
> + <section
> + id="Default behavior after installation">
> + <title>Default behavior after installation</title>
> + <para>
> + 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>
> + is used to collect warnings and errors. It
> + backups the log files when they reach a certain size.
> + </para>
> + <para>
> + Here is what the default configuration file
> + <emphasis>log4j.properties</emphasis>
> + , which is located in
> + <emphasis><APACHDS_HOME>/conf/</emphasis>
> + , looks like.
> + The name of the RollingFileAppender is "R":
> + </para>
> + <example
> + id="Configuration RollingFileAppender">
> + <title>Configuration RollingFileAppender</title>
> + <programlisting><![CDATA[
> +log4j.rootCategory=WARN, stdout, R
> +
> +log4j.appender.stdout=org.apache.log4j.ConsoleAppender
> +log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
> +
> +log4j.appender.R=org.apache.log4j.RollingFileAppender
> +log4j.appender.R.File=apacheds-rolling.log
> +
> +log4j.appender.R.MaxFileSize=1024KB
> +# Keep some backup files
> +log4j.appender.R.MaxBackupIndex=5
> +
> +log4j.appender.R.layout=org.apache.log4j.PatternLayout
> +log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
> +
> +log4j.appender.stdout.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
> +
> +# 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>
> + </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
> + id="Linux/MacOS/Solaris">
> + <title>Linux/MacOS/Solaris</title>
> + <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>
> + <screen><![CDATA[
> +$DAEMON_HOME/apacheds \
> +...
> +-outfile $SERVER_HOME/var/log/apacheds-stdout.log \
> +-errfile $SERVER_HOME/var/log/apacheds-stderr.log \
> +...
> +$APACHEDS_HOME start
> + ]]></screen>
> + </example>
> + </section>
> + <section
> + id="Windows">
> + <title>Windows</title>
> + <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
> + <link
> + xlink:href="http://logging.apache.org/log4j/docs/manual.html">Short introduction to log4j</link>
> + .
> + </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>
> + <screen><![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
> +...
> + ]]></screen>
> + <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
> + <link
> + xlink:href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html">javadoc of log4j</link>
> + 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>
> + <screen><![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
> +...
> + ]]></screen>
> + <warning>
> + <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
> + <link
> + xlink:href="http://logging.apache.org/log4j/docs/chainsaw.html">Chainsaw</link>
> + .
> + </para>
> + <para>
> + Learn more about log4j and related tools at its
> + <link
> + xlink:href="http://logging.apache.org/log4j/docs/index.html">homepage</link>
> + .
> + </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>
> + <link
> + xlink:href="http://logging.apache.org/log4j/docs/manual.html">Short introduction to log4j</link>
> + </para>
> + </listitem>
> + </itemizedlist>
> + </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>
> + <para>
> + If you use the server standalone configured with a
> + <emphasis>server.xml</emphasis>
> + file, you can disable anonymous binds 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. Afterwards, all clients have to provide
> + 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
> + linkend="Authentication options">here</xref>
> + .
> + </para>
> + </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" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="LDAP Clients" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="The sample data (Sailors of the seven seas)" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + <xref
> + linkend="Resources RFC 2849" />
> + </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
> + <link
> + xlink:href="data/apache_ds_tutorial.ldif">apache_ds_tutorial.ldif</link>
> + 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
> + <link
> + xlink:href="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</link>
> + . 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" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + Configure a partition for the sample date, described in
> + <xref
> + linkend="Basic configuration tasks" />
> + </para>
> + </listitem>
> + <listitem>
> + <para>
> + Import the data, for instance using
> + <link
> + xlink:href="http://directory.apache.org/studio/">Apache Directory Studio</link>
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + <section
> + id="Resources RFC 2849">
> + <title>Resources</title>
> + <itemizedlist>
> + <listitem>
> + <para>
> + <link
> + xlink:href="http://www.faqs.org/rfcs/rfc2849.html">RFC 2849</link>
> + The LDAP Data Interchange Format (LDIF) â Technical Specification
> + </para>
> + </listitem>
> + </itemizedlist>
> + </section>
> + </section>
> +</chapter>
>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkx7M4EACgkQ2lZVCB08qHHdtgCfe1N0b4zmu/GtB1+5or7gJvna
SPgAoJWW7FA5mexDgcxiNwdy0TrQoz6a
=PP9x
-----END PGP SIGNATURE-----