1.2 - Network Layer

This layer is the part the user connects to when he wants to obtain some data from the server. This is not a mandatory part ot the server : we don't need to use it when the server is embedded.

-

We offer more than just LDAP protocol, the server also include various protocols :
- Kerberos
- NTP
- DHCP
- DNS
-* ChangePassword

-

Not all of them are implemented in the current version, but at least the Kerberos server is available. (The other protocols have been developped as a proof of concept : as they are all dpeending on a storage database, we have used the LDAP server as a storage).

+

We offer more than just LDAP protocol, the server also include various protocols :

+

+

Kerberos

+

NTP

+

DHCP

+

DNS

+

ChangePassword

+

+

Not all of them are implemented in the current version, but at least the Kerberos server is available. The other protocols have been developped as a proof of concept : as they are all depending upon a storage database, we have used the LDAP server as a storage.

It's perfectly possible to imagine more protocols being implemented in the near future...

Server startup

-

This chapter title is a bit misleading. We don't start a server, we start a DirectoryService, then we start various servers on top of it. The DirectoryService is the part responsible for the management f data (retrieval, storage, etc). All the servers can access this storage if needed.

+

This chapter title is a bit misleading. We don't start a server, we start a DirectoryService, then we start various servers on top of it.
+The DirectoryService is the part responsible for the management of data (retrieval, storage, etc). All the servers can access this storage if needed.

So when the DirectoryService has been started and is operational, we can start the various servers, which will accept incoming requests from remote peers.

Transports

We allow connection through the definition of transports. A Transport is a TCP or an UDP socket capable of absorbing a request and to send a response. Depending on the type of server, we may declare one or more TCPTransports, or a TCP and a UDPTransports, or an UDPTransport only.

1.3 - DirectoryService

The DirectoryService is the core of the server. This is where we process incoming requests and ask the backend for data.

It has an entry point, the OperationManager, which is in charge of pushing the requests into the Interceptors chain, and to protect the server against concurrent modifications.

-

Then the request is going through every Interceptor being registred for this operation. When we have gone through all the Interceptors, we have reach the PartitionNexus, which is the connection with the backends.

-

We now just have to determinate which type of Backend we should address, and this is done using the Dn.The request is then transmitted to the Backend, which returns the result.

-

The result bubble up through the Interceptors as we unfold the stack stack, up the the OperationManager and the caller.

+

Then the request is going through every Interceptor being registred for this operation. When we have gone through all the Interceptors, we have reached the PartitionNexus, which is the connection with the backends.

+

We now just have to determinate which type of Backend we should address, and this is done using the Dn. The request is then transmitted to the Backend, which returns the result.

+

The result bubbles up through the Interceptors as we unfold the stack stack, up to the OperationManager and to the caller.

Environment

