2 - Server Configuraion

We will now describe the server configuration. Usually, all the configuration is done using Apache Directory Studio, which offers a pretty GUI. One can also configure the server using LDAP request, as the configuration is stored in teh DIT. Otherwise, all the configuration modifications won't be applied on a started server : usually, you will have to restart the server in order to get those modifications applied.

It's a good policy not to modify the LDIF files by hand, but instead to use the Studio Configuration plugin to modify your 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 Server they are child of. If we have many kind of servers, we will have as many transports as we have servers.

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, 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 key of the whole server : the place where we store the data. Most of the servers are depending on this component. You maye have more than one server, but only one DirectoryService. This compoent itself refers to the servers that will be started, plus the backends it will depends on.

Here are the configuration parameters for this components :

Change Log

The ChangeLog is an optional system that logs every changes 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, the system works in memory.

It's disabled by default.

Here are the configuration element for the ChangeLog elements :

Journal

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

The configuration elements for the Journal are :

Interceptors

The Interceptors are generally not configurable. You don't want to change their order, nor remove or add some. The fact that they appear in the configuration is because we use this to initialize the server.

However, at least one Interceptor can be confiured : 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 taht 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 possible elements :

Partitions

The Partition is the part of the server storing 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 configuraton you are the more likely to modify, adding new Partitions or adding new Indexes.

You may have more than one Partition in your DirectoryService. We have at least three existing Partition, the ou=system Partition, the ou=config Partition and the ou=schema Partition. The former is a JDBM Partition, when the two others are LDIF _Partitions.

JDBM Partition

A JDBM Partition have the following configurable elements :

Once those elements have been configured, 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

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

Each index attribute have 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. 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 stord under the ou=replConsumers entry, under the respectiver 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 mechnaism if needed, smply by adding an entry containg those elements, under the ou=saslMechHandlers

Kerberos Server

The KerberosServer configuration is an important part of the configuration. It deoends 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 underlaying 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...