2.1 - Configuration Description

It’s a good practice to not modify the configuration LDIF file by hand, instead use the Studio Configuration plugin to modify the server configuration.

Overall structure

The configuration is stored in a hierarchical order, where sub-elements are related to their parent. For instance, the Transports are associated to the corresponding Server that uses them. Each server may contain one or more transports.

The following hierarchy describe the different kind of elements that one can configure, and their relationship :

• ou=config
  • ads-directoryServiceId=XXXXX (Directory Service)
    • ads-changeLogId=XXXXX (ChangeLog)
    • ads-journalId=XXXXX (Journal)
    • ou=interceptors (Interceptors)
      • ads-interceptorId=authenticationInterceptor (Authentication Interceptor)
        • ou=authenticators (Authenticators)
        • ou=passwordPolicies (Password Policies)
    • ou=partitions (Partitions)
      • ads-partitionId=system (JDBM Partition)
        • ou=indexes (Indexes)
          • ads-indexAttributeId=XXXXX (Indexed Attribute)
    • ou=servers (Servers)
      • ads-serverId=ldapServer (Ldap Server)
        • ou=transports (Transports)
        • ou=replConsumers (ReplConsumers)
        • ou=extendedOpHandlers (Extended Operation Handlers)
        • ou=saslMechHandlers (SASL Mechanisms)
      • ads-serverId=kerberosServer (Kerberos Server)
        • ou=transports (Transports)
      • ads-serverId=httpServer (Http Server)
        • ou=transports (Transports)
        • ou=httpWebApps (HttpWebApps)
      • ads-serverId=changePasswordServer (ChangePassword Server)
        • ou=transports (Transports)

Note that in order to modify one element, you have to go down the tree up to the entry containing the elements you want to modify. For instance, to modify the TCP port for LDAP server, you have to modify the following entry :

**ads-transportid=ldap, ou=transports, ads-serverId=ldapServer, ou=servers, ads-directoryServiceId=XXXXX, ou=config**

We will now explain each one of those elements.

Directory Service

This is the heart of the entire system : the place where we store the data. Most of the servers are depending on this component. You may have more than one server(e.g LDAP, Kerberos, ChangePassword etc), but only one DirectoryService.

Configuration options:

Change Log

The ChangeLog is an optional system that logs every change made on the server, and also records the revert operation, allowing the system to rollback the changes if needed. This is extremely useful when running tests.

Note that at the moment, changelog has in-memory support only.

It’s disabled by default.

Configuration options:

Journal

The Journal logs every modification on the file system. It’s intended to be used if the DirectoryService crashes, as we can re-apply the journal starting from a date in the past where we know that the underlying database is correct.

Configuration options:

Interceptors

The default Interceptors are generally not configurable. You don’t want to change their order, or remove anyone from the default interceptors unless you are very familiar with the internals of ApacheDS and/or including a custom interceptor.

However, at least one default Interceptor can be configured : the authenticationInterceptor.

In the case where one would like to add an interceptor, it’s enough to add the associated entry containing the interceptor identifier, under the ou=interceptors entry. It must have an order. Here are the elements that can be configured in such a case :

Authentication Interceptor

This Interceptor is in charge of managing the users authentication. It is associated with Authenticators, and with Password Policies.

Authenticators

We may have various Authenticator declared for a given server. The default server has three different Authenticators, which are :

• anonymousAuthenticator : used for anonymous requests
• simpleAuthenticator : handle simple authentication, based on a password
• strongAuthenticator : handle SASL authentication.

One can add a new Authenticator, if needed. It’s just a matter of creating a new entry under the ou=authenticators,ads-interceptorId=authenticationInterceptor,ou=interceptors entry, containing the two following elements :

Password Policies

There are many possible configurable options for the PasswordPolicy system. Here is a list of all the options. See the password policy draft for an indept explanation of the respective attributes :

Partitions

The Partition is where the server stores your data. There are many parts that need to be configured in order to obtain the best performances out of the server. It’s also the part of the configuration you are more likely to modify, adding new Partitions or adding new Indexes.

