From commits-return-20943-apmail-directory-commits-archive=directory.apache.org@directory.apache.org Thu Jan 29 18:44:37 2009 Return-Path: Delivered-To: apmail-directory-commits-archive@www.apache.org Received: (qmail 45445 invoked from network); 29 Jan 2009 18:44:37 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 29 Jan 2009 18:44:37 -0000 Received: (qmail 48113 invoked by uid 500); 29 Jan 2009 18:44:37 -0000 Delivered-To: apmail-directory-commits-archive@directory.apache.org Received: (qmail 48077 invoked by uid 500); 29 Jan 2009 18:44:37 -0000 Mailing-List: contact commits-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@directory.apache.org Delivered-To: mailing list commits@directory.apache.org Received: (qmail 48068 invoked by uid 99); 29 Jan 2009 18:44:36 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 29 Jan 2009 10:44:36 -0800 X-ASF-Spam-Status: No, hits=-1994.1 required=10.0 tests=ALL_TRUSTED,HTML_MESSAGE,MIME_HTML_ONLY,OBFUSCATING_COMMENT X-Spam-Check-By: apache.org Received: from [140.211.11.140] (HELO brutus.apache.org) (140.211.11.140) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 29 Jan 2009 18:44:23 +0000 Received: from brutus (localhost [127.0.0.1]) by brutus.apache.org (Postfix) with ESMTP id 0C170234C4AB for ; Thu, 29 Jan 2009 10:44:00 -0800 (PST) Message-ID: <355444340.1233254640041.JavaMail.www-data@brutus> Date: Thu, 29 Jan 2009 10:44:00 -0800 (PST) From: confluence@apache.org To: commits@directory.apache.org Subject: [CONF] Apache Directory Server v1.5: 1.4.1 Configuration of ApacheDS with Spring (page edited) MIME-Version: 1.0 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Virus-Checked: Checked by ClamAV on apache.org
Page Edited : DIRxSRVx11 : 1.4.1 Configuration of Apach= eDS with Spring

1.4.1 Configuration of ApacheDS = with Spring has been edited by Emmanuel L=C3=83=C2=A9charny (Jan 29, 2009).

=20

(View changes)

Content:
 1.4. Ba= sic configuration tasks 1.4.2 Changing the server port for LDAP

Configuration of ApacheDS with Spring

This section describes the overall structure of the server configuration= , which uses Spring.

ApacheDS and Spring

There are several options to configure ApacheDS. For instance you can pr= actically do everything programmatically if you embed the server in a Java = component.

For this guide we assume a standard installation of ApacheDS run standal= one, and the default mechanism to configure this deployment option is (in a= lmost all cases) changing the file server.xml, which is located in= the conf directory of your ApacheDS instance. The file is compose= d of bean definitions, because configuration in ApacheDS 1.5 is done with t= he help of the Spring Framework3D"".

Despite the fact that the default server.xml shipped with the p= roduct is somewhat long, a quick look with the help of the Spring IDE3D"" displays that the structure is rather simple:

Most configuration tasks can be accomplished by modifying the properties= of existing bean definitions, or (e.g. for a new partition) by adding new = beans of certain types and wiring them to the configuration.

Note that the picture above does not show all properties available in th= e configuration. Only those are visible for which the default server.xm= l contains a value. There are more, and in case of absence the default= value is chosen. Feel free to browse the file to get an impression about f= urther options – several other features controlled by properties are = commented out.

Using Apache Directory Studio for configuration<= /h2>

Future versions of Directory S= tudio3D""= will support creation and manipulations of these configur= ations files. Stay tuned.

ApacheDS configurable parameters

Apache Directory Server has many different configuration parameters. Thi= s page summarize all the possible parameters, and what are the default valu= es for all of them.

The global structure is given here :

Int= erceptors

We have currently 16 possible interceptors we can use in the server. It'= s important to understand that some of them are mandatory, and other can be= activated or disabled. The interceptors order is also very important : mos= t of them can't be moved up or down, without severely impact the server beh= aviour.

