title: 2.1 - Configuration Description navPrev: 2-server-config.html navPrevText: 2 - Server Configuration navUp: 2-server-config.html navUpText: 2 - Server Configuration navNext: 2.2-instance-layout.html navNextText: 2.2 - Instance Layout

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 :

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:

AttributeTypetypedefault valueDescription
ads-directoryServiceIdStringThe unique identifier for the service
ads-enabledbooleantrueTells if the DirectoryService is enabled
descriptionStringN/AA short optional description
ads-dsReplicaIdint1The replication identifier
ads-dsAccessControlEnabledbooleantrueTells if the Access Control interceptor is active
ads-dsAllowAnonymousAccessbooleanfalseTells if the service allow anonymous access
ads-dsDenormalizeOpAttrsEnabledbooleantrueTells if the service should denormalize operational attributes
ads-dsPasswordHiddenbooleantrueTells if the passwords should be encrypted (not used)
ads-dsSyncPeriodMillislong15000The delay in milliseconds before we flush data on disk
ads-dsTestEntriesStringN/ANot used

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:

AttributeTypetypedefault valueDescription
ads-changeLogIdStringThe unique identifier for the system
ads-enabledbooleanfalseTells if the ChangeLog system is enabled
descriptionStringN/AA short optional description
ads-changeLogExposedbooleanfalseTells if the ChangeLog is exposed to the users

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:

AttributeTypetypedefault valueDescription
ads-journalIdStringN/AThe unique identifier for the Journal
ads-enabledbooleanfalseTells if the Journal system is enabled
descriptionStringN/AA short optional description
ads-journalWorkingDirStringN/AThe working directory the Journal will be stored in
ads-journalRotationStringN/AThe number of operation stored befoe the journal is rotated
ads-journalFileNameStringjournal.txtThe file contaning the Journal

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 :

AttributeTypetypedefault valueDescription
ads-interceptoridStringN/AThe unique identifier for this Interceptor
ads-enabledbooleanfalseTells if the Interceptor is enabled
descriptionStringN/AA short optional description
ads-interceptororderintN/AThe position in the chain for this interceptor
ads-interceptorclassnameStringN/AThe class implementing this interceptor

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 :

AttributeTypetypedefault valueDescription
ads-authenticatorIdStringN/AThe unique identifier for this Authenticator
ads-enabledbooleanfalseTells if the Partition is enabled
descriptionStringN/AA short optional description
ads-authenticatorClassStringN/AThe FQCN for the class implementing the AUthenticator

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 :

AttributeTypetypedefault valueDescription
ads-pwdIdStringN/AThe unique ID of the PasswordPolicy system
ads-pwdAttributeStringuserPasswordThe name of the attribute to which the password policy is applied
ads-pwdMinAgeint0Holds the number of seconds that must elapse between modifications to the password
ads-pwdMaxAgeint0Holds the number of seconds after which a modified password will expire. If 0, never expires
ads-pwdInHistoryboolean0Specifies the maximum number of used passwords stored in the pwdHistory attribute (0 means no storage)
ads-pwdCheckQualityboolean0Indicates how the password quality will be verified while being modified or added (0 means no check)
ads-pwdMinLengthint0The minimum number of characters that must be used in a password (0 means no limit)
ads-pwdMaxLengthint0The maximum number of characters that may be used in a password (0 means no limit)
ads-pwdExpireWarningboolean0The maximum number of seconds before a password is due to expire, and that expiration warning messages will be returned to an authenticating user (0 means no message wil be sent to user)
ads-pwdGraceAuthNLimitint0The number of times an expired password can be used to authenticate (0 means do not allow a expired password for authentication)
ads-pwdGraceExpireboolean0Specifies the number of seconds the grace authentications are valid (0 means no limit)
ads-pwdLockoutbooleanfalseFlag to indicate if the account needs to be locked after a specified number of
consecutive failed bind attempts. The maximum number of consecutive failed bind attempts is specified in ads-pwdMaxFailure
ads-pwdLockoutDurationint300The number of seconds that the password cannot be used to authenticate due to too many failed bind attempts
ads-pwdMaxFailureint0The number of consecutive failed bind attempts after which the password may not be used to authenticate (0 means no limit)
ads-pwdFailureCountIntervalint0The number of seconds after which the password failures are purged from the failure counter (0 means reset all the pwdFailureTimes after a successful authentication)
ads-pwdMustChangebooleanfalseFlag to indicate if the password must be changed by the user after they bind to the directory after a password is set or reset by a password administrator
ads-pwdAllowUserChangebooleantrueIndicates whether users can change their own passwords
ads-pwdSafeModifybooleanfalseFlag to specify whether or not the existing password must be sent along with the new password when being changed
ads-pwdMinDelayint0The number of seconds to delay responding to the first failed authentication attempt (0 means no delay)
ads-pwdMaxDelayint0The maximum number of seconds to delay when responding to a failed authentication attempt (no delay) 0 means
ads-pwdMaxIdleint0The number of seconds an account may remain unused before it becomes locked (0 means infinite)
ads-pwdValidatorStringN/AThe PasswordValidator FQCN (will use DefaultPasswordValidator if not provided)

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 :

