Basic configuration tasks

This section describes some important configuration tasks. The selection is partly driven by questions frequently asked on the mailing list.

Configuration of ApacheDS with Spring

There are several options to configure ApacheDS. For instance you can practically do everything programmatically if you embed the server in a Java component.

For this guide we assume a standard installation of ApacheDS run standalone, and the default mechanism to configure this deployment option is (in almost all cases) changing the file server.xml, which is located in the conf directory of your ApacheDS installation. The file is composed of bean definitions, because configuration in ApacheDS 1.0 is done with the help of the Spring Framework.

Despite the fact that the default server.xml shipped with the product is somewhat long, a quick look with the help of the Spring IDE displays that the structure is rather simple:

Most configuration tasks can be accomplished by modifying the properties of existing bean definitions, or (e.g. for a new partition) by adding new beans of certain types and wiring them to the configuration.

Note that the picture above does not show all properties available in the configuration. Only those are visible for which the default server.xml contains a value. There are more, and in case of absence the default value is choosen. Feel free to browse the file to get an impression about further optione – several other features controlled by properties are commented out.

Changing the server port for LDAP

By default the LDAP server listens on port 10389. 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 paragraph above.

Just pick the following line within the "configuration"-bean from the server.xml file

and change it to your needs. You have to restart the server afterwards in order to take this change effect.

Changing the admin password

Changing the admin password is a bit tricky at the moment. We will simplify that in one of the next releases:

1. First while the server is up and running log into as admin (uid=admin,ou=system) using the default password 'secret' and bind to ou=system. If you are using JXplorer this will look like the following:
   
2. Change the userPassword attribute in the admin entry.
   
3. Shutdown the server.
4. Open the conf/server.xml file and set the admin password, currently set to 'secret', to the new value. xml <prop key="java.naming.security.credentials">secret</prop>
5. Start up the server.
6. Verify that you can login as admin with the new password.

Adding your own partition resp. suffix

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 partiton suffix. The implementation of partitions is based on JDBM B+Trees (but it's possible to add custom partition implementations). The ApacheDS default configuration contains a a partition with the suffix "dc=example,dc=com".

The following attributes are used when defining a partition's configuration:

• An id, which uniquely identifies the partition
• A external name, which is used by managing tools
• A cacheSize, the cache size expressed as a number of entries.
• A suffix which is a LdapDN object (dc=example, dc=com, for instance)
• indexedAttributes, a set of attributes which will be indexed
• contextEntry, the root entry that will be added to the partition
• And some specific parameters associated with the backend (synchOnWrite, optimizerEnabled, etc).

For the examples in the following sections, we want to add a partition with the suffix "o=sevenSeas" and the id "sevenSeasPartitionConfiguration". This requires editing of the conf/server.xml file. Open it in your favorite editor and look for the following element with name contextPartitionConfigurations. Add another ref element for the sevenSeas partition.

Now we will add the actual partition. Just copy & paste this set of elements in the configuration file:

Now we will update the elements step by step. First change the id to the value added to the contextPartitionConfiguration element.

Before:

After:

Next give the partition a name and change the suffix to o=sevenSeas
Before:

After:

Configuration of the indexed Attributes is described at #Configure indices.
The last property remaining now is the context entry. The objectclasses top and extensibleObject are universal hence they remain. But the objectclass domain is replaced by the objectclass organization, because our partition shouldn't represent a domain but an organization.
Before:

After:

Afterwards restart the server.

Configure logging

ApacheDS 1.0 uses NLOG4j as its logging solution. This is a simple facade for various logging APIs. The default for ApacheDS 1.0 is log4j, detailed properties can be configured by modifying the file <APACHDS_HOME>/conf/log4j.properties.

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:

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 below.

Default behaviour after installation of ApacheDS 1.0

By default, ApacheDS writes log files in the directory <APACHDS_HOME>/var/log/. Besides stdout, a RollingFileAppender is used to collect warnings and errors. It backups the log files when they reach a certain size.

Here is what the default configuration file log4j.properties looks like. The name of the RollingFileAppender is "R":

In this file "R" is configured like this:

If the default logging does not meet your requirements, you can easily adjust the configuration to your needs.

Adjusting logging to your needs

Log file location (where the log files are placed)

By default the log files are placed at <apacheds_home>/var/log, but that can be changed.

Linux/MacOS/Solaris

On this systems the location of the log files is configured via an entry in /bin/server.init. Look for the following lines and change it to your preferences:

Windows

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 Redirect Stdout and Redirect Stderror

Log level (how detailed the logs are)

The following log levels from log4j are used for messages within ApacheDS:

The default (global) log level in the configuration is WARN. All messages of level WARN and more severe (ERROR, FATAL) are written to the rolling log fil. The easiest way to get finer log messages is to change it like this

These detailed log messages took much file space and time and therefore should only be enabled globally in order to analyze problems.

It is possible to configure the logging more fine grained by using categories. Within the default configuration there are some examples:

If the global level is switched to DEBUG, these definitions overide 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 Short introduction to log4j.

Format for log messages

The format of each line within a log file is controlled by a pattern. For the RollingFileAppender in the default configuration it looks like this

Some examples lines within the log file, formatted with the pattern "[%d{HH:mm:ss}] %p [%c] - %m%n" are:

The pattern uses the following conversion characters:

The javadoc of log4j contains a table with all valid %-characters and their meaning.

Simple adjust the pattern in the log4j.properties file to get the log format of your choice, for instance

leads to messages of this form:

Advanced log4j configuration

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 Chainsaw.

Learn more about log4j and related tools at its homepage.

Enable/disable anonymous access

Anonymous access to the server is disabled by default. All clients have to provide their name (distinguished name) and password in order to bind to the directory service. If you use the server standalone configured with a server.xml file, you can enable anonymous binds by changing the value for property allowAnonymousAccess in the Spring bean definition for bean configuration, as depicted in the following fragment:

A restart of the server is necessary for this change to take effect. Learn more about authentication option in the corresponding section of this guide here.

Configure indices

( -> http://cwiki.apache.org/confluence/display/DIRxSRVx10/Performance+Tuning )
( -> http://cwiki.apache.org/confluence/display/DIRxSRVx11/Backend )

(Re)Building Indices

Sometimes after loading a database you want to index another attribute but forgot to set up the index configuration for that attribute. Let's presume you have a partition called "example" with 5 million inetOrgPersons in it. All of a sudden your application starts conducting searchs for the state (the st attribute) of the user. Reloading this partition after adding the index configuration for the st attribute is out of the question.

Luckily building the st index is pretty easy to do using the apacheds-tools supplied with an ApacheDS binary installation. Here's the command you have to execute on your system to build the st attribute index for the "example" partition:

Handling of the index operation is described in detail at ApacheDS tools. The index operation basically builds a new index on the st attribute within the "example" partition. This new index will not be utilized until the index for the st attribute is also configured within the server.xml file. To make use of the index add the following index configuration to the "example" partition:

Although this can be performed while the server is online without corrupting the partition it is recommended that you run this command offline. This way new entries cannot be added while you're building the index.

Memory Allocation

By default the initial and the maximum heap size for the JVM are set to 384 MB. To change this settings in Linux open the file /bin/server.init and look for the following lines:

Change the values at -Xms384m -Xmx384m to your preferences. Xms is the initial heap size, Xmx is the maximum heap size. It's recommendable to use not less than 128 MB for the initial heap size.

In Windows you can easily change the settings using the Procrun Service Manager. Open the Service Settings and go to the Java tab.

Resources

• Spring Framework 1.2.x Reference Documentation
• Short introduction to log4j