Here is the list of the mandatory interceptors, and the order in which t= hey should appears in the configuration file :

Interceptor Mandatory Order
AciAuthorizationInterceptor Yes 4
AuthenticationInterceptor Yes 2
ChangeLogInterceptor No 7
CollectiveAttributeInterceptor Yes 13
DefaultAuthorizationInterceptor Yes 5
EventInterceptor Yes 14
ExceptionInterceptor Yes 6
KeyDerivationInterceptor No 10
NormalizationInterceptor Yes 1
OperationalAttributeInterceptor Yes 8
PasswordPolicyInterceptor No 9
ReferralInterceptor Yes 3
ReplicationInterceptor No 16
SchemaInterceptor Yes 11
SubentryInterceptor Yes 12
TriggerInterceptor No 15

The following table represents the same interceptor in the order they mu= st appear :

Interceptor Mandatory
NormalizationInterceptor Yes
AuthenticationInterceptor Yes
ReferralInterceptor Yes
AciAuthorizationInterceptor Yes
DefaultAuthorizationInterceptor Yes
ExceptionInterceptor Yes
ChangeLogInterceptor No
OperationalAttributeInterceptor Yes
PasswordPolicyInterceptor No
KeyDerivationInterceptor No
SchemaInterceptor Yes
SubentryInterceptor Yes
CollectiveAttributeInterceptor Yes
EventInterceptor Yes
TriggerInterceptor No
ReplicationInterceptor No

Interceptor without any parameters

Most of all the interceptors don't take any paramter. The only possible = configuration is to enable or disable them, simply by adding or removing th= em from the list of interceptors. Here is the list of those interceptors :<= /p>

    =09
  • AciAuthorizationInterceptor
    • =09
  • AuthenticationInterceptor
    • =09
  • ChangeLogInterceptor
    • =09
  • CollectiveAttributeInterceptor
    • =09
  • DefaultAuthorizationInterceptor
    • =09
  • EventInterceptor
    • =09
  • ExceptionInterceptor
    • =09
  • KeyDerivationInterceptor
    • =09
  • NormalizationInterceptor
    • =09
  • OperationalAttributeInterceptor
    • =09
  • PasswordPolicyInterceptor
    • =09
  • ReferralInterceptor
    • =09
  • SchemaInterceptor
    • =09
  • SubentryInterceptor
    • =09
  • TriggerInterceptor

Here is an example of configuration where the aciAuthorizationInterce= ptor is enabled :

<defaultDirectoryService ...
    ...
    <interceptors>
      ...
      <aciAuthorizationInterceptor/>
      ...

AuthenticationInterceptor :

Set<Authenticator> : The list of supported Authenticators.= Currently, we have Anonymous, Simple and Strong authe= nticators. We can just list the associated beans in the server.xml file. He= re is a sample of such a configuration :

<defaultDirectoryService ...
    ...
    <interceptors>
      ...
      <authenticationInterceptor>
        <s:property name=3D"authenticators">
          <s:set>
            <!-- Define a new Simple=
 authenticator with a cache of 50 elements -->
            <s:bean id=3D"simpleAuthenticator=
"
                    class=3D"org.apache.director=
y.server.core.authn.SimpleAuthenticator">
              <s:constructor-arg value=3D"50"=
/>
            </s:bean>

            <!-- Define a Strong authenticator -->
            <s:bean id=3D"strongAuthenticator=
"
                    class=3D"org.apache.director=
y.server.core.authn.StrongAuthenticator"/>
          </s:set>
        </s:property>
      </authenticationInterceptor>
      ...

The possible values are : AnonymousAuthenticator, SimpleAuthen= ticator and StrongAuthenticator, out of which the SimpleAuthe= nticator has a possible parameter, the cache size (an integer va= lue)

ReplicationInterceptor

This interceptor manage the replication. It has many parameters, most o= f them being defined in a specific clas : ReplicationConfiguration. Let's d= escribe those parameters.