AttributeTypetypedefault valueDescription
ads-partitionidStringN/AThe unique identifier for this Partition
ads-enabledbooleanfalseTells if the Partition is enabled
descriptionStringN/AA short optional description
ads-partitionsuffixStringN/AThe partition DN
ads-contextEntryStringN/AThe entry associated with the suffix (in LDIF format)
ads-partitionSyncOnWritebooleantrueTells the server to flush on disk on each write

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 :

Indexrole
apacheRdnStores the RDN for the entry, and the relation to its parent's RDN
apachePresenceUsed to index the attributeTypes used in the entry
apacheOneAliasStores the aliases one level below the current entry
apacheSubAliasStores the aliases below the current entry
apacheAliasStores the aliases
objectClassStores the relation between an ObjectClass an the entry using it
entryCSNStores the CSN for each entry
administrativeRoleStores the entries that are AdminstrativePoints
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 :

AttributeTypetypedefault valueDescription
ads-indexAttributeIdStringN/AThe unique identifier for this indexedAttribute
ads-enabledbooleanfalseTells if the IntexedAttribute is enabled
descriptionStringN/AA short optional description
ads-indexHasReversebooleanfalseTells if the IndexedAttribute has a reverse index

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

AttributeTypetypedefault valueDescription
ads-indexFileNameStringN/AThe index file name (default to the associated attributeType name)
ads-indexWorkingDirStringN/AThe index working directory
ads-indexNumDupLimitint512The maximum number of values for a single key before we use a sub-tree
ads-indexCacheSizeint100The number of cached pages for this index

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 :

AttributeTypetypedefault valueDescription
ads-searchBaseDNDnN/AThe place were to start looking for authentication informations
ads-serverIdStringN/AThe server unique name
ads-enabledbooleanN/ATells if the Server is enabled
descriptionStringN/AA short optional description

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 :

AttributeTypetypedefault valueDescription
ads-transportIdStringN/AThe identification
ads-transportAddressStringlocalhostThe IP Address
ads-systemPortint-1The port
ads-enabledbooleanN/ATells if the Transport system is enabled
descriptionStringN/AA short optional description
ads-transportEnableSslbooleanfalseTells if SSL is activated (not used for UDP)
ads-transportNbThreadsint3he number of dedicated threads to process the messages
ads-transportBackLogint50The number of messages on hold if the server is overloaded (not used for UDP)

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.

AttributeTypetypedefault valueDescription
ads-enabledbooleantrueTells if the LdapServer system is enabled
descriptionStringN/AA short optional description
ads-confidentialityRequiredbooleanfalseWhether or not confidentiality (TLS secured connection) is required
ads-maxSizeLimitint1000The maximum number of entries the server will return
ads-maxTimeLimitint1000The maximum number of seconds the server will use to process a search request
ads-maxPDUSizeint2048The maximal size for a PDU. This is currently not leveraged
ads-saslHostintN/AThe name of this host, validated during SASL negotiation
ads-saslPrincipalStringN/AThe service principal, used by GSSAPI.
sads-saslRealmsListN/AThe list of realms serviced by this host.
ads-keystoreFileStringN/AThe place on the filesystem where the Keystore is stored
ads-certificatePasswordStringN/AThe certificate's password
ads-replReqHandlerString(*)The replication request handler FQCN
ads-replEnabledbooleanFALSETells if the replication system is enabled

