Note | ||
---|---|---|
| ||
This site is in the process of being reviewed and updated. |
Introduction
There is two ways to initialize the server :
- As a standelone server
- As an embeded server
Both initialization are different, for the user perspective, but not from the developper perspective, as the first initializtion system embed the server, just adding some specific mechanism to stop the server (remember that the server can be launched as a daemon)
The server initialization is done in two steps. The first one read the confuguration, and set all the necessary structures, and the second step start the server.
Initialization
This is done by reading the server.xml file, which is a Spring based document. As we refer many classes into this file, they will be instanciated on the fly.
The following classes are created :
Object | Class | Description |
---|---|---|
environment | HashTable | Initialize the authentication objects for Ldap, Kerberos, Naming, ChangePW, and set of binary attributes |
configuration | MutableServerStartupConfiguration | Initialize the server |
systemPartitionConfiguration | MutableBTreePartitionConfiguration | Configuration of the system partition |
examplePartitionConfiguration | MutableBTreePartitionConfiguration | Configuration of an example partition |
The following schema represent the properties set by this configuration file :
Configuration initialization
During this phase, we instanciate the MutableServerStartupConfiguration, which will initialize a lot of structures, through the call to those three methods :
- setDefaultAuthenticatorConfigurations
- setDefaultBootstrapSchemas
- setDefaultInterceptorConfigurations
then we will initialize the two declared partitions, system and example
setDefaultAuthenticatorConfigurations() method
This method initialize the authentication methods. At the moment, we support only Simple authentication (ie with a password) or Anonymous authentication.
Each authenticator is stored in a MutableAuthenticatorConfiguration object, which associate a name and a dedicated class.
Note | ||
---|---|---|
| ||
We could declare those authenticator as plugins into the server.xml file, allowing us to easily add some new authenticator. However, this will introduce some weakness in the security system. If somebody add a faked authentication class, and modify the configuration file to load this plugin, what could happen? |
Info | ||
---|---|---|
| ||
SASL authentication should still be implemented... |
For information about authentication mechanisms, open this page : Authentication Mechanisms in ADS
setDefaultBootstrapSchemas() method
In this method, we will load all the default schemas, which are :
- CoreSchema
- CosineSchema
- ApacheSchema
- InetorgpersonSchema
- JavaSchema
- SystemSchema
- CollectiveSchema
Those schema are transofmed into classes by a maven plugin, and they initiate all the needed structures to handle Ldap ObjectClass, Attributes, Comparator, MatchingRules, etc...
The description of this setup can be found in this page : Schema loading
It can be noted that at this stage, we don't load any other schema. Users defined schema are loaded after the initialization of the server has been done.
Note | ||
---|---|---|
| ||
It can be noted that all the default schema loaded in this section are also declared in the server.xml file. It is questionnable to load those default schema in this part, and it may be decided to remove this step in the default initialization... |
setDefaultInterceptorConfigurations() method
Here, we will create the list of all existing interecptors. Each interceptor is an instance of the MutableInterceptorConfiguration class.
The instanciated interceptors are :
- normalizationService
- authenticationService
- referralService
- authorizationService
- defaultAuthorizationService
- exceptionService
- schemaService
- subentryService
- operationalAttributeService
- collectiveAttributeService
- eventService
- triggerService
For more informations about Interceptors, go to this page : Interceptors
Other parameters
When this basic initialization is done, this phase is achieved by the loading of default values :
Parameter | Default value | Description |
---|---|---|
enableNetworking | TRUE | Used if we allow the server to accept network communication (if the server is embeded, it can be set to FALSE) |
synchPeriodMillis | 20 000 ms | Interval between each flush to the disk of modifed data. Can be set to 0 if the user wants all data to be flushed on disk as soon as they are modified, but this has a huge negative impact on performance. |
ldapPort | 389 | Default LDAP port. |
ldapsPort | 686 | Default LDAPS port. |
ldapsCertificateFile | <basedir>/certificates/server.cert | Default certificate file storage |
ldapsCertificatePassword | "changeit" | Default SSL password |
enableLdaps | FALSE | LDAPS is not enabled by default |
enableKerberos | FALSE | KERBEROS is not enabled by default |
enableChangePassword | FALSE | ChangePW is not enabled by default |
enableNtp | FALSE | NTP is not enabled by default |
ldifDirectory | null | The dirctory in which ldif files will be read |
System and example partitions initialization
Those two partitions are instances of the MutableBTreePartitionConfiguration class.
Note | ||||
---|---|---|---|---|
| ||||
We may have differnt kinds of partitions, but at the moment, only one exist, which is based on JDBM. There is a need of in memory parttion, and for RDBMS based partition. One project is to use Hibernate tas an O/R mapping tool. Work In Progress, as usual, and volunteers welcomed |
The initialization will create a Jdbm partition, instanciate one MutableIndexConfiguration per indexed attribute (this class stores the indexed attribute's OID with an cache size - this size is expressed as the number of attributes to keep in the cache -),
Note | ||
---|---|---|
| ||
The indexed attributes are described using their OID. This is not necessary a great choice from the administrator point of view ... We should be able to use either on of the attribute's name or its OID, and internally transform the names to OID latter in the initialization process. |
Note | ||
---|---|---|
| ||
Some attributes must be indexed, like ObjectClass, uid or DistinguishedName, so it may be a good idea to index them even if they are not declared in the configuration file. However, as the cache size is defined at the same time, and as an administrator might want to set the cache size accordingly to its memory configuration, and to its expected performance, this is not really a burdn to have them in the configuration file. |
The last piece of information we have to set is the entry associated with the top level element of the partition : the context entry. As a partition is characterized by a suffix and an associated entry, this is the place to declare this entry. For instance, for the dc=example, dc=com partition, the context entry is :
Code Block |
---|
objectClass: top objectClass: domain objectClass: extensibleObject dc: example |
It should be clear that this entry must be valid. We can consider that the partition suffix is the entry's DN. In our example, this is dc=example, dc=com.
Environment setting
After this first initialization done, we have to augment the envirnoment with some specific properties. Up to this point, the environment contains :
Property | Value | Description |
---|---|---|
java.naming.security.principal | uid=admin,ou=system | Admin user DN |
java.naming.security.authentication | simple | Authentication mechanism used for this user |
java.naming.security.credentials | secret | Admin password : THIS MUST BE CHANGED !!! |
We will add those properties :
Property | Value | Description |
---|---|---|
java.naming.provider.url | ou=system | The system partition URL |
java.naming.factory.initial | org.apache.directory.server.jndi.ServerContextFactory | Initial context factory which will be used to create the inital context. |
org.apache.directory.server.core.configuration.Configuration | Initialized configuration | This property holds the previously initialized configuration |
Now, we have to reach the last two steps : instanciate the server before starting it, and create a thread which will be responsible of saving modified entries from the cache to the disk.
Server instanciation
The configuration has been read, we now have to instanciate the server. This is done throw a JNDI invocation of the InitialDirContext() method :
Code Block |
---|
new InitialDirContext( env ); |
where env is the environment we have set in the previous steps. This method calls the getInitialContext() from the ServerContextFactory class which has been associated with the java.naming.factory.initial property.