Each instance has a name, which allows multiple instances of the server= to be present on the same machine, but with possible replication between t= hem.

First, let see an example :

<defaultDirectoryService ...
    ...
    <replicationInterceptor>
      <configuration>
        <replicationConfiguration logMaxAge=3D"5"
                                  replicaId=3D"i=
nstance_a"
                                  replicationInterval=3D"2"
                                  responseTimeout=3D"10"
                                  serverPort=3D"=
10390">
          <s:property name=3D"peerReplicas">
            <s:set>
              <s:value>instance_b@localhost:1234</s:value>
              <s:value>instance_c@localhost:1234</s:value>
            </s:set>
          </s:property>
        </replicationConfiguration>
      </configuration>
    </replicationInterceptor>
    ...

Here, we have set 2 replicas (instance B and C), the current instance is= listening on port 10390, and we have modified the default values for lo= gMaxAge, replicationInterval and responseTimeout.

The ReplicationConfiguration bean contains those parameters :

Name Type Default value Description
logMaxAge int 7 Maximum days of change logs stored
replicaId String none ID of the replica
replicationInterval int 5 Replication data exchange interval (seconds) be= tween two replicas
responseTimeout int 60 response timeout value (seconds) for each sent = message
during the communication between replicas.
serverPort int 7846 TCP/IP port number that the interceptor listens= to
peerReplicas Set<String> none The remote peer replica list

The peerReplicas parameter is a composite one.

This is the list of remote replicas. Each replica is defined by a name, = a host address and a port. The syntax must be :
<replicaid>@<host>:<port>, like ServerAAA@10.1.2.7:1234.<= /p>

Partit= ion

The ADS server can support more than one kind of Partition, but the defa= ult is to use JDBM. Here is the associated configuration for this underlyin= g partition.

Jd= bmPartition

The main class managing the backend where entries are stored and indexed= .

Six kind of parameters can be configured. Here is a table presenting eac= h of them. Only one is a composite parameter, the JdbmIndex list, wh= ich is the list of indexes we can set for this partition

Parameter Default Mandatory Description
id N/A yes The Partition identification.
suffix N/A yes The DN for this partition.
cacheSize 10000 no The number of cached objects
optimizerEnabled true no Tells if the optimizer is on. Unless having som= e
serious reasons to switch it off, don't !
syncOnWrite true no Flush data on disk for every written entry.
indexedAttributes None no Gives the list of indexed attributes. (see belo= w)

Here is an example of a partition configuration

...
  <jdbmPartition id=3D"example"
                 suffix=3D"dc=3Dexample,dc=3Dcom=
"
                 cacheSize=3D"100"
                 optimizerEnabled=3D"true"
                 syncOnWrite=3D"true">
    <indexedAttributes>
      ...
    </indexedAttributes>
  </jdbmPartition>
  ...

We have created the example partition, described by the "dc=3Dexa= mple,dc=3Dcom" DN, with a cache of 100 objects.

JdbmIn= dex

Each JdbmIndex represent an index set on a specific attributeType. Using= index is vital in LDAP if one want to get some performance boost. As a LDA= P server is mainly used for reads, index all the AttributeType you will use= to retrieve entries from the base.

Here are the parameters you can configure on an index

Parameter Default Mandatory Description
attributeId NA yes The attributeType to index (see below, [1])
cacheSize 100 no The number of objects stored into the cache
numDupLimit 512 no WARNING : this is a technical parameter, do not=
change it without good reasons. This parameter tells the server to switch =
from a linear storage of duplicated elements to a B-tree backed storage (see below, [2])
wkDirPath NA no WARNING : this is a technical parameter, do not=
change it without good reasons. Sets the working directory path to somethi= ng
other than the default. Sometimes more performance is gained by locating <= br clear=3D"all" /> indices on separate disk spindles.