You may have more than one Partition in your DirectoryService. There are at least three default _Partition_s, ou=system, ou=config and ou=schema Partition. ou=system is a JDBM Partition and the two others are LDIF partitions.

JDBM Partition

A JDBM Partition has the following configurable options :

Once the above elements have been added, the Partition is available. You still have to create some mandatory indexes though.

Indexes

Each Partition have indexes, some are mandatory, and others are user provided. Here are the mandatory indexes :

Indexed Attribute

Indexed attributes have a type, depending on the Partition type they are associated with. Currently, we have only one type, JdbmIndex. They have specific configurable elements.

Each index attribute has four basic elements that can be configured :

The JdbmIndex type of index has some more configurable elements, all optional :

Servers

As we can see, we can start more than one server (a.k.a service). We have :

• a LDAP server
• a Kerberos server
• a changePassword server
• an HTTP Server
• a NTP Server
• a DHCP server
• a DNS server

There is a distinction though between the servers backed by a DirectoryService, and those that aren’t (like the HTTP and NTP servers).

All the DirectoryService backed servers share some common parameters, which are exposed in the following table :

A server can define more than one transports : for instance, the Kerberos server uses UDP and TCP transports.

Transports

Here are the parameters for the Transport structure :

Ldap Server

Let’s start with the main server : the LDAP server.

The list of attributes that can be modified is exposed in the following table.

(*) org.apache.directory.server.ldap.replication.provider.SyncReplRequestHandler

Repl Consumers

This part of the configuration deals with the replication. It provides all the information for a server to become a consumer. A server can have many different consumers set.

All the consumers are stored under the ou=replConsumers entry, under the respective server entry.

Here are the configurable elements :

Extended Op Handlers

An LDAP server can handle ExtendedOperations, assuming it has the code to do so. In ApacheDS, we do that by associating a Java class with each ExtendedOperation. We may provide more ExtendedOperations in the future. The list of supported ExtendedOperations is given below :

• CertGenerationRequest : Generate a certificate on demand
• GracefulShutdownRequest : Requires the server to shutdown gracefully
• StartTLSExtendedOperation : Process the StartTLS request
• StoredProcedureExtendedOperation : Execute a Stored procedure

Adding a new ExntedeOperatonHandler is just a matter of adding a new entry under the ou=extendedOpHandlers entry, with the given elements :

SASL Mechanisms

We have various SASL mechanisms, which can be configured. the list of supported SASL mechanisms is :

• CRAM-MD5
• DIGEST-MD5
• GSS-SPNEGO
• GSSAPI
• NTLM
• SIMPLE

This list is stored in the configuration. It’s possible to add new mechanisms if needed, simply by adding an entry containing those elements, under the ou=saslMechHandlers

Kerberos Server

The KerberosServer configuration is an important part of the configuration. It depends on a DirectoryService too, as most of the informations managed by a KerberosServer are store there.

The list of attributes that can be modified is exposed in the following table.

Of course, a Transport has to be defined under the KerberosServer entry (see Transports).

Http Server

We have a Http Server embedded, which is used to manage some parts of the server. One can inject a web application, which has direct access to the embedded LdapServer, for instance. It can be useful for sending LDAP requests using DSML, for instance.

There is one single element that can be configured :

An HttpServer without webApps is pretty useless, we now have to configure the underlying web applications

Http Web Apps

Each WebApp configuration must be added under the ou=webapps entry. Here are the configurable elements :

Here is an example of configuration :

dn: ads-id=webApp1,ou=httpWebApps,ads-serverId=httpServer,ou=servers,ads-directoryServiceId=default,ou=config
objectclass: top
objectclass: ads-base
objectclass: ads-httpWebApp
ads-Id: webApp1
ads-httpWarFile: war file 1
ads-httpAppCtxPath: /home/app1

Change Password Server

To be added…

Bean graph

The following picture represent the structure of the container used to store the configuration inside the server. The yellow beans are abstract beans, extended by specific beans.

The bold links mean we can have more than one instance of a bean.