The DirectoryService knows about its execution environment : it has a schemaManager instance, it knows about the Interceptors chain, it stores a map of all the pending requests (it's necessary as one may abandon some request), it holds the existing Sessions.

In other word, the DirectoryService is not only the part of teh server executing the logic, it also holds the current state of every clients.

Some Interceptors can be disabled, some other can be enabled. It's also possible to add some new one.

All in all, they will handle operations from a specific functional aspect.

Handled operations

-

Each Interceptor handle a subset of the possible operations, among those listed in the following table :

+

Each Interceptor handles a subset of the possible operations, among those listed in the following table :

@@ -142,23 +142,23 @@

Add

-

Add an entry in the backend

+

Adds an entry in the backend

Bind

-

Bind on the DirectoryService

+

Binds on the DirectoryService

Compare

-

Compare the elements with the associated entry in the backend

+

Compares the elements with the associated entry in the backend

Delete

-

Delete the entry

+

Deletes the entry

getRooDSE

-

Get back the RootDSE entry

+

Gets back the RootDSE entry

hasEntry

@@ -166,37 +166,38 @@

Lookup

-

Fetch an entry

+

Fetches an entry

Modify

-

Modify an entry

+

Modifies an entry

Move

-

Move an entry

+

Moves an entry

MoveAndRename

-

Move and rename an entry

+

Moves and renames an entry

Rename

-

Rename an entry

+

Renames an entry

Search

-

Search for entries

+

Searches for entries

Unbind

-

Unbind from the DirectoryService

+

Unbinds from the DirectoryService

-

It is important to understand that each operation wil go through each Interceptor that are declared to handle the operation, down to the backend.

+

It is important to understand that each operation will go through each Interceptor declared to handle the operation, down to the backend.

Existing interceptors

-

The following interceptors are already present in the server, even if they are not enabled. In this table, we list all the operation each interceptor is handling, and if the interceptor is enabled by default or not :

+

The following interceptors are already present in the server, even if they are not enabled.
+In this table, we list all the operations each interceptor is handling, and if the interceptor is enabled by default or not :

@@ -527,7 +528,7 @@

Interceptors order

-

As we already said, the Intecreptors order is significant : why would we proceed an Add operation through all the Interceptors if the user is simply denied the right to add an entry by the AciAuthorizationInterceptor ?

+

As we already said, the Interceptors order is significant : why would we proceed an Add operation through all the Interceptors if the user is simply denied the right to add an entry by the AciAuthorizationInterceptor ?

Currently, the following order is enforced :

@@ -596,7 +597,7 @@

Example

-

Let's consider the search operation. It will be processed successuvly by the following Intecreptors, as it can be deduced by the two previous tables :

+

Let's consider the search operation. It will be processed successively by the following Interceptors, as it can be deduced by the two previous tables :

NormalizationInterceptor

AuthenticationInterceptor

@@ -608,10 +609,10 @@

We can do the same exercise for each operation.

Processing

-

Basically, an Interceptor receives a request for an operation, do some pre-processing, call the next Interceptor in the chain, do some post-processing, and return a result.

+

Basically, an Interceptor receives a request for an operation, does some pre-processing, calls the next Interceptor in the chain, does some post-processing, and returns a result.

Calling the next Interceptor is as simple as calling the next(OperationContext) method, which will compute the right Interceptor.

The pre-processing and post-processing are standard Java code, there is nothing special there.

-

Each operation is passed into an instance of a specific OperationContext, which contains all what is needed about the operation and the environement.

+

Each operation is passed into an instance of a specific OperationContext, which contains all what is needed about the operation and the environment.

1.5 - Backend

The Backend is the part of the server responsible for storing data in a way we can easily retrieve them. This storage does not necessarily have to be remanent : we can have a in-memory backend.

Existing Backends

-

We currently have 3 different backends :
- JDBM
- LDIF
-* In-Memory

+

We currently have 3 different backends :

+

+

JDBM

+

LDIF

+

In-Memory

+

JDBM Backend

The JDBM backend is storing data on disk, using BTrees. It's fast when it comes to retrieve data, slow when you have to add them.

In-Memory Backend

This Backend loads in memory a full set of entries. ALl of them must be hold by the existig memory, we don't write on disk anything nor we read anything from disk. If the server is stopped, everything is lost.

LDIF Backend

-

It come sin two forms : one single file, or many fles (one per entry). It's always backed by a in-memory Backend, otherwise it would not be possible to retrieve the entries.

-

As we depend on a in-memory backend, which handles the indexes, we have to create those index when this Backend is read, which can be a costly operation.

+

It comes in two forms : one single file, or many fles (one per entry). It's always backed by a in-memory Backend, otherwise it would not be possible to retrieve the entries.

+

As we depend on a in-memory backend, which handles the indexes, we have to create those indexes when this Backend is read, which can be a costly operation.

Future Backends

We intend to add another in-memory backend, based on Mavibot, a MVCC BTREE. The biggest advantage over the other systems is that it's fast, it allows concurrent reads without locks when the other Backend block the reads when some write operation is being processed. Also it saves on disk it contents peridodically, and has a Journal so that we can recover fro a crash.

The only drawback is that all the entries and indexes must hold in memory. On the other hand, we don't anymore need a cache.

@@ -147,7 +149,7 @@

Basically, each Backend instance inherit from the AbstractBTreePartition class. We can see that a Backendmust be a Btree.

Data are stored into various tables. In fact, we have one table containing all the entries - the MasterTable - and many indexes.

MasterTable

-

The MasterTable coantins all the entries, serialized.

+

The MasterTable contains all the entries, serialized.

This table is a BTree, where the key is the entry's UUID, and the value the serialized entry.

Theorically, we could be able to read it, and restore the whole database, indexes included, assuming that we know which index we have to create. Sadly, it's not enough, as the entries are stored without any information about their position in the DIT.
@@ -167,9 +169,9 @@ Theorically, we could be able to read it

OneAlias : An index used for children aliases

SubAlias : An index used of descendant aliases

-

The user may define many different index, dependening on his needs.

+

The user may define many different indexes, depending on his or her needs.

The ParentIdAndRdn index

-

This index is special, as it's used to associate an entry to a position in the DIT. Assuming that each entry has a Dn, and that this Dn describes a hierarchie, the ParentIdAndRdn index depicts this hierarchy.

+

This index is special, as it's used to associate an entry to a position in the DIT. Assuming that each entry has a Dn, and that this Dn describes a hierarchy, the ParentIdAndRdn index depicts this hierarchy.

The ParentId part refers to the UUID of the parent for the current entry. The Rdn part is the entry Rdn. In order to rebuild the full Dn for a given entry, we must get all the ParentIdAndRdn up to the root to grab all the needed Rdn.

3 - Administrative Model

The Administrative Model is a really critical notion that need to be understood, because it drives many of ApacheDS roles.

+

The Administrative Model is a really critical notion that needs to be understood, because it drives many of ApacheDS roles.

It's directly inherited by the X.500 Administrative model (in fact, we do implement the full X.500 sepcification related to AAs).

What is the Administrative Model ?

-

The idea is to define the DIT as some areas which are administrated. Each area can be defined, and covers a set of entries, and each area can manage one ore more roles we want to manage. Those roles can be related to authorization, schema, etc... Each of this areas can overlap, but in any case, if two areas are overlaping, then one area totally include the other one.

-

The Admnistrative Model is everything we need to implement in order to be able to manage roles on some defined areas.

+

The idea is to define the DIT as some areas which are administrated.
+Each area can be defined, and covers a set of entries, and each area can manage one ore more roles we want to manage.
+Those roles can be related to authorization, schema, etc... Each of these areas can overlap, but in any case, if two areas are overlapping,
+then one area totally includes the other one.

+

The Administrative Model is everything we need to implement in order to be able to manage roles on some defined areas.

Areas

-

An Area describe a part of the DIT which will start from a specific entry, and span across a part of the subtree starting at the base entry. An area is administrated by an AP (Administrative Point) which holds all the needed information about the area and the roles.

+

An Area describes a part of the DIT which will start from a specific entry, and span across a part of the subtree starting at the base entry. An area is administrated by an AP (Administrative Point) which holds all the needed information about the area and the roles.

We have three kind of areas :

AAA : Autonomous Administrative Areas

SAA : Specific Administrative Areas

IAA : Inner Administrative Areas

-

AAAs cover all the roles as if we have declared one SAA for each existing role. They overload any area in which they can be encapsulated, hiding them.

+

AAAs cover all the roles as if we had declared one SAA for each existing role. They overload any area in which they can be encapsulated, hiding them.

SAAs cover one specific role, and overload any encapsulating area with the same role.

IAAs cover one specific role, but don't not overload any encapsulating area with the same role.

Administration Point

An Administration Point is the point in the DIT where an area starts. It defines the roles, and the scope that applies to this area.

-

Once we know which area we need to define, and the associated roles, it's mandatory to store those information in the DIT. This is done by addinga subentries, which just are entries storing all the administrative configuration.

+

Once we know which area we need to define, and the associated roles, it's mandatory to store those information in the DIT. This is done by adding subentries, which just are entries storing all the administrative configuration.

An Administrative Point is stored as a subentry (which is just a plain LDAP entry) just below the base of the defined area.

- A Subentry is just a plain normal entry except that it contains administative model informations. They are stored below the entry they are managing, as a child entry.
+ A Subentry is just a plain normal entry except that it contains administrative model informations.
+ They are stored below the entry they are managing, as a child entry.

We also use the term "subtree" to define areas. This is due to the fact that we define a subtree specification in the administration point to express the set of selected entries.
Modified: websites/staging/directory/trunk/content/apacheds/advanced-ug/3.1-administrative-points.html
==============================================================================
--- websites/staging/directory/trunk/content/apacheds/advanced-ug/3.1-administrative-points.html (original)
+++ websites/staging/directory/trunk/content/apacheds/advanced-ug/3.1-administrative-points.html Tue Dec 25 19:40:07 2012
@@ -147,36 +147,44 @@ role the Subentry is defined for.

Administrative Point

We will describe the types of Administrative Points we are managing and the
way they impact their associated Administrative Areas (AA)

Those three different APs are related with each other in this way :
-AAPs manage an AA as if all the possible type of SAP where declared
-for this area
-SAPs manage an AA with respect to one specific kind of role (Access
-Control, Collective Attributes, SubSchema or Trigger Execution )
- IAPs manage an AA inside another AP
- An AAP or a SAP start at some point in the tree, and all the entries
+

We have three different kind of AP :

+

+

Autonomous AP ( AAP)

+

Specific AP (SAP)

+

Inner AP (IAP)

+

+

Those three different APs are related with each other in this way :

+

+

AAPs manage an AA as if all the possible type of SAP where declared
+for this area

+

SAPs manage an AA with respect to one specific kind of role (Access
+Control, Collective Attributes, SubSchema or Trigger Execution )

+

IAPs manage an AA inside another AP

+

An AAP or a SAP start at some point in the tree, and all the entries
below this AAP/SAP aren't related to any other AAP. That also means
that if an AAP/SAP is created below an existing AP, then all the
entries it covers are unlinked from the previous AP (except that for SAP,
we just logically keep a link to the higher AP for all the other aspects
-but the one covered by the new SAP)
- An IAPmust be included into another AP, being it an AAP, SAP
-or IAP. It controls a specific aspect too, as for the SAP, but it will
-be combined with any of the above AP*.
+but the one covered by the new SAP)

+

An IAPmust be included into another AP, being it an AAP, SAP
+or IAP. It controls a specific aspect too, as for the SAP, but it will
+be combined with any of the above AP.

Subentry

Once we have defined an AP, we can add some subentries which contain
-the description of the administrative actions, including :
- The area this subentry covers, defined by a SubtreeSpecification,
-named subtree*.

+the description of the administrative actions, including :
+

+

The area this subentry covers, defined by a SubtreeSpecification,
+named subtree.