Configuration Parameters Reference

Work in progress

This page lists all configuration parameters which can be used in conf/server.xml in Version 1.5.1. For a more detailed description look at the corresponding section in the Advanced User's Guide.

Environment parameters

Those parameters are loaded in the org.apache.directory.server.Service.java class, when the server is started, in the init method :

public void init( InstallationLayout install, String[] args ) throws Exception
    {
        ...

        if ( install != null )
        {
            log.info( "server: loading settings from ", install.getConfigurationFile() );
            ...
            env = ( Properties ) factory.getBean( "environment" );
        ...

They are used everywhere in the server.
The "environment" bean is read from the Spring configuration file, server.xml, shown below :

<bean id="environment" class="org.springframework.beans.factory.config.PropertiesFactoryBean">
    <property name="properties">
      <props>
        <!-- JNDI security properties used to get initial contexts.         -->
        <prop key="java.naming.security.authentication">simple</prop>
        <prop key="java.naming.security.principal">uid=admin,ou=system</prop>
        <prop key="java.naming.security.credentials">secret</prop>
        <!--
        <prop key="java.naming.ldap.attributes.binary"></prop>
        -->
      </props>
    </property>
  </bean>

The bean name ("environement") may be renamed to something more explicit, like "serverEnvironment", IMHO

Parameter Default value Description Comment
java.naming.security.authentication simple The kind of authentication used for the admin. Shouldn't it be SASL now ?
java.naming.security.principal uid=admin,ou=system The admin DN Can be changed to another DN
java.naming.security.credentials secret The principal password must be changed at startup!!!
java.naming.ldap.attributes.binary empty The list of binary attributes In LDAP, only a few AT are declared as binary.
This is were we should describe the other ones

The admin password should be changed when the server is started. A good thing would be that the server cannot start if this password is kept as is.

Protocol providers

Parameters common to all protocol providers

Since all protocol provider Configuration beans inherit from the same ServiceConfiguration, they share many of the same configuration parameters.

Parameter Default value Description
enabled false Whether this service is enabled.
ipPort No default. The IP port for this service.
ipAddress No default. The IP address for this service.
searchBaseDn "ou=users,ou=system" The single location where users that can be SASL authenticated are stored. <to be clarified>The definition of "entries" depends on the protocol. For example, for LDAP, Kerberos, and Change Password, entries are users for purposes of authentication. For DNS, entries are resource records. If this property is not set the store will search the system partition configuration for catalog entries. Catalog support is highly experimental and is only tested in the OSGi build of ApacheDS using the Config Admin service.<to be clarified/>
recent inclusion

This last parameter has been included with the last SASL addition. The description is not giving a lot of information about what is this parameter about, except for SASL authentication. The parameter name is not significant, and another one should be selected, IMHO.

Can soemone elaborate what this parameter is about ?

Parameter Default value Description
initialContextFactory "org.apache.directory.server.core.jndi.CoreContextFactory" The JNDI initial context factory to use.
securityAuthentication "simple" The authentication mechanism to use for establishing a JNDI context.
securityPrincipal "uid=admin,ou=system" The principal to use for establishing a JNDI context.
securityCredentials "secret" The credentials to use for establishing a JNDI context.
serviceName No default. The friendly name of this service.
servicePid No default. The PID for this service. A PID is a unique identifier for an instance of a service. PID's are used by OSGi's Config Admin service to dynamically inject configuration into a service when the service is started.
bufferSize No default. The MINA buffer size for this service.
catalogBaseDn No default. The single location where catalog entries are stored. A catalog entry is a mapping of a realm (or zone for DNS) to a search base DN. If this property is not set the store will expect a single search base DN to be set. Catalog support is highly experimental and is only tested in the OSGi build of ApacheDS using the Config Admin service.

It would be good to have more insight about catalogs.

LDAP-Specific Configuration Parameters

We have had a lot of modification in this part. Some of them are really going in the right direction, some other needs to be tuned.
First, all the previous configuration has been moved from the common part to a specific LdapConfiguration part : that is a good move
Second, we now have a new configuration called "ldapsConfiguration", but I'm afraid that some informations are missing.
Third, I don't know if we should have only one configuration called "ldapConfiguration", or three ("ldapConfiguration", "ldapsConfiguration" and" ldapSASLConfiguration". Atm, we have two.

Here is the latest version of the ldap configuration :

  <bean id="ldapConfiguration" class="org.apache.directory.server.ldap.LdapConfiguration">
    <!-- The port to run the LDAP protocol on.                              -->
    <property name="ipPort" value="10389" />

    <!-- Whether to allow anonymous access.                                 -->
    <property name="allowAnonymousAccess" value="false" />
    
    <!-- The list of supported authentication mechanisms.                   -->
    <property name="supportedMechanisms">
      <list>
        <value>SIMPLE</value>
        <value>CRAM-MD5</value>
        <value>DIGEST-MD5</value>
        <!--<value>GSSAPI</value>-->
      </list>
    </property>
    
    <!-- The FQDN of this SASL host, validated during SASL negotiation.     -->
    <property name="saslHost" value="ldap.example.com" />
    
    <!-- The Kerberos principal name for this LDAP service, used by GSSAPI. -->
    <property name="saslPrincipal" value="ldap/ldap.example.com@EXAMPLE.COM" />
    
    <!-- The desired quality-of-protection, used by DIGEST-MD5 and GSSAPI.  -->
    <property name="saslQop">
      <list>
        <value>auth</value>
        <value>auth-int</value>
        <value>auth-conf</value>
      </list>
    </property>
    
    <!-- The realms serviced by this SASL host, used by DIGEST-MD5 and GSSAPI. -->
    <property name="saslRealms">
      <list>
        <value>example.com</value>
        <value>apache.org</value>
      </list>
    </property>
    
    <!-- The base DN containing users that can be SASL authenticated.       -->
    <property name="searchBaseDn" value="ou=users,ou=system" />
    
    <!-- SSL CONFIG CAN GO HERE-->
    
    <!-- limits searches by non-admin users to a max time of 15000          -->
    <!-- milliseconds and has a default value of 10000                      -->
    <property name="maxTimeLimit" value="15000" />

    <!-- limits searches to max size of 1000 entries: default value is 100  -->
    <property name="maxSizeLimit" value="1000" />

    <!-- the collection of extended operation handlers to install           -->
    <property name="extendedOperationHandlers">
      <list>
        <!--<bean class="org.apache.directory.server.ldap.support.starttls.StartTlsHandler"/>-->
        <bean class="org.apache.directory.server.ldap.support.extended.GracefulShutdownHandler"/>

        <bean class="org.apache.directory.server.ldap.support.extended.LaunchDiagnosticUiHandler"/>
      </list>
    </property>
  </bean>
Parameter Default value Description Comments
ipPort 10389 The IP port used by the ldap server We are using a port above 1024 to allow non root users to launch the server
allowAnonymousAccess false Whether to allow anonymous access Was true in the previous version.
supportedMechanisms SIMPLE, CRAM-MD5, DIGEST-MD5 The supported authentication mechanisms. The GSSAPI mechanism has been temporarilly disabled

We have to figure out if we should reactivate this GSSAPI configuration, or not. Not a simple matter, right now. If SASL is to be moved to another configuration, then maybe it should be activated as a default value. TO BE DISCUSSED...

Parameter Default value Description Comments
saslHost ldap.example.com The name of this host, validated during SASL negotiation. The host name must be selected with great caution
saslPrincipal ldap/ldap.example.com@EXAMPLE.COM The service principal, used by GSSAPI.
saslQop auth, auth-int, auth-conf The quality of protection (QoP), used by DIGEST-MD5 and GSSAPI.
saslRealms example.com The list of realms serviced by this host.
maxSizeLimit 100 The maximum size limit.
maxTimeLimit 10000 The maximum time limit.
enableLdaps false Whether LDAPS is enabled.
ldapsCertificateFile server-work/certificates/server.cert The path to the certificate file.
ldapsCertificatePassword changeit The certificate password.
extendedOperationHandlers No default. The extended operation handlers.

Kerberos-Specific Configuration Parameters

<bean id="kdcConfiguration" class="org.apache.directory.server.kerberos.kdc.KdcConfiguration">
    <!-- Whether to enable the Kerberos protocol.                           -->
    <property name="enabled" value="false" />
    <!-- The port to run the Kerberos protocol on.                          -->
    <property name="ipPort" value="88" />
  </bean>
Parameter Default value Description
encryptionTypes des-cbc-md5 The encryption types.
primaryRealm EXAMPLE.COM The primary realm.
servicePrincipal krbtgt/EXAMPLE.COM@EXAMPLE.COM The service principal name.
allowableClockSkew 5 minutes The allowable clock skew.
paEncTimestampRequired true Whether pre-authentication by encrypted timestamp is required.
maximumTicketLifetime 1440 (24 hours) The maximum ticket lifetime.
maximumRenewableLifetime 10080 (1 week) The maximum renewable lifetime.
emptyAddressesAllowed true Whether ticket issuance for empty Host Addresses is allowed.
forwardableAllowed true Whether forwardable tickets are allowed.
proxiableAllowed true Whether proxiable tickets are allowed.
postdateAllowed true Whether postdated tickets are allowed.
renewableAllowed true Whether renewable tickets are allowed.

Change Password-Specific Configuration Parameters

<bean id="changePasswordConfiguration" class="org.apache.directory.server.changepw.ChangePasswordConfiguration">
    <!-- Whether to enable the Change Password protocol.                    -->
    <property name="enabled" value="false" />
    <!-- The port to run the Change Password protocol on.                   -->
    <property name="ipPort" value="464" />
  </bean>
Parameter Default value Description
encryptionTypes des-cbc-md5 The encryption types.
primaryRealm EXAMPLE.COM The primary realm.
servicePrincipal kadmin/changepw@EXAMPLE.COM The service principal name.
allowableClockSkew 5 minutes The allowable clock skew.
emptyAddressesAllowed true Whether tickets issued with empty Host Addresses are allowed.
policyPasswordLength 6 characters The policy for minimum password length.
policyCategoryCount 3 (out of 4) The policy for number of character categories required (A - Z), (a - z), (0 - 9), non-alphanumeric (!, $, #, %, ... ).
policyTokenSize 3 characters The policy for minimum token size. Passwords must not contain tokens larger than 'policyTokenSize' that occur in the user's principal name.

NTP-Specific configuration parameters

The NTP parameters are very limited :

<bean id="ntpConfiguration" class="org.apache.directory.server.ntp.NtpConfiguration">
    <!-- Whether to enable the NTP protocol.                                -->
    <property name="enabled" value="true" />

    <!-- The port to run the NTP protocol on.                               -->
    <property name="ipPort" value="123" />
  </bean>

Here is the table containing the default configuration :

Parameter Default value Description Comments
enabled true Tells if the service is on or off Should be OFF by default
ipPort 123 The default port

Just wanted to know if the UDP and TCP should be enabled or if the server just accept TCP ?

DHCP-Specific configuration parameters

There is no description about DHCP parameters atm.

Server Startup Configuration

Replication

<bean class="org.apache.directory.server.core.configuration.MutableInterceptorConfiguration">
          <property name="name" value="replicationService" />
          <property name="interceptor">
            <bean class="org.apache.directory.mitosis.service.ReplicationService">
              <property name="configuration">
                <bean class="org.apache.directory.mitosis.configuration.ReplicationConfiguration">
                  <property name="replicaId">
                    <bean class="org.apache.directory.mitosis.common.ReplicaId">
                      <constructor-arg>
                        <value>instance_a</value>
                      </constructor-arg>
                    </bean>
                  </property>
                  <property name="serverPort" value="10390" />
                  <property name="peerReplicas" value="instance_b@localhost:10392" />
                </bean>
              </property>
            </bean>
          </property>
        </bean>
Parameter Default value Description

Partition Configuration