(*) 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 :

AttributeTypetypedefault valueDescription
ads-replConsumerIdStringN/AThe replica unique identifier
ads-searchBaseDNStringN/AThe base DN for replication
ads-replProvHostNameStringN/AThe provider host name
ads-replProvPortint389The port of the remote server
ads-replAliasDerefModeStringNEVER_DEREF_ALIASESThe alias dereferencing mode to use
ads-replAttributesString*The list of attributes to get back
ads-replRefreshIntervalint60000The delay between refreshes (60 seconds)
ads-replRefreshNPersistbooleantrueSets the replication mode
ads-replSearchScopeStringSUBTREEThe scope to use while searching for entries
ads-replSearchFilterString(objectClass=*)The filter to use
ads-replSearchSizeLimitint0The maximum number of entries to get back
ads-replSearchTimeOutint0The maximum time to wait while fetching the entries
ads-replUserDnStringN/AThe user DN used to bind on the provider
ads-replUserPasswordStringN/AThe password of the user
ads-replUseTlsbooleantrueTells the server to use startTLS during replication
ads-replStrictCertValidationbooleantrueTells the provider to check the certificate if provided
ads-replPeerCertificatebyte[]N/AThe certificate to use for replication
ads-replConsumerImplStringReplicationConsumerImplThe implementation
ads-replCookiebyte[]N/AThe last received cookie

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 :

AttributeTypetypedefault valueDescription
ads-enabledbooleantrueTells if the ExtendedOpHandler system is enabled
descriptionStringN/AA short optional description
ads-extendedOpIdStringN/AThe ExtendedOpHandler unique identifier
ads-extendedOpHandlerClassStringN/AThe class FQCN that implements the handler

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

AttributeTypetypedefault valueDescription
ads-enabledbooleantrueTells if the Transport system is enabled
descriptionStringN/AA short optional description
ads-saslMechNameStringThe mechanism name
ads-saslMechClassNameStringN/AThe mechanism class name
ads-ntlmMechProviderStringN/AThe NTLM provider

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.

AttributeTypetypedefault valueDescription
ads-enabledbooleantrueTells if the KerberosServer is enabled
descriptionStringN/AA short optional description
ads-krbAllowableClockSkewint300000The allowable clock skew in milliseconds (5 minutes)
ads-krbEncryptionTypesListThe encryption types
ads-krbEmptyAddressesAllowedbooleantrueWhether empty addresses are allowed
ads-krbForwardableAllowedbooleantrueWhether forwardable addresses are allowed
ads-krbPaEncTimestampRequiredbooleantrueWhether pre-authentication by encrypted timestamp is required
ads-krbPostdatedAllowedbooleantrueWhether postdated tickets are allowed
ads-krbProxiableAllowedbooleantrueWhether proxiable addresses are allowed
ads-krbRenewableAllowedbooleantrueWhether renewable tickets are allowed
ads-krbKdcPrincipalStringkrbtgt/EXAMPLE.COM@EXAMPLE.COMThe service principal name
ads-krbMaximumRenewableLifetimelong1000 * 60 * 60 * 24 * 7The maximum renewable lifetime in millisconds (7 days)
ads-krbMaximumTicketLifetimelong1000 * 60 * 60 * 24he maximum ticket lifetime in milliseconds (24 h)
ads-krbPrimaryRealmStringEXAMPLE.COMThe primary realm
ads-krbBodyChecksumVerifiedbooleantrueWhether to verify the body checksum

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 :

AttributeTypetypedefault valueDescription
ads-enabledbooleantrueTells if the HttpServer is enabled
descriptionStringN/AA short optional description
ads-httpConfFileStringN/AThe configuration file for this server

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 :

AttributeTypetypedefault valueDescription
ads-enabledbooleantrueTells if the HttpServer is enabled
descriptionStringN/AA short optional description
ads-httpWarFileStringN/AThe WAR file to use
ads-idStringN/AThe unique ID for this WebApp
ads-httpAppCtxPathStringN/AThe context

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.

ApacheDS configuration beans