[1] Many indexes must be set on technical attributes. Right now, only OI= D are used for those technical attributeTypes. In a close future, we will r= emove them from the indexed attribute list, unless one wants to set another= cache size for them
[2] In some case, an attribute value can point to many entries. For instanc= e, the 'person' ObjectClass will point to potentially millions of entries i= f we manage millions of users. In this case, we don't store all the referen= ces to entries into a big hashmap, but instead we are using a secondary B-T= ree to speed-up the search and modification. Usually, 512 elements stored i= nto a page is a good guess.

Here is an example of indexed attribute configuration for a partition 

...
  <jdbmPartition id=3D"example"
                 suffix=3D"dc=3Dexample,dc=3Dcom=
"
                 cacheSize=3D"100"
                 optimizerEnabled=3D"true"
                 syncOnWrite=3D"true">
    <indexedAttributes>
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.1" cacheSize=3D"100"/=
>
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.2" cacheSize=3D"100"/=
>
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.3" cacheSize=3D"100"/=
>
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.4" cacheSize=3D"100"/=
>
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.5" cacheSize=3D"10"/&=
gt;
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.6" cacheSize=3D"10"/&=
gt;
      <jdbmIndex attributeId=3D"1.3.6.1.4.1.1=
8060.0.4.1.2.7" cacheSize=3D"10"/&=
gt;
      <jdbmIndex attributeId=3D"ou" ca=
cheSize=3D"100"/>
      <jdbmIndex attributeId=3D"uid" c=
acheSize=3D"100"/>
      <jdbmIndex attributeId=3D"objectClass"<=
/span> cacheSize=3D"100"/>
    </indexedAttributes>
  </jdbmPartition>
  ...

We have define two indexes for the ou and uid attributeTyp= e, on top of the technical attributeTypes (all the OIDs), and the ObjectCla= ss, obviously. The cache size is small (from 10 objects to 100 objects).

DefaultDirectoryService

This is the directory service managing all the stored information for ma= ny protocols, including LDAP, KDC, DNS and ChangePa= ssword.

Protoc= ols

All the supported protocols (except DHCP) are derived from the AbstractP= rotocolService, and all of those protocols but NTP inherit from the Directo= ryBackedService.

It means that we have some common configuration shared by all the protoc= ols. Here is the table of the AbstractProtocolService class shared paramete= rs :

Parameter Default Mandatory Description
Enabled N/A no Tells if the service is enabled or not
IpAddress localhost yes The server IP address we are listening on
IpBackLog 50 no The back log for the UDP and TCP acceptors
IpPort N/A no The port number the server is listening to, on = UDP and TCP
NbThreads 3 no The number of threads dedicated to processing t= he incoming requests

In some case, we want a protocol to be accepting connection only on UDP = or only on TCP, or on both but with a different port. In these cases, we ar= e using the following parameters, in place of the three parameters IpBac= kLog, IpPort, NbThreads :

TCP specific configuration :

Parameter Default Mandatory Description
TcpBackLog 50 no The back log for the TCP acceptor
TcpPort N/A no The TCP port number the server is listening to =
NbTcpThreads 3 no The number of threads dedicated to processing t= he incoming requests on TCP

UDP specific configuration :

Parameter Default Mandatory Description
UdpBackLog 50 no The back log for the UDP acceptor
UdpPort NA no The UDP port number the server is listening to =
NbUdpThreads 3 no The number of threads dedicated to processing t= he incoming requests on UDP

And here are the DirectoryBackedService shared parameters :

Parameter Default Mandatory Description
catalogBased N/A no Set to true if this service uses a catalog for = searching different
regions of the DIT for its data (used for kerberos, mainly).
searchBaseDn N/A no The base DN we will search on when looking for = an entry during
an authentication (mainly used for kerberos)
3D""

Those two parameters are not frequently used. Just ignore them unless yo= u are installing a kKerberos server. They might be moved to another place l= ater.

Each protocol have its own configuration. The following paragraphs will = describe those configurations.

ChangePasswordServer

Some documentation is available here3D""

3D""

