1.4.3 - Adding your own partition

1.4 - Basic configuration tasks

1.4.5 - Enable and disable anonymous access

1.4.4 - Configure logging

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.

ApacheDS and logging

ApacheDS 2.0 uses SLF4J as its logging solution. This is a simple facade for various logging APIs. The default for ApacheDS 2.0 is log4j.

Default behavior after installation

By default, ApacheDS writes log files in the directory <APACHEDS_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, which is located in <APACHEDS_HOME>/conf/, looks like. The name of the RollingFileAppender is “R”:

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 inundated 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

In this file “R” is configured like this:

Property name	Value in file above	Meaning
File	apacheds-rolling.log	Path to the output log file, in our case relative to var/log
MaxFileSize	1024KB	Maximum size that the output file is allowed to reach before being rolled over to backup files
MaxBackupIndex	5	Number of backup files kept
layout.ConversionPattern	[%d{HH:mm:ss}] %p [%c] - %m%n	Format string for logging events

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:

$DAEMON_HOME/apacheds \
...
-outfile $SERVER_HOME/var/log/apacheds-stdout.log \
-errfile $SERVER_HOME/var/log/apacheds-stderr.log \
...    
$APACHEDS_HOME start

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:

Level	Description from log4j documentation
DEBUG	Designates fine-grained informational events that are most useful to debug an application
INFO	Designates informational messages that highlight the progress of the application at coarse-grained level
WARN	Designates potentially harmful situations
ERROR	Designates error events that might still allow the application to continue running
FATAL	Designates very severe error events that will presumably lead the application to abort

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 file. The easiest way to get finer log messages is to change it like this

log4j.rootCategory=DEBUG, stdout, R
...

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:

...
# with these we'll not get inundated 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

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

...
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
...

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

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

The pattern uses the following conversion characters:

Character	Output
%d	Date of the logging event in the given format. like “12:29:05” for %d{HH:mm:ss}
%p	Priority (level) of the logging event, like “INFO” or “WARN”
%c	Category of the logging event, like “org.apache.directory.server.Service”
%m	Application supplied message associated with the logging event
%n	Platform dependent line separator

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

log4j.appender.R.layout.ConversionPattern=[%d{dd.MM.yyyy HH:mm:ss}] %p: %c{1}.%M() - %m%n

leads to messages of this form:

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

** Warning**

“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)

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.

Example configurations

The following example could be used to log all incoming search, add, delete, modify and moddn requests:

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

Log settings of the Windows service

To run as a Windows service, the ApacheDS Java classes must be executed within a Windows native binary. The ApacheDS project relies on the Tanuki Software Java Service Wrapper’s wrapper.exe to manage the ApacheDS Java Virtual Machine (JVM) process. While the ApacheDS Java code’s logging is log4j-based, the wrapper.exe Windows service has its own logging configuration. For example, the wrapper.conf log settings govern the destination of the JVM’s stdout and stderr logging and the logging of the communication between the wrapper.exe Windows service container and the JVM it hosts.

An ApacheDS installation’s wrapper.exe log settings are stored in:

C:\Program Files (x86)\ApacheDS\conf\wrapper.conf.

The Tanuki Software Java Service Wrapper web site documents all configuration settings for wrapper.exe including logging:

https://wrapper.tanukisoftware.com/doc/english/introduction.html#logging

Resources

Short introduction to log4j