This service is not fully documented atm. A complete review mus= t be done before considering this service usable.

The ChangePassword server has the following parameters :

Parameter Default Mandatory Description
allowableClockSkew 5 minutes no The allowable clock skew.
emptyAddressesAllowed true no Whether tickets issued with empty Host Addresse= s are allowed.
encryptionTypes des-cbc-md5 no A list of possible encryption types. See [1] fo= r the possible values
policyCategoryCount 3 no The policy for number of character categories r= equired (A - Z), (a - z), (0 - 9),
non-alphanumeric (!, $, #, %, ... ).
policyPasswordLength 6 no The policy for minimum password length.
policyTokenSize 3 no The policy for minimum token size. Passwords mu= st not contain tokens smaller
than 'policyTokenSize' that occur in the user's principal name
primaryRealm EXAMPLE.COM no The primary realm.
servicePrincipal kadmin/changepw@EXAMPLE.COM no The service principal name.

[1] Encryption types values

    =09
  • des-cbc-crc
    • =09
  • des-cbc-md4
    • =09
  • des-cbc-md5
    • =09
  • des3-cbc-md5
    • =09
  • des3-cbc-sha1
    • =09
  • dsaWithSHA1-CmsOID
    • =09
  • md5WithRSAEncryption-CmsOID
    • =09
  • sha1WithRSAEncryption-CmsOID
    • =09
  • rc2CBC-EnvOID
    • =09
  • rsaEncryption-EnvOID
    • =09
  • rsaES-OAEP-ENV-OID
    • =09
  • des-ede3-cbc-Env-OID
    • =09
  • des3-cbc-sha1-kd
    • =09
  • aes128-cts-hmac-sha1-96
    • =09
  • aes256-cts-hmac-sha1-96
    • =09
  • rc4-hmac
    • =09
  • rc4-hmac-exp
    • =09
  • subkey-keymaterial
    • =09
  • rc4-md4
    • =09
  • rc4-hmac-old
    • =09
  • rc4-hmac-old-exp

DnsSer= ver

KdcSer= ver

Ldap= Service

We have two sets of parameters : some are simple, some are composite. We= will expose the full list first, then a description for every composite pa= rameter the composite parameters are bold).

Parameter Default Mandatory Description
allowAnonymousAccess true no A flag to allow or forbid anonymous connections=
certificatePassword N/A no If the certificate is stored in an external Key= Store, this is
the certificate password
confidentialityRequired false no Sets the mode for this LdapService to accept re= quests with or without a
TLS secured connection via either StartTLS extended operations or using LD= APS.
directoryService N/A yes The reference to the underlying Directory servi= ce (see below)
enableLdaps true no Enable LDAPS
extendedOperationHandlers N/A no A list of extended operations supported by the = server. It makes
the server extensible, as you can add a new extended operation (see below)= .
keystoreFile N/A no Define the external KeyStore to use, if one don= 't want to use ADS to
store the certificates
maxSizeLimit No limit (0) no Sets the maximum size limit in number of entrie= s to return for search
maxTimeLimit No limit (0) no Sets the maximum time limit in milliseconds to = conduct a search
SASL configuration

Those parameters are defined when using SASL Authentication.

Parameter Default Mandatory Description
saslHost N/A no Sets the FQDN of this SASL host, validated duri= ng SASL negotiation.
saslMechanismHandlers PLAIN, CRAM_MD5, DIGEST_MD5, GSSAPI, NTLM, GSS_= SPNEGO no A map representing the supported authentication= mechanisms.
saslPrincipal N/A no Sets the Kerberos principal name for this LDAP = service, used by GSSAPI.
saslQop N/A no Sets the desired quality-of-protection, used by= DIGEST-MD5 and GSSAPI.
saslRealms N/A no Sets the realms serviced by this SASL host, use= d by DIGEST-MD5 and GSSAPI.
SaslMechanismHandlers configuration

This is a list of parameters describing the supported SASL mechanisms. C= urrently, the following mechanisms are supported :

The configuration file will be something like :

<ldapService>
    ...
    <!-- The list of supported authentication mechanisms. -->
    <saslMechanismHandlers>
      <simpleMechanismHandler mech-name=3D"SI=
MPLE"/>
      <cramMd5MechanismHandler mech-name=3D"C=
RAM-MD5" />
      <digestMd5MechanismHandler mech-name=3D=
"DIGEST-MD5" />
      <gssapiMechanismHandler mech-name=3D"GS=
SAPI" />
      <ntlmMechanismHandler mech-name=3D"NTLM=
" ntlmProviderFqcn=3D"com.foo.Bar"=
/>

    </saslMechanismHandlers>
  ...

The specific parameters for each of those handlers is described here.

SaslQoP configuration

This parameter is used when the GSSAPI and DIGEST-MD5 authentication han= dlers are used (see RFC = 28313D""<= /sup>). It contains the possible Quality of Protections :

    =09
  • auth
    • =09
  • auth-int
    • =09
  • auth-conf

Here is an example of configuration in the server.xml file :

<ldapService>
    ...
    <!-- The desired quality-of-protection, used by DIGEST-MD5 and GSSAP=
I.  -->
    <saslQop>
      <s:value>auth</s:value>
      <s:value>auth-int</s:valu=
e>
      <s:value>auth-conf</s:value>
    </saslQop>
    ...
SaslRealms configuration

This parameter lists the realms serviced by this SASL host, used by DIGE= ST-MD5 and GSSAPI. It contains a list of host name.

Here is an example in the server.xml file :

<ldapService>
    ...
    <!-- The realms serviced by this=
 SASL host, used by DIGEST-MD5 and GSSAPI. -->
    <saslRealms>
      <s:value>example.com</s:value>
      <s:value>apache.org</s:value>
    </saslRealms>
    ...
DirectoryService configuration
ExtendedOperationHandlers configuration

This parameter is used to list the supported extended operations. This i= s a highly technical parameter, and you are not likely to change it, except= if you want to remove some of the extended operations for some reasons.

The syntax is simple : it's a list of all the supported classes implemen= ting extended operations. Here is an example in the server.xml file :

<ldapService>
    ...
    <!-- the collection of extended operation handlers to install -->
    <extendedOperationHandlers>
      <startTlsHandler/>
      <gracefulShutdownHandler/>
      <launchDiagnosticUiHandler/>
      <!-- The Stored Procedure Extended Operation is not stable yet and=
 it may cause security risks.-->
      <!--storedProcedureExtendedOperationHandler/-->
    </extendedOperationHandlers>
  ...

As you can see, the last extended operation is commented, it won't be av= ailable into this instance of the LDAP server.

Currently, the available extended operations are :

    =09
  • GracefulShutdownHandler : Handle the server shutdown
    • =09
  • LaunchDiagnosticUiHandler : Launch a graphical tool to look at the b= ackend content
    • =09
  • StartTlsHandler : Handle the StartTLS operation (establishes a secur= ed connection between the server and a client)
    • =09
  • StoredProcedureExtendedOperationHandler : Manage StoredProcedured, e= xecuting them when received.

NtpSer= ver

There is no specific parameter for the NtpServer. The AbstractProtoco= lService parameters have to be used in order to configure this server. = Here is an example of configuration :

<NtpServer ipPort=3D=
"60123" nbThreads=3D"8"/>

We have a running NtpServer on localhost, waiting for incomming connecti= on on port 60213, for TCP and UDP transports. 8 processing threads for each= of the transport connectors will be used to process the incoming requests.=

StandardThreadPool ???

LDA= P Handlers

SASL Mechanism handlers

CramMd5MechanismHandler
DigestMd5MechanismHandler
GssapiMechanismHandler
NtlmMechanismHandler
PlainMechanismHandler
SimpleMechanismHandler

ADS

ReplicationConfiguration

ApacheDSJdbmPartition

Resour= ces

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences