Introduction to Directory Proxy Server

The Directory Proxy Server architecture enables you to configure several
objects that control how client requests are routed to backend data sources.
These configuration objects are illustrated at a high level in the following
simplified schematic of the Directory Proxy Server architecture. This illustration
will help you to understand the architectural concepts presented in the remainder
of this book.

Figure 15–1 Simplified Architecture of Directory Proxy Server

Directory Proxy Server Architecture

This section briefly presents the new Directory Proxy Server architecture
and what is new compared to 5.x. Its aim is to help you understand why literal
translation of some 5.x configuration attributes is not possible.

Data views, however, are new. They do not correspond to anything present
in 5.x. Fundamentally Directory Proxy Server handles incoming connections individually,
assigning a connection handler when the connection is
opened, and reassigning a connection handler upon rebind when the bind identity
changes.

The connection handler gives Directory Proxy Server a set of policy rules
for making decisions about what to do with operations requested through a
given connection. Connection handlers correspond roughly to network groups
in 5.x, yet whereas network groups are configured to use load balanced groups
directly.

Directory Proxy Server uses connection handlers mainly to determine policies
about a connection, so it can take appropriate decisions about operations
performed on that connection. For example, if a connection handler is configured
to prevent write operations on a certain connection, Directory Proxy Server can
use that property of the policy to short circuit evaluations concerning write
operation requests on that connection. In this case, the appropriate errors
are returned to the client as soon as Directory Proxy Server has decoded the operation.

LDAP operations on a connection are handled in Directory Proxy Server first
through data views. Data views enable Directory Proxy Server to perform DN-based
routing. In other words, operations concerning one set of data can be sent
to one set of data sources, and operations concerning another set of data
can be sent elsewhere. This new architectural form seems unnecessary when
you look at it from the point of view of reproducing a 5.x configuration.
Yet data views become indispensable when you want to distribute different
directory data across various directories, or when you want to recover different
data from disparate data sources to present a virtual directory view of those
sources to a client application.

Overview of Directory Proxy Server Features

Single point of access to directory data stored on multiple
directory servers

Automatic referral following

Reactive and proactive monitoring of directory servers

Configuration on the command line or with a GUI

All connections have a normal listener port and a secure
listener port

Authentication and authorization

Certificate-based authentication with certificate mapping

Secure LDAP reverse proxy

LDAP control filtering

Proxy authorization

Identity mapping

Access control

Distribution

Single point of access to a directory service spread over
multiple directory servers

Extensible and customizable distribution algorithm

Server affinity to address propagation delay problem

Connection pooling and partial BER-decoding for performance
and scalability

Load-balancing/Fail-over

Routing based on the operation or the connection

Automatic load balancing and automatic fail over and fail
back among a set of replicated LDAP directory servers

Three load-balancing algorithms

Virtualization

Multiple virtual views for client applications

Aggregation of multiple heterogeneous data sources

Mapping of attribute names and values

Access to JDBC-compliant data repositories

Access to flat LDIF file resources

Chapter 16 Directory Proxy Server Load Balancing and Client Affinity

Deployments that use more than one data source to respond to client
requests use load balancing to distribute work load. Client affinity can be
used to reduce the risk of propagation delay in load balanced deployments.

LDAP Data Source Pools

Requests from clients are distributed
to an LDAP data source pool. One or more data sources are attached to the
data source pool. The properties of a data source pool determine how client
requests are routed to the different LDAP data sources that are attached to
the pool. The following properties can be configured for an LDAP data source
pool:

client-affinity-policy

The algorithm used to determine when client requests should
exhibit affinity to a single LDAP data source

client-affinity-timeout

The client affinity time-out duration

description

A description of the LDAP data source pool

enable-client-affinity

A flag indicating whether or not consecutive requests from
the same client should be directed to the same LDAP data source

load-balancing-algorithm

The algorithm used to distribute operations over load-balanced
LDAP data sources

Introduction to Load Balancing

Directory Proxy Server distributes requests according to a load balancing
algorithm. The following load balancing algorithms can be configured:

Proportional algorithm

Requests are distributed according to the weight of the data
source and the cumulative load of the data source since the last startup of Directory Proxy Server.

Saturation algorithm

Requests are distributed according to the weight of the data
source and the number of available connections on the data source.

Operational affinity algorithm

Requests are distributed according to the hash value. The
number of hash values that are allocated to an attached data source is proportional
to the weight of that data source.

Failover algorithm

Requests are distributed exclusively to the attached data
source with the highest weight for that operation.

In all load balancing algorithms, each attached data source can be configured
with an independent weight for each of the following types of operation:

Add

Bind

Compare

Delete

Modify DN

Modify

Search

If multiple attached data sources are configured with the same weight
for a given type of operation, Directory Proxy Server distributes the requests
evenly between the data sources. If a data source has a weight of disabled for a particular type of operation, Directory Proxy Server never distributes
requests of that type to the data source. If a data source has a weight of 0 (zero) no requests are distributed to that data source unless
all other data sources are unavailable. Therefore, data sources configured
with a weight of 0 are used only when all other data sources
are down.

An attached data source cannot be selected by the load balancing algorithm
in the following circumstances:

The data source is unavailable because an error occurred.

All connections between the Directory Proxy Server and the data
source are in use.

If a data source is configured as read-only, the data source cannot
receive add, delete, or modify requests. The data source can receive search
requests.

The load balancing algorithm works on a best-effort basis. If there
are not sufficient resources for the load balancing algorithm to distribute
requests by respecting weights, the weights are overruled. For example, if
the number of simultaneous requests to a data source exceeds the maximum number
of connections to that data source, requests are distributed to other data
sources.

When the client affinity feature is active, Directory Proxy Server distributes
requests by using the client affinity feature instead of using the load balancing
algorithm. For information about client affinity, see Client Affinity.

Proportional Algorithm for Load Balancing

In
the proportional algorithm, requests are distributed to attached data sources
according to the following criteria:

The type of request

The weight of the data source as a ratio of the total weights
of the other data sources in the pool

The cumulative load since the last startup of Directory Proxy Server

After startup, the first request of a given type is distributed to the
data source with the highest weight for that type of request. Directory Proxy Server continues
to distribute the requests in proportion to the weight of each data source
for that type of request.

If a data source becomes unavailable, Directory Proxy Server distributes
the requests to remaining data sources in proportion to their weight.

The following figure illustrates how Directory Proxy Server distributes
the first eight search requests to a pool of data sources with different weights.
The data source with a weight of 2 processes twice as many
requests as the data sources with a weight of 1.

Figure 16–1 Distribution of Requests According to the Proportional
Algorithm for Load Balancing

Saturation Algorithm for Load Balancing

In
the saturation algorithm, requests are distributed to data sources according
to a combination of the weight of the data source and the number of available
connections.

All requests of a certain type are distributed to the data source with
the highest weight, until its saturation level is reached.
Once this level is reached, requests are distributed between this data source
and the data source with the next highest weight. The saturation level is
obtained by multiplying the weight of the data source by the total number
of connections.

The following figure illustrates how Directory Proxy Server distributes
requests to a pool of data sources with 10 connections and different weights.
The number of available connections multiplied by the weight is shown in brackets.

Figure 16–2 Distribution of Requests According to the Saturation
Algorithm for Load Balancing

If your deployment includes data sources with greatly different capacity,
you can use the saturation algorithm to distribute requests according to the
capacity of the data source.

Operational Affinity Algorithm for Load Balancing

In the operational affinity algorithm for load balancing, all
requests are allocated a hash value according to the request type and request
properties. Each hash value is allocated to an attached data source. The number
of hash values that are allocated to a data source is proportional to the
weight of the data source.

When a request is received, Directory Proxy Server examines the hash table
to determine whether a request with that hash value has already been distributed.
If the hash value already exists in the hash table, Directory Proxy Server sends
the request to the data source with that hash value. If the hash value does
not exist in the hash table, the request is distributed by using the proportional
algorithm for load balancing.

Figure 16–3 shows an example
with three attached data sources. Data source A has a weight
of 3 for search operations, the other data sources have
a weight of 1 for search operations. The hash table allocates
3/5ths of the hash values to data source A,
1/5th to data source B, and 1/5th to data source C.

If requests have a normal range of diversity, data source A would
receive three times more requests than data source B or
data source C. If there is a disproportionate number of
requests with identical properties, the ratio of requests between the three
data sources is disturbed. For example, if a client make repeated BIND requests
on the same DN, the BIND must always be serviced by the same data source.

Figure 16–3 Distribution of Requests According to the Operational
Affinity Algorithm for Load Balancing

The use of the operational affinity algorithm for load balancing is
beneficial for the following features:

Global account lockout

Cache optimization in Directory Server

Disadvantage of Using the Operational Affinity Algorithm
for Load Balancing

The operational affinity algorithm for load balancing does not ensure
an evenly distributed work load across data sources.

A hash value is allocated to a request according to the type of request
and the properties of the request. A range of hash values represents an arbitrary
group of unrelated requests. It is possible for one range of hash values to
represent many more operations than another range of hash values. A given
range of hash values might represent requests that are made frequently, another
range of hash values might represents requests that are almost never made.

Operational Affinity Algorithm for Global Account
Lockout

By using
the operational affinity algorithm for load balancing, you can ensure that
the same data source always responds to bind requests from a given client.
In this way, you can ensure that a client is locked out after the maximum
number of failed bind attempts. If the same data source does not respond to
bind requests from a given client, the client can exceed the maximum number
of failed bind attempts.

When a client binds, a hash value for the request is allocated according
to the bind credentials. Directory Proxy Server consults the hash table and distributes
the request to the data source for that hash value. No matter how many times
the client binds, the hash value is always the same. The request is always
distributed to the same data source.

If a client requests a bind without the appropriate credentials, the
data source rejects the bind request. If the client makes a second or third
bind request, the same data source rejects the bind request. When the client
exceeds the maximum number of allowed bind attempts, Directory Server locks
the client out.

Operational Affinity Algorithm for Cache Optimization

By using
the operational affinity algorithm for load balancing, searches from the same
client to the same entry can always be distributed to the same data source.
When a data source responds to a request, the targeted entry is stored in
the cache. If the same data source responds repeatedly to the same request,
the data source can benefit from using the cached data.

Failover Algorithm for Load Balancing

In
the failover algorithm, requests of a given type are distributed exclusively
to the attached data source with the highest weight for that operation. If
that attached data source fails, requests are distributed exclusively to the
attached data source with the next highest weight for that operation. If the
data source with the highest weight comes back on line, requests are distributed
to that data source.

Client Affinity

Client affinity
is defined between a client connection and a data source. When client affinity
is defined, requests from a specified client connection are distributed to
a specified data source in a data source pool.

The client affinity feature reduces the risk of propagation delay in
deployments that use load balancing. Propagation delays can occur when a client
makes consecutive requests that target the same entry if those requests are
not treated by the same data source. For example, a client might make one
request to change an entry and a second request to use the changed entry.
If the second request is treated by a data source that has not been updated
by the first request, an error occurs.

Client affinity can be configured in the following ways:

Enabled or disabled

Configured for all write requests after the first write request

Configured for all requests after the first write request

Configured for all requests after the first read request or
write request

Configured for first read request after a write request

Configured to expire after a specified time

Client affinity takes precedence over the load balancing algorithm. Directory Proxy Server distributes
a request from the specified connection to the specified data source, irrespective
of the load balancing algorithm.

If client affinity is defined and enabled, the load balancing algorithm
takes precedence in the following circumstances:

The request that starts client affinity has not occurred

The request that ends client affinity has occurred

The client affinity time-out has expired

The specified data source cannot be used for a request, or
an error has occurred on the specified data source

A data source cannot be used for a request in the following circumstances:

It is offline.

It is not configured to perform the operation being requested.
For example, a data source that is configured for read requests cannot respond
to write requests.

Chapter 17 Directory Proxy Server Distribution

Directory Proxy Server enables
distribution through the definition of data views. Data views are defined
with a view base, which determines the base DN of the entries in that data
view. Based on the distribution algorithms provided in Directory Proxy Server,
you can specify how entries are divided among the different data views.

LDAP Data View Features

A simple LDAP data view is defined primarily by the base DN of the data
view. In a simple data view all of the entries in the subtree are encompassed
by the data view. Data views can exist in hierarchy, with a superior
data view and a subordinate data view.
A subordinate data view is a data view whose base DN is inferior to the base
DN of a superior data view. The entries in a subordinate data view are excluded
from the superior data view.

For information about the features of a data view, see the following
sections.

Excluding a Subtree From a Data View

When a subordinate
data view is created, Directory Proxy Server automatically excludes the subordinate
data view from the superior data view. When a request targets the subordinate
data view, the request is sent to the subordinate data view instead of the
superior data view.

Attribute Renaming and DN Renaming

Each entry in a directory is identified by a DN and a set of attributes and their values. Often,
the DN and the attributes defined on the client side do not map to the DN
and the attributes defined on the server side.

Data views can be defined to rename DNs and attributes to values that
match the server side. When a client makes a request, the DNs and attributes
are renamed to match the server side. When the result is returned to a client,
the DN and attributes are changed back to match the client side.

Attribute Renaming

The following figure illustrates how attribute renaming is performed
by Directory Proxy Server.

Figure 17–1 Attribute Renaming

In Figure 17–1, the email client
expects the last names to be specified by the attribute surname However,
in the LDAP server, last names are specified by the attribute sn.
When attributes are renamed, only the name of the attribute is affected —
the value of the attribute is not changed. However, when attributes are renamed
all entries with that name are renamed.

Figure 17–2 DN Renaming

Attributes that contain DNs must also be renamed if those DNs are in
the portion of the DIT that is affected by the original DN renaming. In Figure 17–2, the group attribute
contains a list of the DNs of group members. When dc=example, dc=com is
renamed to dc=example, dc=org, the DNs in the group attribute
must also be renamed.

Distributing Entries In a Subtree to Different Data Views

A distribution
algorithm distributes operations across data views that have the same base
DN. The type of distribution algorithm is defined by the distribution-algorithm parameter.

To determine how to distribute operations, the distribution algorithm
considers the value of the attribute directly below the
base DN of the data view. For example, consider a data view with a base DN
of ou=people,dc=example,dc=com. If a search operation contains
the base DN uid=23,ou=people,dc=example,dc=com, the distribution
algorithm considers uid to be the routing attribute, because uid is directly below the base DN of the data view. The algorithm
then attempts to match the value 23 to determine how to
route the operation.

However, if the search operation contains the base DN uid=23,ou=managers,ou=people,dc=example,dc=com, the distribution algorithm considers ou to
be the routing attribute, because ou is directly below
the base DN of the data view. Because ou does not match
the uid specified in the search query, the distribution
algorithm cannot distribute the search correctly. For distribution to work
in this case, the base DN of the data view should be ou=managers,ou=people,dc=example,dc=com.

You must therefore ensure that the base DN of the data view is appropriate
to the distribution algorithm.

The following distribution algorithms are provided with Directory Proxy Server:

Pattern matching

Requests are distributed to data views based on the match between the
parameters of the requests and one or more patterns. Patterns are defined
by the following parameters:

Requests are distributed to data views according to the numeric value
of the RDN in the request. The numeric value is taken from the value of the
first RDN beneath the base DN of the data view. Numeric bounds are defined
by these parameters:

numeric-attrs

numeric-default-data-view

numeric-lower-bound

numeric-upper-bound

Lexicographic

Requests are distributed to data views according to the lexicographic
value of the RDN in the request. Lexico bounds are taken from the value of
the first RDN beneath the base DN of the data view. Lexico bounds are defined
by these parameters:

lexicographic-attrs

lexicographic-lower-bound

lexicographic-upper-bound

Replication

Requests are distributed to data views according to the role
of the data view in replication. The algorithm distributes write operations
to all data sources in the data source pool and read operations to a single
data source. The replication role is defined by the replication-role parameter.
A data view can have a master role or a consumer role.

Limitations of Distribution Algorithms

The following list outlines the situations in which requests do not
respect the distribution algorithm. The examples in this list assume that
the routing attribute is uid and the view base of the data
view is dc=example,dc=com.

When the search base ends with the view base and the scope
is base, requests are always distributed to the first data
view. For example:

$ ldapsearch -b "ou=people,dc=example,dc=com" -s base "uid=116352"

When the search base ends with the view base and the scope
is one level or subtree, requests are always distributed to the first data
view. For example:

$ ldapsearch -b "ou=people,dc=example,dc=com" -s sub "uid=116352"

When the search base ends with the view base and starts with
the routing attribute, but the search filter does not contain the routing
attribute, requests are distributed to all data views. For example:

Data Views to Route All Requests, Irrespective of
the Target DN of the Request

This section describes a data view that routes all requests to a data
source pool, irrespective of the target DN of the request. This data view
is called the root data view. The root data view is
created by default when an instance of Directory Proxy Server is created.

The example in this section has multiple data sources that contain the
same set of subtrees. The data sources are data-equivalent and pooled into
one data source pool for load balancing. A data view is configured with a
base DN at the rootDSE, represented as “ ”. Figure 17–3 shows an example deployment.

Figure 17–3 Example Deployment That Routes All Requests to a
Data Source Pool, Irrespective of the Target DN of the Request

Because the base DN of the data view is the rootDSE, the data view encompasses
the base DN of all possible requests. All requests are
forwarded to the data source pool, irrespective of the target DN or whether
the data source contains an entry for the request.

If Directory Proxy Server receives a request with a target DN that does
not exist in the data source, the request is forwarded to the data source
pool. The data source that responds to the request returns an error.

Data Views to Route Requests When a List of Subtrees
Are Stored on Multiple, Data-Equivalent Data Sources

This section describes data views that route requests targeted at a
list of subtrees to a set of data-equivalent data sources.

The example in this section has multiple data sources that each contain
the same set of subtrees. The data sources are data-equivalent and pooled
into one data source pool for load balancing. A data view is configured for
each subtree to expose that subtree to client requests. Figure 17–3 shows the example deployment.

Figure 17–4 Example Deployment That Routes Requests When a List
of Subtrees Is Stored on Multiple, Data-Equivalent Data Sources

A request is exposed to a data view only if the target DN is subordinate
to the base DN of the data view. When a request is exposed to a data view,
the request is forwarded to the data source pool specified by the data view.

If the target DN of a request is not subordinate to the base DN of any
data view, Directory Proxy Server returns an error.

In Figure 17–4, requests that
target dc=example1,dc=com or dc=example2,dc=com are
forwarded to the data source pool. Directory Proxy Server returns an error for
requests that target neither dc=example1,dc=com nor dc=example2,dc=com.

Data Views to Provide a Single Point of Access When
Different Subtrees Are Stored on Different Data Sources

This section describes how Directory Proxy Server provides a single point
of access to different subtrees of data on multiple data sources. The example
in this section contains a data view is for each subtree, to expose that subtree
to client requests. A data source pool is configured for each set of data-equivalent
data sources. Figure 17–5 shows the
example deployment.

Figure 17–5 Example Deployment That Provides a Single Point
of Access When Different Subtrees Are Stored on Different Data Sources

The Directory Proxy Server exposes a request to a data view if the DN targeted
by the request is subordinate to the base DN of the data view. When a request
is exposed to a data view, the request is forwarded to the data source pool
specified by the data view.

If a request has a target DN that is not subordinate to the base DN
of a data view, Directory Proxy Server returns an error.

In Figure 17–5, client requests
that target dc=example1,dc=com are forwarded to the data
source pool 1 and are treated by data source 1 or data source 1'. Client requests
that target dc=example2,dc=com are forwarded to the data
source pool 2 and are treated by data source 2 or data source 2'. The Directory Proxy Server returns
an error for client requests that target neither dc=example1,dc=com nor dc=example2,dc=com.

Data Views to Route Requests When Different Parts
of a Subtree Are Stored in Different Data Sources

This section describes how Directory Proxy Server provides a single point
of access to different parts of a subtree stored in multiple data sources.
To route requests for different parts of a subtree, Directory Proxy Server uses
a distribution algorithm. In the example in this section, Directory Proxy Server uses
the numeric distribution algorithm. For more information about distribution
algorithms, see Distributing Entries In a Subtree to Different Data Views.

The example in this section contains two data views with the same base
DN. A numeric distribution algorithm is used to separate entries into different
data views. A data source pool is configured for each set of data-equivalent
data sources. Figure 17–6 shows the
example deployment.

Figure 17–6 Example Deployment That Routes Requests When Different
Parts of a Subtree Are Stored in Different Data Sources

Directory Proxy Server exposes a request to the data view which satisfies
the following conditions:

The DN targeted by the request is subordinate to the base
DN of the data view

The parameters of the requests match the pattern specified
by the distribution algorithm in the data view

When a request is exposed to a data view, the request is forwarded to
the data source pool specified by the data view.

If a request that does not match the conditions of any data view, Directory Proxy Server returns
an error.

The example in Figure 17–7 contains
three data views. The base DN of dataview–1 is superior
to the base DNs of dataview-2 and dataview-3.

The excluded-subtrees property on dataview-1 excludes dataview-2 and dataview-3 from dataview-1.
The alternate-search-base-dn properties on dataview-2 and dataview-3 include dataview-2 and dataview-3 in search operations targeted at dataview-1. Figure 17–7 shows the example deployment.

Figure 17–7 Example Deployment to Route Requests When Superior
and Subordinate Subtrees Are Stored in Different Data Sources

Directory Proxy Server exposes a request to the data view which satisfies
the following conditions:

The DN targeted by the request is subordinate to the base
DN of the data view

The DN targeted by the request is not excluded from the data
view by the excluded-subtrees parameter

When a request is exposed to a data view, the request is forwarded to
the data source pool specified by the data view.

If a request does not match the conditions of any data view, the request
cannot be exposed to a data view and Directory Proxy Server returns an error.

In Figure 17–7, client requests
that target dc=example,dc=com but do not target ou=computer,
dc=example, dc=com or ou=people, dc=example, dc=com are
forwarded to the data source pool 1. Such requests are treated by data source
1 or data source 1'. Client requests that target ou=computer, dc=example,
dc=com or ou=people, dc=example, dc=com are forwarded
to data source pool 2 and data source 3, respectively. Directory Proxy Server returns
an error for client requests that do not target dc=example,dc=com.

All three data views are candidates for search operations that are targeted
at dc=example,dc=com.

Data Views With Hierarchy and a Distribution Algorithm

Different data views can be used in the same topology to expose or hide
parts of a subtree. Figure 17–8 shows
are an example with data views that combine the hierarchy shown in Figure 17–7 with the distribution algorithms
shown in Figure 17–6.

The example in Figure 17–8 contains
four data views. The base DN of data view 1 is superior to the base DNs of
the other data views. Data view 3 and data view 4 have the same base DN, but
a numeric distribution algorithm separates entries into the different data
views. Figure 17–8 shows the example
deployment.

Figure 17–8 Data View With Hierarchy and a Distribution Algorithm

The excluded-subtrees property on dataview-1 excludes
the other data views from dataview-1. The alternate-search-base-dn property on dataview-2, dataview-3,
and dataview-4 includes these data views in search operations
targeted at dataview-1.

Directory Proxy Server exposes a request to the data view which satisfies
the following conditions:

The DN targeted by the request is subordinate to the base
DN of the data view

The DN targeted by the request is not excluded from the data
view by the excluded-subtrees parameter

The parameters of the requests match the pattern specified
by the distribution algorithm

When a request is exposed to a data view, the request is forwarded to
the data source pool specified by the data view.

If a request does not match the conditions of any data view, Directory Proxy Server returns
an error.

Chapter 18 Directory Proxy Server Virtualization

Directory Proxy Server enables
virtualization through the definition of virtual data views. Virtual data
views enable you to display physical data in a different way. This chapter
describes how virtual data views are created, and the kinds of virtual data
views that are available in Directory Proxy Server.

Construction of Virtual Data Views

A virtual data view is essentially a physical data
view on which certain transformation actions have been defined. The transformation
actions take place in real time, to create the virtual data view. The following
figure shows how transformation actions are defined on a physical data view
to create a virtual data view.

Figure 18–1 Virtual Data View

In addition to the transformation actions, certain properties can be
defined on a data view, which restrict the way in which data can be managed
through that data view. The additional virtual data view properties are described
in Additional Virtual Data View Properties.

Caution –

Virtual data views imply a performance impact. The significance
of the performance impact depends on several factors including the size of
the physical data source, the complexity of the transformation, and the complexity
of any virtual ACIs you might use.

Virtual Data Transformations

Virtual
data transformations create a virtual data view from a physical data view.
Practically, you never define a virtual data view. Instead, you specify the
transformations that you require and define these on an existing physical
data view. A transformation performs a specific action in
a certain direction. The direction of a transformation
determines the transformation model. When you define a virtual data transformation,
you create a virtual attribute that exists only in the context of the virtual
data view.

A transformation is defined on a data view, by using the dpconf command
as follows:

The view-name refers to the data view on
which the transformation is defined. The attr-name refers
to the virtual attribute that is created. The model, action, and additional
parameters are described in the following sections.

The name of the virtual transformation can be set by using the following
command:

Transformation Models

The transformation model is determined by the direction of a transformation,
in other words, whether the transformation is applied during the request,
during the response, or both.

In this sense, transformations can be categorized into the following
types:

Mapping transformations (bidirectional transformations)

Write transformations (inbound transformations)

Read transformations (outbound transformations)

Mapping Transformations

The
most common transformation is a bidirectional (mapping) transformation. A
mapping transformation is applied during the request, and its inverse is applied
during the response. These transformations are called mappings because
in effect, an attribute or entry in the physical data view maps to an attribute
or entry in the virtual data view. Mapping transformations enable you to process
existing values before assigning them to a DN component, an attribute type
or value, or an object class.

The following diagram illustrates the principals of a mapping transformation.

Figure 18–2 Mapping Transformation

A mapping transformation is defined on a data view, by running the dpconf command as follows:

Example 18–1 When Would You Use a Mapping Transformation?

Imagine, for example, an organization has a physical data source that
contains entries with the attributes surname and givename. The organization has a client application that requires entries
to have a cn (common name) attribute of the form givenname
surname.

The client application sends a search request for an entry of the form cn=Carlos Fuentes. A transformation is defined that extracts the
name and surname during this request and transforms the request to one of
the form surname=Fuentes, givenname=Carlos. The corresponding
entry is located in the data source. Before returning this entry to the client
application, the inverse transformation is performed. The client application
receives the entry as cn=Carlos Fuentes, which it understands.

This request is transformed to be of the form surname=Fuentes,
givenname=Carlos. Similarly, the client application sends a modify
request to change the cn attribute of an entry to Lisa
Davis. The request is transformed so that the givenname attribute
of the physical entry is modified to Lisa and the surname attribute is modified to Davis.

Write Transformations

A write
transformation is applied during the request, but not during the response.
A write transformation changes the physical data in storage.

The following diagram illustrates the principals of a write transformation.

Figure 18–3 Write Transformation

A write transformation is defined on a data view, by using the dpconf command as follows:

Example 18–2 When Would You Use a Write Transformation

Imagine an organization has a legacy application whose function is to
add person entries to a data source. The application adds the entries without
the telephoneNumber attribute. The physical data source
has been upgraded and the telephoneNumber is now a mandatory
attribute for person entries. The transformation required here is to add the telephoneNumber attribute during the add request. This transformation
changes the entry that is written to the database. No reverse transformation
is required.

Read Transformations

A read
transformation is applied only during the response to a request. No transformation
is applied during the request and the physical data is not changed.

The following diagram illustrates the principals of a read transformation.

Figure 18–4 Read Transformation

A read transformation is defined on a data view, by using the dpconf command as follows:

Example 18–3 When Would You Use a Read Transformation

Imagine an organization has a legacy application whose function is to
display person entries. The application does not support entries that do not
contain a mail attribute. The physical data source has
been upgraded and the email attribute no longer exists
for person entries (e-mail addresses are constructed using other attributes).

The transformation required here is to add the mail attribute
during the search response. This transformation changes the entry that is
read from the database and adds a mail attribute whose
value is givenname.surname@example.com. No reverse transformation is required and the physical data is
not changed.

Note that with the above transformation, the mail attribute
makes no sense in a search request filter. Search request filters must contain
physical attributes.

Transformation Actions

Transformation actions describe what a transformation does to
its target entry or entries. The following transformation actions are possible:

Construct an attribute. This
action enables you to construct a virtual attribute that does not actually
exist in the physical data source but is required by a client application.
The action can also be used to alter an add or modify request to construct
an attribute that is required by the physical data source.

To
construct the attribute, use the add-attr transformation
action.

Remove an attribute. This
action enables you to delete an attribute from a client request if that attribute
is not permitted by the schema on the physical data source. The action can
also be used to remove an attribute from the response sent to a client application
if the client application does not require that attribute.

To
remove an attribute, use the remove-attr transformation
action.

Construct an attribute value. This
action enables you to create an attribute value from other attribute values.

To create an attribute value, use the add-attr-value transformation
action.

Delete an attribute value. This
action enables you to remove the value from an attribute. It is usually used
to remove one or more values from a multi-valued attribute if either the client
application or the data source schema does not permit multi-valued attributes.

To remove an attribute value, use the remove-attr-value transformation
action.

Add a default value to an attribute. This
action enables you to add a default value to an attribute, if no value exists.

To add a default value to an attribute, use the def-value transformation
action.

Map one attribute value to another. This
action enables you to have two different values for an attribute, depending
on whether the attribute is being written to a data source or returned to
a client application.

To map attribute values, use the attr-value-mapping transformation action, with the internal-value and view-value parameters.

The results of a transformation action depend on the transformation
model.

Transformation Parameters

Transformation parameters provide the value of a virtual attribute.
This value can either be a default value, or rule that creates the value from
other attribute values.

The following transformation parameters are accepted:

value. This parameter is applied
to all transformation actions that add an attribute value, other than the attr-value-mapping action.

internal-value:value. This parameter
applies only to the attr-value-mapping action, and to the remove-attr-value action when used with the mapping model.
It describes the value of the attribute that is written to or read from the
physical data source.

view-value:value. This parameter
applies only to the attr-value-mapping action, and to the remove-attr-value action when used with the mapping model.
It describes the value of the attribute that is returned to or sent by the
client application.

Transformation parameters take the following syntaxes:

Constant. Used to generate
an attribute with a static default value.

For example, the parameter 0800–5994654 might be used to provide a default telephone
number.

Attribute value. Used to
create a new attribute from an existing attribute in the entry that is being
processed.

For example, the parameter \${cn} specifies
that the value of the new attribute must be taken from the value of the cn attribute The escape character is required before the $.

Constant and attribute value. Used
to create a new attribute by combining an existing attribute and a static
value.

For example, the parameter \${cn}@example.com specifies
that the value of the new attribute must be taken from the value of the cn attribute and a static domain name.

Macro. Used to create an
attribute by manipulating the value of an existing attribute.

Transformation Examples

The following sections provide use cases in which virtual data
views are required, and the combination of transformation models and actions
required to implement the use cases.

Example 18–4 Adapting an ADAM Object Class For
LDAP Compliance

An organization, Example A, stores its users in an LDAP directory. Example
A acquires another company, Example B, which stores its users in an ADAM directory.

In Example A's LDAP directory, a user is stored as an inetOrgPerson. In Example B's directory, a user is stored as a user.
A transformation is required that maps the ADAM user object
class to the LDAP inetOrgPerson object class.

The following transformation is defined on the physical data view of
Example A's directory:

Example 18–5 Constructing an Attribute With a Write
Transformation

Example A stores user entries in its directory. All user entries require
a mail attribute. If user entries without a mail attribute
are added, a schema violation error is returned. Example A has a client application
that adds user entries to the directory. Some user entries do not contain
a mail attribute and the client application is incapable of generating one.
To avoid schema violations when a user entry is added, a transformation is
defined that adds the mail attribute to an add request. The value of the mail attribute is taken from the uid provided
in the client add request, with the addition of @example.com.

The following diagram indicates the transformation that occurs on an
add request.

This transformation is defined on the physical data view by using the
following dpconf command.

In this command, \${uid} means the value of the uid attribute for that entry.

Example 18–6 Constructing an Attribute With a Read
Transformation

Example A does not store the mail addresses of its users in its directory.
However, a new client application requires that a user's mail address be returned
with the user entry.

All mail addresses in the organization take the form firstname.lastname@example.com.
The organization defines a virtual view in which the mail attribute is added
to each user entry for reads only. The value of the mail attribute is generated
by taking the value of the givenName and sn attributes
that already exist in the user entry.

The following diagram indicates the transformation that occurs on user
entries when they are returned in a search.

This transformation is defined on the physical data view by using the
following dpconf command.

Example 18–7 Adding a Default Attribute Value

Example A stores a number of products in its directory. In the past,
each product was associated with a support person, an employee responsible
for handling all support calls for that product. In the physical data store,
each product is therefore associated with a supportPerson attribute,
whose value is the DN of an employee in the organization.

The organization has changed its business process for support queries
and now sends all product queries to a central hotline. To handle this change
without changing the physical data, the organization defines a virtual data
view where all product entries do not have a supportPerson attribute,
but have a hotline attribute instead. The value of the hotline attribute is an 0800 number that is the same for all products.

The following diagram indicates the transformation that occurs on product
entries when they are returned in a search.

This transformation is defined on the physical data view by using the
following dpconf commands:

Example 18–8 Using a Virtual Transformation to Rename
a DN

Example A has a client application that needs to sort entries according
to their object class.

To do this, Example A defines a virtual transformation that rewrites
the RDN of entries to include the object class of the entry along with its cn, whenever an entry is returned to that specific client application.

The following transformation is defined on the physical data view of
Example A's directory:

Additional Virtual Data View Properties

In addition to the transformation actions described previously, certain
properties can be defined on a data view, which restrict the way in which
data can be managed through that data view. These properties essentially provide
a list of the attributes that can be read or modified through the virtual
data view.

The following additional properties can be defined on a data view to
present a restricted virtual data view:

Non-viewable attributes.A list of the attributes
that cannot be read through this data view. This list is specified by adding
the multi-valued property non-viewable-attr to the data
view. This property should be used if the number of attributes that cannot
be read is small.

Non-writable attributes.A list of the attributes
that cannot be added or modified through this data view. This list is specified
by adding the multi-valued property non-writable-attr to
the data view. This property should used if the number of attributes that
cannot be added or modified is small.

Viewable attributes.A list of the attributes
that can be read through this data view. This list is specified by adding
the multi-valued property viewable-attr to the data view.
This property should used if the number of attributes that can be read is
small.

Writable attributes.A list of the attributes
that can be added or modified through this data view. This list is specified
by adding the multi-valued property writable-attr to the
data view. This property should used if the number of attributes that can
be added or modified is small.

Join Data Views

A join
data view is an aggregation of multiple data views. The
current release of Directory Proxy Server supports the aggregation of two data
views into one join data view.

A join data view is created by specifying its name and the two existing
data views that will be aggregated. One of these existing data views is considered
the primary data view, and the other the secondary data view. Before you create the join data view, you need to configure
the rules on the secondary data view that determine how the data is aggregated.

The following figure shows the aggregation of a primary and secondary
data view to form one join data view.

Primary and Secondary Data Views

The hierarchical organization of the sources for a join data view
enables Directory Proxy Server to make default decisions where the data from the
primary and secondary data views do not match.

The primary data view controls the existence of entries in the join
data view. The secondary data view provides supplementary data for this list
of entries. In other words, if an entry exists in the secondary data view
but not in the primary data view, it does not appear in the join data view.

The primary data view is the authoritative source by default. When an
attribute is present on both source data views but has a different value on
each, a multi-valued attribute is returned. This behavior is configurable,
however. For example, you can choose to accept only the value in the primary
data view, or only the value in the secondary data view.

Additional Secondary Data View Properties

In addition
to the virtual data view properties described in Additional Virtual Data View Properties,
certain properties can be defined only on a secondary data view. These properties
determine how data from the two views is aggregated and how requests to the
data views are handled. The following sections describe these additional properties.

Join Rules

Join rules determine
how an entry from a secondary data view relates to an entry from a primary
data view. Join rules are not mandatory on a secondary data view. However,
if no join rule is defined, the secondary data view is not queried during
LDAP operations. Directory Proxy Server provides two types of join rules, DN join
rules and filter join rules.

DN Join Rules

A DN join rule
determines the DN of entries in the secondary data view. A DN join rule is
configured on the secondary data view by using the dn-join-rule property.
Only one DN join rule can be configured on a secondary data view. If a DN
join rule is configured on a data view, a filter join rule cannot be configured
on that data view.

A DN join rule has DN syntax and can take one of the following forms:

The DN of the secondary entry is constructed from an attribute
in the primary entry.

For example, the following DN join rule
stipulates that the DNs of entries in the secondary data view should include
the cn from the primary data view, plus the ou=people suffix.

cn=\${primary-data-view.cn},ou=people

The DN must not contain the base DN of the secondary
data view. In this sense, it is a relative DN.

The DN of the secondary entry is the same as the DN of the
primary entry.

The syntax of such a join rule is as follows:

\${primary-data-view.dn}

In this case, the portion of the primary and the secondary DNs below
the base DN are identical, although the full DNs may differ. Imagine, for
example, that the primary data view has a base DN of o=primary and
the secondary data views has a base DN of o=secondary.
A join rule of \${primary-data-view.dn} implies
that the DITs below the base DN are identical. So, the entry uid=1,o=secondary would be associated with uid=1,o=primary.

Filter Join Rules

A filter
join rule defines the relationship between the primary and secondary data
views. A filter join rule is configured on the secondary data view by using
the filter-join-rule property. This rule indicates how
an entry should be retrieved from the secondary data view based on something
in the primary data view.

Only one filter join rule can be configured on a secondary data view.
If a filter join rule is configured on a data view, a DN join rule cannot
be configured on that data view. A filter join rule takes the form of a filter
that is used to construct an attribute from one or more attributes from the
primary data view.

For example, the following filter join rule stipulates that an entry
be retrieved if the entry uid in the primary data view
matches the entry uid in the secondary data view.

uid=\${primary.uid}

Handling of Shared Entries

The contains-shared-entries property determines what should be done
if an entry in the secondary data view is used by more than one entry in the
primary data view.

Imagine for example, that the primary data view contains a list of user
entries and the secondary data view contains a list of department numbers.
A single department number in the secondary data view might apply to more
than one user in the primary data view. If a user is deleted from the primary
data view, you do not necessarily want that user's department number to be
deleted from the secondary data view.

The contains-shared-entries property is set on the
secondary data view only. This property is set to TRUE by
default. This means that deleting an entry in the primary data view will not
result in the deletion of the shared entry in the secondary data view. Adding
an entry to the primary data view will only add the entry to the secondary
data view if it does not already exist.

Handling of Binds

The process-bind property specifies whether a bind can be performed
on the secondary data view.

By default, primary data views allow binds and secondary data views
do not. The process-bind property is not set by default.
If this property is set to true on a secondary data view,
binds are permitted on that data view.

If an attribute exists on both the primary and secondary data view,
the attribute values are merged by the join data view. For read operations,
this implies that a multi-valued attribute is returned, with the values from
both data views. For write operations, the proxy queries both data views and
determines where to write the value based on the content of the write operation.

If one backend data source fails during an add operation Directory Proxy Server performs
an automatic rollback. The roll back takes the form of a delete operation
on the data source that did not fail. This ensures the consistency of the
data between the two data sources. If a roll back cannot be performed, an
error is logged and an optional administrative alert is raised. Automatic
roll back is on by default. You can configure automatic roll back by setting
the revertAddOnFailure attribute to off (directly
in cn=config).

If one backend data source fails during a delete operation, no roll
back is performed. An error is logged and an optional administrative alert
is raised.

Virtual Data Transformations on
Join Data Views

Virtual data transformations are described in Virtual Data Transformations.
The syntax of a transformation parameter differs slightly if the data transformation
is defined on a join data view. Because an attribute can be obtained from
more than one data view, variables that define the attribute content must
be fully qualified. That is, the source attribute value
must include the name of the data view from which the attribute is taken.

For example, the following parameter creates an attribute from existing
attributes in both the primary and secondary data views:

JDBC object class. Maps
one or more JDBC tables to an LDAP object class.

JDBC table. Defined for
each relational database table.

JDBC attribute. Defines
an LDAP attribute from a specified column in a JDBC table.

The following diagram shows how an LDAP client application is able to
view an Oracle database in the format of an LDAP DIT, through the configuration
of the JDBC objects described previously. These objects are discussed in more
detail in the following sections.

An LDAP client application can also bind to a JDBC
data view, or to a join data view that includes a JDBC data view. In this
case Directory Proxy Server obtains the password from the JDBC database to do
the password check. The password can be obtained in clear, SHA, or SSHA.

JDBC Data Sources and Data Source Pools

A JDBC data source is
defined for each relational database. The properties of a JDBC data source
include the name and location of the relational database, and the user name
and password required to access the database. For a complete list of the properties
that can be set for a JDBC data source, run the following command:

Currently, only one JDBC data source is supported for each JDBC data
view. In other words, you cannot load balance across JDBC data sources.

Like LDAP data sources, JDBC data sources are organized into data source
pools. The properties of a JDBC data source pool are similar to those of an
LDAP data source pool. For more information about LDAP data source pools see LDAP Data Source Pools.

Note –

Directory Proxy Server relies on metadata retrieved from the relational
database. This metadata is read when Directory Proxy Server starts, or when a
new JDBC data view is added. The metadata is not reread each time Directory Proxy Server processes
a request. If you change the metadata in the relational database, you must
restart Directory Proxy Server to take the changes into account.

The metadata is changed when any of the following changes are made:

Changes to the structure of the database (adding or removing
tables, rows, or columns)

Changes to the case sensitivity of any column in a table

JDBC Object Classes

A JDBC object
class maps an LDAP object class to one or more relational database tables.
A JDBC object class works in a similar way to a join data view (see Join Data Views). Just as a join data view
has primary and secondary source data views, a JDBC object class can obtain
its information from more than one table. One table must be defined as the
primary table, and additional tables, if they exist, are defined as secondary
tables. The primary table controls the list of entries and additional information
on these entries is extracted from the secondary tables.

When you define a JDBC object class, you must specify the following
operands:

The name of the JDBC data view to which this object class
is attached.

The name of the JDBC object class.

The primary JDBC table from which the object class will obtain
its list of entries.

A DN pattern that controls how DNs are constructed in the
data view.

Optionally, one or more secondary JDBC tables.

JDBC Tables

A JDBC table must
be created for each relational database table that will be used in the JDBC
data view. When you create a JDBC table you specify the name of the table
in the relational database, and the name you want to assign to this table
in the JDBC data view.

The following properties apply to JDBC tables:

SQL table. (sql-table) Specifies the name of the relational database table.

This
value must be specified when you create the JDBC table but can be changed
if the SQL table name changes.

Single row table. (is-single-row-table) Specifies that an LDAP entry has only one matching row in the
relational database table.

Generally, performance is improved
if this property is set to true because there is no ordering
in the SQL request.

Shared entries. (contains-shared-entries) This property determines what should be done if a row in a secondary
table is used by more than one entry in the primary table.

Imagine
for example, that the primary table contains a list of user details and the
secondary table contains department numbers. A single department number in
the secondary table might apply to more than one user in the primary table.
If a user is deleted, you do not necessarily want that user's department number
to be deleted from the secondary table.

The contains-shared-entries property is set on secondary
tables only. If this property is set to TRUE, deleting
an LDAP entry will result in deletion of the user in the primary table but
not in the deletion of the corresponding row in the secondary table.

A filter join rule is mandatory on secondary
tables, and indicates how an entry should be retrieved from the secondary
table based on something in the primary table.

Only one filter join rule can be configured on each secondary table.
A filter join rule takes the form of a filter that is used to construct an
LDAP attribute.

For example, the following command creates a filter join on the secondary phone table. This rule stipulates that an entry be retrieved from
the phone table if the user_id field
in that table matches the id field in the employee table.

JDBC Attributes

JDBC attributes
map LDAP attributes to entries in relational database tables. The definition
of a JDBC attribute includes the name of the LDAP attribute, and the table
and column in which the corresponding information is located.

For example, the following command maps the employeeNumber attribute
to the ID field of the EMPLOYEE table.

LDAP syntax. (ldap-syntax) This property defines the syntax used to construct the LDAP attribute
from an entry in the relational database table.

Changes to JDBC
attribute syntax require a server restart before they are taken into account.

SQL column. (sql-column) The column in the relational database table from which the LDAP
attribute is obtained.

SQL syntax. (sql-syntax) This property defines the syntax used to construct an entry in
the relational database table from an LDAP entry.

Case Sensitivity in JDBC Data Views

In some cases, the LDAP attribute might be case insensitive,
while the corresponding column in the relational database is case
sensitive. Directory Proxy Server handles this by adding an UPPER keyword to equality and substring indexes. This can have serious
performance implications. If the relational database requires case-sensitivity,
you should therefore create specific indexes on the upper case values.

Access Control On Virtual Data Views

In
a virtual data view, Directory Proxy Server exposes virtual data. Directory Proxy Server is
therefore responsible for controlling who can access that data, and what parts
of the data can be accessed. To control access to virtual data, you can define
virtual ACIs. When Directory Proxy Server receives a request on a virtual data
view, it uses the virtual ACIs, and any authentication information provided
by the user, to allow or deny access to the information that is requested.

Virtual ACI Definition

Virtual ACIs are defined by using the dpsaci operational
attribute. The dpsaci attribute is multi-valued. This means
that several ACIs can be defined for the same portion of a directory.

Directory Proxy Server is responsible for the management of the dpsaci attribute. This attribute can be configured along with the physical
data but it is not stored with the data. When the dpsaci attribute
is included in a request, Directory Proxy Server extracts it from the request
and manages it in a dedicated ACI repository, through its own ACI data view.

A modify request that targets a virtual data view and contains the dpsaci attribute is effectively split into two requests by Directory Proxy Server.
The first request handles only the virtual data, and the second request handles
the virtual ACI.

Note –

By default, write operations are forbidden on non-LDAP data views.

Global ACIs

Global ACIs are defined
in the entry cn=data-source-name,cn=virtual
access controls. These ACIs are evaluated by an ACI engine to deny
or allow requests from a connection handler using that ACI pool. Global ACIs
are required to allow or deny application administrators to access certain
data. These application administrators can then provide more finely-grained
access control to users, by placing ACIs directly in the data.

Only the proxy manager can create a pool of ACIs and manage ACIs directly
through the ACI data view. Application administrators cannot manage ACIs directly
through the ACI data view, even if they have the right to add entries. Application
managers can only manage ACIs directly through the data.

ACIs that are defined in the data itself, are evaluated by Directory Proxy Server.
These ACIs are entries in the pool of ACIs defined by the proxy manager, that
is they are child entries of the entry cn=data-source-name,cn=virtual
access controls.

ACIs have a performance impact. Therefore, if you use ACIs within the
data itself, keep to a minimum the number of rules in the global ACIs, because
these ACIs are evaluated every time the subtree is accessed.

The ACI repository is accessed through an LDAP or LDIF data view, depending
on the type of repository. By default, the access control data view is an
LDIF data view named virtual access controls. The view
base exposed by the access control data view must exist
in the ACI repository.

The ACI repository contains one or more pools of ACIs. An ACI pool is
defined by an LDAP entry of the type aciSource, directly
below the view base of the data view. The ACI pool is a subtree of entries.
It can contain access controls, and can be the parent entry of other entries
containing ACIs.

Virtual ACI Application

Virtual ACIs are applied per connection handler. The name of the ACI
pool to be used is defined as the aci-source property of
the connection handler. Virtual access controls are not evaluated if you bind
as the Proxy Manager.

Virtual Schema Checking

Directory Proxy Server exposes its own schema that is different to the schema
of a physical data source. The Directory Proxy Server schema can be stored locally
in an LDIF file, or in a remote Directory Server. You can configure where
the schema is stored with the dpconf command. A schema
is defined per connection handler. The schema for a specific
connection handler can be retrieved or updated using ldapsearch or ldapmodify. When the schema is updated, Directory Proxy Server must
be restarted before the changes take effect.

Schema Checking

Generally,
schema checking is performed by the server that exposes the schema. In a scenario
where Directory Proxy Server acts as a proxy to one or more Directory Servers,
the Directory Servers check that add and modify requests adhere to their
LDAP schema. When Directory Proxy Server exposes its own schema. Directory Proxy Server must
check that add and modify requests adhere to these schema.

Because a schema is defined for a specific connection handler, schema
checking is enabled per connection handler. Schema checking is enabled by
setting the schemaCheck attribute of a connection handler
to true.

Virtual Data Views and LDAP Groups

With virtual data views, you can define local virtual groups, and use
them though ACIs. You can also rely on existing groups defined on backend
servers. You can transform the groups from an LDAP directory to appear in
the virtual namespace by using DN mapping. You can also transform all member
DNs by using attribute value renaming.

With a join data view, you can join two static groups from two different
LDAP backends, as long as there are no member naming conflicts. You can also
create a read-only virtual group, by using an ACI on the uniquemember attribute,
for example.

Directory Proxy Server server uses groups in the area of ACIs only. The
ACI engine can reference both static and dynamic groups by using the groupdn keyword.

Virtual ACIs support both static and dynamic groups. However, the isMemberOf feature is not supported. Due to the severe performance
impact, nested groups are also not supported.

With dynamic groups, attribute value renaming does not apply to the
value of the dynamic group, because this value is an LDAP URL and is therefore
not DN syntax. In other words, if a dynamic group value contains a DN, the
DN part is not renamed.

LDAP Data Sources

The
connections between Directory Proxy Server and backend LDAP servers are configured
through LDAP data sources. An LDAP data source identifies
the name and port numbers of an LDAP server, and the authentication policy
that is applied by Directory Proxy Server when forwarding operations to the LDAP
server. LDAP data sources also configures how the LDAP server is monitored.

An LDAP data source can be any LDAP v3 server. Certain advanced functionality
of Directory Proxy Server might rely on features that are available only in Sun's Directory Server,
but the configuration of this functionality is optional. For example, the “Get
Effective Rights” control in Sun's Directory Server is used by Directory Proxy Server for
proxied authorization.

The health of a backend LDAP server is monitored by testing the connections
between Directory Proxy Server and the backend LDAP server. For information about
how Directory Proxy Server monitors LDAP data sources, see How Data Sources Are Monitored.

At startup, Directory Proxy Server opens a connection to each data source
that is configured, and enabled.

When an error is detected on a connection, Directory Proxy Server closes
the connection and tries to reestablish it immediately. If Directory Proxy Server cannot
connect to a data source, the data source is considered unavailable. For more
information about how Directory Proxy Server responds to failed connections, see Responding to the Failure of a Data Source.

Connections between Directory Proxy Server and backend LDAP servers are
pooled for use with multiple client requests. Each data source can have one
pool of SSL connections and one pool of non-SSL connections. The ssl-policy property of the data source and the is-ssl-mandatory property
of the connection handler determine whether SSL is used when contacting the
data source.

The number of connections that can be opened to a data source can be
configured independently for BIND, READ, and WRITE operations. The same limit
applies to SSL connections and to non-SSL connections.

The following properties can be configured for each data source and
for each type of operation:

The initial number of connections made to the data source

If more than the initial number of connections are requested,
the number of new connections made

The maximum number of connections that can be made to the
data source

When BIND replay is configured, Directory Proxy Server attempts to reuse
connections that have already been opened, to optimize performance. If a client
opens an authenticated connection, the connection is taken from the BIND pool.
Therefore, when BIND replay is used, the connection pool for BIND operations
is used more than the connection pools for READ or WRITE operations. For more
information about BIND replay, see Directory Proxy Server Configured for BIND Replay.

When a connection to a data source is not used for 5 minutes, the connection
is removed from the pool.

Directory Proxy Server Configured for BIND Replay

Directory Proxy Server forwards
a BIND request from a client and the credentials of the client to an LDAP
server. If the BIND is successful, all subsequent requests from the client
to that LDAP server are processed with the authorization of the client.

In BIND replay, if the client makes a subsequent request that is forwarded
to another LDAP server, the Directory Proxy Server uses the credentials already
provided by the client to BIND to the other LDAP server before forwarding
the request.

If a client request contains a proxy authorization control, Directory Proxy Server forwards
the control to the backend server.

The following figure shows client identity and credentials being used
for authorization by BIND replay.

Figure 19–1 Authentication in BIND Replay

When Directory Proxy Server is initiated, it opens a connection to each
LDAP server. When a client connects to Directory Proxy Server it makes requests
in the following stages:

The client requests a BIND, and provides a DN and a password.

Directory Proxy Server authenticates the client to LDAP server
1 by using the client's credentials. An entry for the client exists in LDAP
server 1 and the BIND request is granted.

The SEARCH request is performed with
the authorization of the client. If the client request contains a proxy authorization
control, the request is processed with authorization of the user specified
in the proxy authorization control.

If the client sends more SEARCH requests that are targeted at LDAP server
1, the Directory Proxy Server forwards the request without performing additional
binds.

The client sends a SEARCH request targeted at LDAP server
2

The Directory Proxy Server authenticates the client to LDAP server
2 by using the client's credentials obtained in Step 1. An entry for the client
exists in LDAP server 2 and the BIND request is granted.

When Directory Proxy Server is configured for BIND replay, authentication
by SASL external bind cannot be used . In BIND replay, Directory Proxy Server authenticates
the client to a backend LDAP server by using the client DN and password. In
SASL external bind, no password is provided by the client. Furthermore, the
password that is stored in the user entry cannot be read in clear text.

For performance reasons, you should configure Directory Proxy Server to
use BIND replay only when the extra configuration required for proxy authorization
is not feasible, or where proxy authorization is not supported. For information
about proxy authorization, see Directory Proxy Server Configured for Proxy Authorization

Directory Proxy Server Configured for Proxy Authorization

When Directory Proxy Server is
configured for proxy authorization, Directory Proxy Server can add a proxy authorization
control to a client request. The client request is then forwarded with the
authorization of the specified in the proxy authorization control.

To simplify the configuration of ACIs, Directory Proxy Server can be configured
to allow anonymous reads and to apply proxy authorization for write operations.

If Directory Proxy Server is configured for proxy authorization and the
client request contains its own proxy authorization control, Directory Proxy Server does
not add a proxy authorization control. In this case, Directory Proxy Server checks
with the backend LDAP server that the client has the right to use its proxy
authorization control. If the client has the right to use its proxy authorization
control, Directory Proxy Server forwards the request with the authorization specified
in the client's proxy authorization control.

Connections When Directory Proxy Server Is Configured
for Proxy Authorization

When Directory Proxy Server is configured for proxy authorization, a client
is usually authenticated to the Directory Proxy Server by a non-anonymous BIND
or by a SASL external BIND, however, clients can also be anonymous. Directory Proxy Server is
usually bound to the data sources by using an administrative identity.

Figure 19–2 Connections for Proxy Authorization

The connections for proxy authorization are made in the following stages:

When Directory Proxy Server is initiated, it opens a connection
to each LDAP server. Directory Proxy Server binds to LDAP server 1 and LDAP server
2 by providing its DN and password, DPSbindDN and DPSbindPW.

An entry for DPSbindDN exists
in both the LDAP servers and the BIND requests are granted. Directory Proxy Server is
bound to the LDAP servers, on connection 2 and connection 3.

When a client connects to Directory Proxy Server, the client binds
by providing its DN and a password, clientDN and clientPW.

The Directory Proxy Server authenticates the client to LDAP server
1 by using the client's credentials and by reusing connection 2.

An
entry for the client exists in LDAP server 1 and the BIND request is granted.
The client is bound to Directory Proxy Server on connection 1.

Directory Proxy Server Configured for Proxy Authorization
and the Client Request Does Not Contain a Proxy Authorization

The client sends a SEARCH request SEARCH 1,
that does not contain a proxy authorization control. The request is targeted
at LDAP server 1.

Directory Proxy Server adds a proxy authorization control to the
request and forwards the SEARCH operation to LDAP server 1, reusing connection
2.

The SEARCH operation is performed with the authorization of
the user specified in the proxy authorization control. That authorization
is defined in the RW ACIs on the LDAP server for the user specified in the
proxy authorization control.

The client sends a second SEARCH request, SEARCH
2, that does not contain a proxy authorization control. The request
is targeted at LDAP server 2.

Notice that it is not necessary
for the client to bind to LDAP server 2 before the request can be processed,
and it is not necessary for the LDAP server to contain an entry for the client.

Directory Proxy Server Configured for Proxy Authorization
and the Client Request Does Contain a Proxy Authorization

Figure 19–3 shows the flow of
information when the client in Figure 19–2 makes
a request that does contain a proxy authorization control. Directory Proxy Server verifies
that the client has the right to use its proxy authorization control.

Figure 19–4 Information Flow When Proxy Authorization Control
Is Contained in the Client Request

The client sends a SEARCH request SEARCH 1,
that contains a proxy authorization control. The request is targeted at LDAP
server 1.

Consider the following security risks before configuring Directory Proxy Server for
proxy authorization:

When Directory Proxy Server is configured for proxy authorization,
it assumes the rights of any client for which it forwards a request. A Directory Proxy Server that
is not authorized to perform write operations on data, can perform those operations
by using proxy authorization.

An LDAP server must contain an entry with the appropriate
R/W ACIs for the user specified in the proxy authorization control. If the
entry was accessed illegally by a third party, that party might be able to
impersonate.

The authorization identity configured in the proxy authorization
control must be protected from tampering.

In some deployment scenarios, it is not necessary to maintain the identity
of a client when the client makes request. Directory Proxy Server can be configured
to forward requests to LDAP servers without the client identity. The LDAP
servers process the requests with the identity and authorization of the Directory Proxy Server.

Client requests
can be performed with the identity of an alternate user by using the feature
called user mapping. In user mapping, the client identity
is mapped to the identity of an alternate user. After a BIND operation, the Directory Proxy Server submits
subsequent operations as the alternate user.

When a client identity is mapped to another identity, requests from
that client can be forwarded to the backend LDAP servers by using BIND replay
or by using proxy authorization.

Client identities can be mapped to alternate identities either locally
on the Directory Proxy Server or remotely on an LDAP server. Figure 19–5 and Figure 19–6 illustrate
local mapping and remote mapping.

Figure 19–5 Local Mapping of a Client Identity to an Alternate
Identity

In local mapping, the identity mapping is configured in the Directory Proxy Server.
The configuration cannot be changed without reconfiguring the Directory Proxy Server.
Local mapping can be configured for unauthenticated clients, authenticated
clients, and for clients authenticated by proxy.

In remote mapping, the identity mapping is configured in an entry in
the remote LDAP server. The mapping can be changed by modifying the entry
in the remote LDAP server. It is not necessary to reconfigure the Directory Proxy Server to
change the mapping. Remote mapping can be configured for unauthenticated clients
and for clients authenticated by proxy.

Remote mapping must not be used for data sources configured for BIND
replay. In BIND replay, the Directory Proxy Server forwards a client request by
using the authentication provided in the BIND operation. However, in remote
mapping the client DN and password provided in the BIND operation are mapped
to an alternate DN and password. The client's password cannot be retrieved
from the backend LDAP sever.

If the user mapping is enabled but the mapping fails, the client identity
is mapped to a default identity. A user mapping can fail when a client identity
is mapped to a non-existent alternative identity or when there has been a
configuration error.

Chapter 20 Connections Between Clients and Directory Proxy Server

All the
incoming connections to Directory Proxy Server are categorized into connection
handlers according to a set of criteria. A connection handler defines the
resource limits and request filters that apply to the connection, and the
data views that are exposed to the connection.

Criteria for Allocating a Connection to a Connection
Handler

An instance of Directory Proxy Server can have many connection handlers.
When a client connects to Directory Proxy Server, the proxy evaluates whether
the attributes of the connection match the criteria of one of the connection
handlers. When a match is found, the connection is classified into that connection
handler. All of the policies defined for that connection handler apply to
the connection. Operations performed through that connection are exposed to
all of the data views or to a list of data views defined by the connection
handler.

After being classified into a connection handler, a connection can be
automatically reclassified into another connection handler by Directory Proxy Server.
For example, if a client connects anonymously, the connection is allocated
to the connection handler configured for anonymous connections. If the client
later provides a bind DN on the same connection, the connection can be reallocated
to another connection handler. Similarly, a non-secure LDAP connection is
initially classified into a connection handler for non-secure connections.
If the client uses startTLS to promote the connection to secure mode, the
connection is automatically reclassified into a connection handler for secure
connections.

A connection is evaluated against connection handlers in order of the
priority of the connection handler. Priority one is the highest priority connection
handler. The connection is classified into the first connection handler for
which there is a match. Connection handlers with the most specific criteria
should have a higher priority than those with less specific or more general
criteria. For example, a connection handler that specifies a bind DN should
have a higher priority than a connection handler that specifies a simple bind.

If a connection does not match the criteria of any configured connection
handler, the connection is allocated to the default connection
handler. The criteria of the default connection handler cannot
be modified. In addition, the default connection handler cannot be disabled
or deleted. However, the policies and data views of the default connection
handler can be changed.

The default connection handler is the lowest priority connection handler.
If a new connection handler is created without a priority, the new connection
handler is given a higher priority than the default connection handler. If
two connection handlers have the same priority, the order in which the connection
is evaluated against them is not specified.

The criteria expression of a connection handler is a logical AND between
criteria of different types and a logical OR between criteria
of the same type. For example, if a criteria is specified for client IP address
and a criteria is set for client domain name, both of the criteria must be
met. However, if two criteria are set for client IP address, either, not both,
of the criteria must be met.

Client IP address and mask. A
set of IPv4 or IPv6 address masks. The IP address of a client connection must
match at least one of the masks in order for the connection to be accepted
by the connection handler.

The IP address can be in one of the following formats:

IP address in dotted decimal form. For example, 129.153.129.14.

IP address and bits, in the form of network number/mask
bits. For example, 129.153.129.0/24.

IP address and quad, in the form of a pair of dotted-decimal
quads. For example, 129.153.129.0/255.255.255.128.

All addresses:ALL, a catch-all for clients
that are not placed into other, higher priority, groups.

0.0.0.0. This address is for groups for
which initial membership is not considered. For example, for groups that clients
switch to after their initial bind.

IP address of the local host. IP address 127.0.0.1 is
the IP address of a client that is running on the same machine as Directory Proxy Server.

Client domain name. A set
of domain names. A client network domain must match at least one of the suffixes
in order for the connection to be accepted by the connection handler.

In order to be able to filter the client's domain name, Directory Proxy Server must
be able to convert the incoming IP address into the fully qualified domain
name. If the naming service returns a hostname without the domain name, Directory Proxy Server cannot
filter the client's domain name.

Directory Proxy Server does not assume any domain suffix, therefore the
fully qualified domain name must be provided. A domain name suffix with a
leading period, for example, .sun.com, will cause all hosts
with domain names that end in that suffix to match.

The domain name can be in one of the following formats:

Full name, for example, box.eng.sun.com.

Suffix name, for example, .eng.sun.com.
If the suffix name is used to identify clients, ensure that DNS is set up
to return fully qualified names to the DNS queries.

Fully qualified name of the local host. This criteria is for
a client that is running on the same machine as Directory Proxy Server.

Bind DN. A regular expression
that must be matched by the bind DN of a client.

For example,
the following regular expression could be used as a bind DN criteria for a
connection handler: uid=(.*),dc=example,dc=com. A client
that binds with a uid such as uid=user1,dc=example,dc=com matches the criteria and can be allocated to the connection handler.
A client that binds with another DN such as ou=accounts,dc=example,dc=com does not match the criteria and cannot be allocated to the connection
handler.

LDAP search filter. A search
filter that the entry of a bound client must match.

For example,
the following filter could be used as a criteria for a connection handler: uid>=1000. Bound clients with a uid that matches
the filter can be allocated to the connection handler.

Authentication method. An
authentication method that must match the client entry in order for the connection
to be accepted by the connection handler.

The authentication method can be one of the following:

SIMPLE

SASL/EXTERNAL

Anonymous

IP port. A set of IP port
numbers. A client connection must come through one of the specified ports
in order for the connection to be accepted by the connection handler.

SSL connection. A flag
indicating whether or not client connections must use SSL in order to be accepted
by the connection handler.

Data Views for Connection Handlers

When a connection
is allocated to a connection handler, requests on the connection are exposed
to a list of data views configured for that connection handler. The list of
data views for a connection handler can contain zero, one, or multiple data
views.

If the list of data views is empty, requests on the connection are not
distributed to any data view. Applications using the connection cannot access
any data and a No such Object error is returned.

If the list of data views contains multiple data views, requests on
the connection are distributed to the data view that most specifically corresponds
to the target DN of the request. For example, in Figure 20–1, requests on a connection in connection-handler-1 can
be distributed to data-view-2, data-view-3 or data-view-4. However, if a search request has a target DN of ou=people,dc=example,dc=com, the request is distributed either to data-view-3 or
to data-view-4.

Figure 20–1 List of Data Views in a Connection Handler

Affinity can be defined between a client connection and the data view
selected to respond to requests on that connection. This feature is called data view affinity. When data view affinity is enabled, successive
requests on a client connection are exposed exclusively to the data view used
for the first request on that connection.

When data view affinity is enabled it takes precedence over other types
of routing. For example, in Figure 20–1,
a search request with a target DN of ou=computer,dc=example,dc=com is
exposed to data-view-2. All subsequent requests on that
client connection are exposed exclusively to data-view-2.
If a subsequent request on that client connection has a target DN of ou=people,dc=example,dc=com, the request is exposed to the data view for ou=computer,dc=example,dc=com, not the data view for ou=people,dc=example,dc=com.

Resource Limits Policies for Connection Handlers

A resource limits policy defines the maximum resources that Directory Proxy Server can
process for a given connection handler. By using this type of connection handler
policy, you can limit the resources allocated to connections, requests, and
referrals.

The following list summarizes the resource limits that can be configured:

Connections

Maximum number of connections.

Maximum number of simultaneous connections from a single client.

Maximum number of operations per connection. If a client exceeds
the maximum number of operations on one connection, the connection is closed
by Directory Proxy Server.

Maximum number of simultaneous operations per connection.

If the maximum number of simultaneous operations per connection is 1, clients must perform synchronous operations. Additional requests
for simultaneous operations, except for requests to abandon an operation,
will fail with a Server Busy error.

Customized Search Limits

Customized limits can be defined for search operations, based on the
search base and search scope. If the target DN of a search is specified in
a list, and the scope of a search is one-level or subtree, the maximum size
of the search result can be configured.

Custom search limits are defined for a specific resource limits policy.
If the resource limits policy is deleted, the custom search limits defined
for that policy are also deleted. If custom search limits are not specified,
standard search size limits are applied.

Request Filtering Policies for Connection Handlers

Request filtering policies control access of clients to data. A connection
handler can reference zero or one request filtering policy.

The following aspects of client access can be defined by using this
type of connection handler policy:

The types of operation that clients are allowed to perform
or are prohibited from performing.

Each of the following types
of operation can be allowed or prohibited: add, bind, compare, delete, extended
operations, modify, modify DN, search, and search based on inequality filters.

Attributes that are allowed or prohibited from being used
in search filters and compare operations.

All attributes can be
permitted in search filters and compare operations, or a list of attributes
can be permitted or prohibited.

The scope of search operations.

The scope can
be the base DN, one level below the base DN, or the entire subtree below the
base DN.

The subtrees that clients are allowed to access or are prohibited
from accessing.

Subtrees in the Request Filtering Policy

The request filtering policy is configured with one or more allowed
subtrees and zero, one, or more prohibited subtrees. The subtrees identify
the part of a data view that can be accessed by clients.

Allowed Subtrees

An allowed subtree is specified by a minimum base DN. Clients are permitted
to perform operations on entries at the minimum base DN or below the minimum
base DN. By default, the minimum base DN is the root DN.

If a client requests a search operation that is targeted at a DN superior
to the minimum base DN, Directory Proxy Server rewrites the DN to target the minimum
base DN. If a client performs any other operation that is targeted at a DN
superior to the minimum base DN, the operation is denied.

Prohibited Subtrees

A prohibited subtree is a branch of the allowed subtree that cannot
be accessed by the client. The base DN of a prohibited subtree must be subordinate
to the minimum base DN of an allowed subtree. If a client performs an operation
that is targeted at a prohibited subtree, the operation is denied.

Search data hiding rules are defined for a given request filtering policy
and cannot be used by another request filtering policy. If a request filtering
policy is deleted, its associated search data hiding rules are automatically
deleted. Zero, one or multiple search data hiding rules can be defined in
one request filtering policy.

Client Authentication Overview

From a protocol perspective, client authentication can occur at two
levels:

LDAP level. Authentication
occurs in the LDAP bind operation.

Connection level. Authentication
occurs in the network connection established between the client and Directory Proxy Server.

Directory Proxy Server can also be configured to accept client requests
without authentication.

The following list summarizes the supported authentication options.
These options are discussed in more detail in the remainder of this chapter.

Simple bind authentication.Simple
bind authentication occurs at the bind level. When the client binds, it provides
a unique name (bind DN) and password to Directory Proxy Server. Directory Proxy Server forwards
these credentials, along with the bind request, to a backend LDAP server.

Simple bind authentication can also be made over a secure connection.
However, the server still identifies the client from its bind DN.

Certificate-based authenticationCertificate-based authentication occurs at the connection level
when the connection is secure. When authentication occurs at the connection
level, the client connects over an encrypted (SSL) connection and provides
a certificate. Directory Proxy Server checks the validity of the client certificate
and maps the certificate to an LDAP DN.

No authentication.If
the client does not provide a certificate, or a bind DN and password, no authentication
occurs. In this case, the client connects to Directory Proxy Server anonymously.
This is known as anonymous access.

Simple Bind Authentication

Simple bind authentication is the most common way to authenticate LDAP
clients. In a simple bind, the client either binds anonymously, that is, with
an empty bind DN, or by providing a DN and a password. Directory Proxy Server binds
to a data source to validate the credentials and to authenticate the client.
An entry for the client must exist on the data source, otherwise the client
is considered to be anonymous. When a client is authenticated, Directory Proxy Server records
the identity of the client.

Directory Proxy Server is configured for simple bind authentication by default.
No additional configuration is required. Because the client provides a password
to Directory Proxy Server, simple bind authentication is also known as password-based
authentication.

For LDAP data views, Directory Proxy Server relies on the backend LDAP server
for password encryption and verification. When a client modifies a password
by using an ADD or MODIFY operation, the backend LDAP server can apply a password
encryption policy when it stores the password. When the client issues a BIND
request, the backend LDAP server is responsible for verifying the password.

For LDIF and JDBC data views, Directory Proxy Server is responsible for
password encryption and verification.

LDIF data views. When a client modifies a password, Directory Proxy Server applies
the encryption policy defined by the db-pwd-encryption property
of the data view. The encryption policy can be PLAIN, SHA, or SSHA. The password is still stored in
the data source, that is, in the LDIF file.

When encrypted passwords are stored, the encrypted value is prefixed
by the encryption policy. So for example, a stored, encrypted password might
look like {SSHA}mcasopjebjakiue or {SHA}askjdlaijfbnja. When the client issues a BIND request, Directory Proxy Server verifies
the password and expects the encryption policy tag.

Certificate-Based Authentication

Certificate-based authentication over an SSL connection is the most
secure type of authentication. Therefore, when authentication occurs at the
connection layer, the client does not need to provide an additional name (bind
DN) and password to Directory Proxy Server during the LDAP bind.

A client can only perform certificate-based authentication over an SSL
connection. The basic steps in establishing an SSL connection are as follows:

The client requests that a secure connection be established.

As part of this request, Directory Proxy Server provides a server
certificate to the client. A server certificate is a single certificate
associated with one instance of Directory Proxy Server. When a secure connection
is used, the server certificate identifies the instance of Directory Proxy Server to
the client.

The establishment of the connection includes a negotiation phase. During
this phase, the client and Directory Proxy Server attempt to agree on the encryption
policy that is used. The server certificate contains the list of encryption
policies (ciphers) that are supported by the Directory Proxy Server.

Depending on the security configuration of the proxy server,
the server might require the client to provide a certificate.

The client provides a certificate to the server, either because
the client is configured to do so, or because the proxy server has requested
it.

The client then sends an LDAP bind request to Directory Proxy Server to
establish the client's identity on that connection.

If the request is a simple bind, Directory Proxy Server uses the
bind DN and password provided by the client.

If the request is a SASL external bind, Directory Proxy Server does one
of two things:

Considers the subject of the certificate as the bind DN of
the client.

Maps the certificate by searching the backend server for an
entry that matches the received certificate. If the verify-certificates property
is set, Directory Proxy Server verifies that the received certificate is the one
stored in the entry that is found.

The following configuration
properties determine how Directory Proxy Server performs that search:

When a client provides a certificate to Directory Proxy Server, the server
verifies that certificate against the list of trusted CA certificates in its
certificate database. The verification is successful if the server's certificate
database contains the client certificate itself, or the CA certificate with
which the client certificate was generated.

The server certificate can be one of the following:

Self-signed certificate. A
public and private key pair, where the public key is signed by Directory Proxy Server.

Trusted CA certificate. A
single certificate that is automatically generated by the company’s
internal certificate server or by a known Certificate Authority (CA).

Directory Proxy Server also supports the use of a server certificate
chain. A server certificate chain is a collection of certificates
that are automatically generated by the company’s internal certificate
server or by a known CA. The certificates in a chain trace back to the original
CA, providing proof of identity. This proof is required each time you obtain
or install a new server certificate.

You can install any number of certificates on a server. When you configure
SSL for an instance of Directory Proxy Server, you must install at least one server
certificate and one trusted CA certificate.

Using SASL External Bind

When a client binds to Directory Proxy Server with
the Simple Authentication and Security Layer (SASL) external bind, Directory Proxy Server obtains
the credentials of the client from the certificate, rather than from the bind
DN.

The server obtains the credentials in one of two ways:

Considers the subject of the certificate as the bind DN of
the client

Maps the certificate subject to data within its own database,
to deduce the bind DN

SASL external bind cannot be used if Directory Proxy Server is configured
for BIND replay. In BIND replay, Directory Proxy Server authenticates the client
to a backend LDAP server by using the client DN and password. In SASL external
bind, no password is provided by the client. Furthermore, the password that
is stored in the user entry cannot be read in clear text. For information
about bind replay, see Directory Proxy Server Configured for BIND Replay.

SSL can be used to protect subsequent interactions between the client
and Directory Proxy Server.

Directory Proxy Server Client Listeners

Directory Proxy Server enables
you to configure certain aspects of a client connection through a client
listener. Two client listeners are provided, a secure listener
(ldaps-listener) and a non-secure listener (ldap-listener).

The secure listener specifies that the connection is made to a secure
port, over SSL. The non-secure listener specifies that the connection is made
to a non-secure port, without SSL. Clients use either the secure listener
or the non-secure listener, depending on the type of connection required by
that client.

Note –

A client can also establish a secure connection to a non-secure
port if the client supports Start TLS.

Both the secure and non-secure listener specify the following aspects
of a client connection:

is-enabled

Specifies whether clients are able to use that listener to
connect to Directory Proxy Server

listen-port

The port number on which Directory Proxy Server listens for client
connections

listen-address

The IP address of the listener

connection-idle-timeout

The maximum time a client connection can remain idle before
being closed

connection-read-data-timeout

The maximum time that a listener can wait for new data to
be available

connection-write-data-timeout

The maximum time that a listener can wait to send results
back to clients

max-connection-queue-size

The maximum size of a listener's connection queue

max-ldap-message-size

The maximum size of an LDAP message.

number-of-threads

The number of threads allocated to a listener to for simultaneous
client connections and requests

use-tcp-no-delay

Whether or not TCP_NODELAY is enabled for
connections between a client and Directory Proxy Server

How Directory Proxy Server Provides Security

Directory Proxy Server provides security through a combination of the following
methods:

Encryption

Encryption protects the privacy of information. When data is encrypted,
the data is scrambled in a way that only a legitimate recipient can decode. Directory Proxy Server supports
SSL encryption. For information about SSL, see Secure Sockets Layer for Directory Proxy Server.

Authentication

Authentication is a means for one party to verify another’s
identity. For example, a client gives a password to Directory Proxy Server during
an LDAP bind operation. Policies define the criteria that a password must
satisfy to be considered valid, for example, age, length, and syntax. Directory Proxy Server supports
anonymous authentication, password-based authentication, and certificate-based
authentication. For information about authentication, see Chapter 21, Directory Proxy Server Client Authentication.

Secure Sockets Layer for Directory Proxy Server

The Secure Sockets Layer
(SSL) provides encrypted communications between a client and Directory Proxy Server.
By using SSL with authentication, data sent to and from Directory Proxy Server can
be encrypted.

When an instance of Directory Proxy Server is created, SSL is enabled by
default and the following directories and files are created:

Directory Proxy Server supports the Start TLS extended operation. StartTLS
can be used to provide security over a regular LDAP connection. With StartTLS,
clients can bind to a non-secure port and then use the TLS protocol to initiate
a secure connection.

Ciphers and Protocols for Directory Proxy Server

The ciphers and protocols
that can be used by Directory Proxy Server depend on the JVM that is used. By
default, Directory Proxy Server uses the default ciphers and protocols for the
JVM.

You can retrieve a list of ciphers and protocols by using the dpconf command:

Enabled ciphers

The list of ciphers that are currently enabled for both the
LDAP and LDAPS listeners. Because the LDAP and LDAPS listeners are synchronized,
the properties are part of the global server configuration, and not the listener
configuration.

Supported ciphers

The list of ciphers supported by the JVM for Directory Proxy Server.

Enabled protocols

The list of protocols that are currently enabled for both
the LDAP and LDAPS listeners. Because the LDAP and LDAPS listeners are synchronized,
the properties are part of the global server configuration, and not the listener
configuration.

Supported protocols

The list of protocols supported by the JVM for Directory Proxy Server.

Note that the log message format is still evolving in this release of Directory Proxy Server.

Introduction to Directory Proxy Server Logs

The Directory Proxy Server logging service provides access logs and
error logs. The logs are flat files that contain information about client
operations and about the health of Directory Proxy Server. By default, log files
are stored under instance-path/logs with
the permission of 600. If an instance of Directory Proxy Server is
started without valid log files, log files are created in the default location
and a warning is sent to DSCC.

You can configure the following aspects of the logs:

Set the log level for each message category

Globally set the default log-level for all message categories

Globally enable all logs

Set the name, location and permissions of log files

Set the maximum number of log files

Define a rotation policy for each log file

Include or exclude search filters in access log messages for
search operations

Log File Rotation

Log files can be rotated manually at any time, or can be rotated
automatically when the following events occur:

When the log reaches a specified size

At a specified start-time, start-day, and interval

At a specified start-time, start-day, and interval, if the
log file is bigger than a specified size

The start-time, start-day, and interval can have the following combinations:

Time-of-day followed by an interval of days, hours, or minutes

Day-of-week and time-of-day, followed by an interval of weeks

Day-of-month and time-of-day, followed by an interval of months

The time-of-day takes precedence over the interval. For example, a log
that is specified to be rotated at 3am and then every 10 hours is rotated
at the following times: 03:00, 13:00, 23:00, and again at 03:00 (not 07:00).

If the log is configured for rotation on the 31st of the month but the
month has fewer than 31 days, the log is rotated on the first day of the following
month.

Log File Deletion

A log file deletion policy defines when backup log files are deleted.
The log file currently in use is never deleted by a deletion policy.

The following deletion policies can be enabled:

Deletion based on time. Log
files are deleted when they reach a specified age.

Deletion based on size. Log
files are deleted when the total size of all the log files reaches a specified
limit. The size of the current log file is taken into account, although this
file is not deleted.

Deletion based on free disk space. When
the free disk space reaches a specified minimum, the oldest backup log file
is deleted. If the free disk space is still lower than the minimum, the next
oldest backup log file is deleted, and so forth.

Message Severity

Messages are included in log files or filtered out of log files
according to the severity of the message, the category of the message, and
the log-level that has been configured for that category. The categories and
log-levels for the error logs and access logs are different, and are discussed
in the sections that follow.

Messages are ranked according to their severity. Messages can have one
of the following severities, where error is highest severity
and debug is the lowest severity:

error

warning

info

debug

Messages with a severity that is lower than the log-level configured
for its message category are not included in the log file. Messages with a
severity that is equal to or higher than the log-level configured for its
associated message category are included in the log file.

Error Logs for Directory Proxy Server

Error
logs contain information about the health of the Directory Proxy Server. Error
messages are categorized according to the cause of the message. The following
table lists the categories of messages that can be included in an error log.

Table 23–1 Message Categories for Error Logs

Category Name

Category Description

CONFIG

Information about configuration

DECODE

Information about operation decoding

PLUGIN

Information about plug-in processing

PROCESSING

Information about a significant event that occurred during client processing

BACKEND

Information about an operation with a data source

INTERNAL

Information about an internal error in the core server

SHUTDOWN

Information about an event at server shutdown

STARTUP

Information about an event at server startup

Error Log Levels

Each message category can be configured with one of the following log-levels:

none No messages are included in the log
file.

error Only error messages are included
in the log file.

warning Error messages and warning messages
are included in the log file.

info Errors, warnings and informational
messages are included in the log file.

all All messages are included in the log
file. In most cases, this setting produces the same results as the info setting.
In certain situations, this setting enables additional debugging messages
to be logged.

inherited The log level is inherited from
the value of the default-log-level property.

By default, the log level for each message category is info.

The log-level of a message category works in conjunction with the severity
level of a message to determine which messages are included in the log file.
For more information, see Message Severity.

Access Logs for Directory Proxy Server

Access logs contain information about the requests being processed
by Directory Proxy Server. Access logs contain information about two types of
connection:

Connections between clients and Directory Proxy Server

Connections between Directory Proxy Server and data sources

Access log messages are categorized according to the cause of the message.
The following table lists the categories of messages that can be included
in the access log.

Table 23–2 Message Categories for Access Logs

Category Name

Category Description

CONNECT

Information about a client connection

DISCONNECT

Information about a client disconnection

OPERATION

Information about operations requested by a client

PROFILE

Information about the profiles of a connection handler

SERVER_OP

Information about operations that are forwarded to data sources

SERVER_OP_DETAIL

Detailed information about operations that are forwarded to data sources

Access Log Levels

Each message category can be configured with one of the following log-levels:

none No access messages are included in
the log file.

info Informational messages are included
in the log file.

all All messages are included in the log
file. In most cases, this setting produces the same results as the info setting.
In certain situations, this setting enables additional debugging messages
to be logged.

inherited The log level is inherited from
the value of the default-log-level property.

By default, the log level for each message category is info.

The log-level of a message category works in conjunction with the severity
level of a message to determine which messages are included in the log file.
For more information, see Message Severity.

Format of an Access Log Message

Example 23–2 shows an extract
of an access log. The log shows a client request that starts with a message
in the CONNECT category and ends with a message in the DISCONNECT category. The operation requested by the client is shown
by the message in the OPERATION category, and results in
several messages in the SERVER_OP category. The logged
messages have the INFO and DEBUG severity.

Message Parts in an Access Log

Messages for the connections between a client and the Directory Proxy Server are
labeled in the same way as in Directory Server. Table 23–4 describes parts of the messages between the client and
the Directory Proxy Server in Example 23–2.
For an explanation of all of the possible message parts, see Content of Access, Error, and Audit Logs.

Table 23–3 Message Parts for Connections Between
a Client and a Directory Proxy Server

Log Message Part

Description

conn

Identifier for the connection between the client and the Directory Proxy Server.

op

The number of an operation on a given connection. The first operation
on a connection has the value op=0. Subsequent requests
on the connection have increasing numbers, op=1, op=2, etc.

msgid

The number of a message to be sent to a client application. The LDAP
protocol is mainly asynchronous. If a client request requires a response from
a server, the response is given in the following steps:

The directory server acknowledges the request and assigns
a msgid

The directory server responds to the request by using the msgid identifier

A response can be sent in multiple packets, where each packet is identified
by the same msgid.

nentries

The number of entries returned by a search request.

err

The result code returned from the LDAP operation. The error number 0 means that the operation was successful. For a list of LDAP result
codes, see Result Codes in Log Files.

msg

A human readable error diagnostic.

Messages for the connections between Directory Proxy Server and a data source
are prefixed with s_. Table 23–4 describes parts of the messages between the Directory Proxy Server and
the data source in Example 23–2.

Table 23–4 Message Parts for Connections Between
a Directory Proxy Server and a Data Source

Log Message Part

Description

s_msgid

Identifier for the message between the Directory Proxy Server and a data
source.

s_authzid

Authorization identity for an operation to be processed under when the Directory Proxy Server forwards
the request to a data source by using proxy authorization.

s_conn

Identifier for the connection between the Directory Proxy Server and the
data source.

Access Log Buffer

Access log messages are stored in a buffer. The buffer is flushed to
the access log at the following times:

When the buffer is full

When the access log is rotated

When Directory Proxy Server is stopped

If a buffer is flushed because it is full, the last message in the access
log file might not be complete. The remainder of the message is then delivered
in the next flush. By default, the size of the buffer is 10 KBytes. However,
the size of the buffer can be configured to control the frequency with which
it is flushed. For performance reasons, the buffer size should not be reduced
to less than 5 KBytes.

Access
logs show client accesses to the server and corresponding server responses. Directory Proxy Server access
logs further show information about the connections set up against data sources,
in this case Directory Server instances.

Tracking client requests can be broken down into the following steps:

Tracking the operations performed within a single client connection

Identifying the client that performed a certain operation

Tracking Operations by Connection

Directory Proxy Server typically sets up connections with backend servers
before it handles client connections. This means that the proxy can pool operations,
binding and rebinding only when necessary and avoiding connection setup overhead. Directory Proxy Server identifies
these backend connections in its access log with tags of the form s_conn=data-source:number, where data-source is a data source name from
the configuration and number is a server connection number
assigned by the proxy. Such s_conn server connections can
then be matched to connection numbers in Directory Server access logs using
the port number from which the proxy connected to the directory as a client
when establishing the connection. Therefore, s_conn in
proxy access log messages be translated into conn in directory
access log messages.

Tracking Operations in Directory Proxy Server

In the Directory Proxy Server access log, each client operation is contained
within a CONNECT and a DISCONNECT message.
Between these two messages, several OPERATION messages
can appear. Each OPERATION message can contain several SERVER_OP messages.

The OPERATION messages refer to operations performed
by the client. The SERVER_OP messages refer to operations
performed by Directory Proxy Server.

The following extract of a Directory Proxy Server access log file shows
the start (CONNECT) and end (DISCONNECT)
of a connection, conn=0. The log shows all the OPERATION requests performed by a client this connection and the related SERVER_OP requests sent to the backend server by Directory Proxy Server on
behalf of the client.

When Directory Proxy Server starts up, it establishes connections with all
the remote servers identified in its configuration. These connections are
logged in the Directory Proxy Server access log, and are identified by the field s_conn=server-name:number.
The server-name is defined in the Directory Proxy Server configuration
and refers to a specific backend server. The number indicates
how many connections there have been to this backend server, through the same
port.

For example, in the following extract from the Directory Proxy Servers_conn=server-1:1 is the first connection to remote server server-1 through
port 59100.

When this connection is established, the corresponding line in the Directory Server access
log shows that the connection from Directory Proxy Server through port 59100 is identified with the connection ID conn=244.

For the remainder of the life of this connection, server-1:1 in
the Directory Proxy Server can be mapped to conn=24 in the Directory Server access
log.

This kind of mapping between connections also requires that Directory Proxy Server and
the backend Directory Server are synchronized.

Note that a connection from Directory Proxy Server to a backend Directory Server can
remain alive for several days. If you rotate logs, either manually or automatically,
it might therefore be necessary to access archived log files to trace the
operations performed during a connection.

Client Identification

A client is identified in the access logs by its IP address and, optionally,
by its bind DN. When a client establishes a connection to Directory Proxy Server,
the following kind of message is logged in the Directory Proxy Server access log:

Tracking the connection in this way enables you to identify the full
connection path from the client to Directory Server.

Directory Proxy Server does not wait for a client connection before it establishes
a connection to a remote server. The Directory Proxy Server configuration specifies
that certain connections are dedicated to bind operations, others to read
operations, and others to write operations. When Directory Proxy Server starts
up, it establishes all connections to the remote servers, according to this
configuration.

When a connection has been established completely (from the client to Directory Server)
the client can be identified by its DN.

Directory Server recognizes the client DN as one of the following:

True client bind DN. The
bind DN is the client's own bind DN if Directory Proxy Server is configured in
Use Bind mode.

Modified client bind DN. The
bind DN is modified if Directory Proxy Server is configured in User Proxy Auth
Control mode. The DN is modified as a result of DN renaming or user mapping.

A single connection can be used by multiple clients (though not simultaneously).
To identify a client connection correctly in the access logs, Directory Proxy Server and Directory Server must
be synchronized, that is, the server clock must be as close as possible. This
will ensure that the timestamps in the access logs correspond. If the servers
are not synchronized, you should synchronize them by using a time server,
or evaluate the difference between the server clocks and search the access
logs taking this difference into account.

Chapter 24 Directory Proxy Server Alerts and Monitoring

The Directory Proxy Server provides monitoring information about its own
status. Directory Proxy Server also monitors data sources to determine whether
they are alive and to detect failed connections. If a data source fails, Directory Proxy Server can
switch new requests over to a working data source in a data source pool and
can replay failed requests to this new data source.

This chapter describes how monitoring is implemented in Directory Proxy Server.
The chapter covers the following topics:

Administrative Alerts for Directory Proxy Server

Directory Proxy Server generates
a set of predefined administrative alerts. You can select one or more of the
predefined administrative alerts and configure Directory Proxy Server to take
a specific action when the alert events occur:

The actions that can be taken include the following:

Create a syslog entry. Alerts are sent to the syslog with
the facility of USER.

Monitoring Data Sources

Directory Proxy Server continuously monitors data sources to determine
whether they are alive and to detect failed connections. This section describes
how Directory Proxy Server monitors data sources, and what action is taken when
data sources fail.

How Data Sources Are Monitored

Directory Proxy Server performs the following tests to monitor the health
of a data source:

Listens for errors on the traffic between Directory Proxy Server and
the data source

Periodically establishes a dedicated connection to the data
source if there is no traffic from that data source for a specified time interval

Periodically pings each existing connection to each data source
to prevent that connection from being closed and to detect closed connections

These tests are described in the following sections.

Monitoring a Data Source by Listening for Errors

When this type of monitoring is configured, Directory Proxy Server listens
for errors on the traffic between itself and the data source. If Directory Proxy Server detects
that a client operation fails, the proxy tests the data source related to
the failure.

This type of monitoring is called reactive monitoring because Directory Proxy Server reacts
to an error, but otherwise performs no active testing of the data sources.

When this type of monitoring is configured, Directory Proxy Server establishes
a dedicated connection to a data source when no requests made to the data
source or responses given by the data source for a specified time period.
By periodically establishing a dedicated connection to a data source, Directory Proxy Server monitors
whether the data source is working.

Monitoring Data Sources by Testing Established Connections

When this type of monitoring is configured, Directory Proxy Server tests
each connection to each data source at regular intervals. In this way, the
proxy prevents connections from being dropped because of inactivity, and detects
closed connections.

Directory Proxy Server can be configured to test connections in the following
scenarios:

Pooled connections that are not used for a period of time

Connections for persistent searches that are not active for
a period of time

Connections between a client and Directory Proxy Server operating
in tunneling mode

Testing established connections consumes system resources, but it provides
good security for connections. If you are using the Active Directory product,
you must use this method of monitoring because the Active Directory product
closes inactive connections.

To test an established connection, Directory Proxy Server issues a search
request with the following parameters:

Directory Proxy Server monitors data sources by using a search filter. Data
sources that return a result that satisfies the filter are considered to be
working.

Responding to the Failure of a Data Source

When Directory Proxy Server detects an error on a connection, the proxy
closes the connection and tries to reestablish the connection immediately.
If the proxy can reestablish the connection, it considers the data source
to be up and running. If the proxy cannot reestablish the connection, it flags
the data source as unavailable. Directory Proxy Server stops distributing requests
to the data source and closes all other connections to the data source.

If a request fails because of a failed connection or a failed data source, Directory Proxy Server replays
the request over another connection to the same data source or replays the
request to another data source. If the request is replayed to another data
source, the load balancing algorithm determines which data source is used.

If there are no data sources to which Directory Proxy Server can replay
the request, the proxy returns an error to the client.

Replaying the request enables the failure to be transparent to the client.
Requests are replayed for the following operations:

Search

Bind

Compare

Requests are not replayed for write operations because Directory Proxy Server cannot
be sure whether the operation was performed before the connection failure
occurred.

When a data source recovers after a being unavailable, Directory Proxy Server returns
the data source to the list of candidate data sources. The work that was being
carried out by the other candidate data sources is redistributed to include
this data source, according to the load balancing algorithm.

When the failed data source recovers, Directory Proxy Server recommences
monitoring the traffic between the data sources and their clients.

Figure 24–1 Monitoring Framework for Directory Proxy Server

Simplified Layout of the cn=monitor Entry

This section provides
a simplified layout of the cn=monitor entry. For the detailed
layout of the cn=monitor entry and a description of all
of the entries and attributes under cn=monitor, see Detailed Layout of the cn=monitor Entry.

Description of Each Entry Under the cn=monitor Entry

cn=Product

The cn=Product entry identifies the set of files
being installed. An installed product is identified by the entry cn=ProductName.

cn=Product contains the following groups of attributes:

Settings

version identifies the full release number
containing major release, minor release and optionally micro release (for
example, 6.1).

buildNumber identifies the syntax of the
build number.

patchId identifies the patch of the product.
This attribute can be empty.

State

Provides operational status and availability status.

Statistics

Provides a set of statistics metrics such as performance and
usage.

cn=Operating System

The cn=Operating System entry identifies which operating
system the product package is installed under. This entry has the following
monitoring DN:

cn=Operating System, cn=ProductName, cn=Product, cn=monitor

cn=Operating System contains the following groups
of attributes:

Settings

operatingSystemName identifies the name of the operating system such as SunOS.

operatingSystemVersion identifies the release
of the operating system such as 5.10.

State

Provides operational status and availability status.

Statistics

Provides a set of statistics metrics
such as performance and usage.

cn=Instance

The cn=Instance entry identifies an instance of the
installed product. More than one instance of a product can exist on a single
data source. Each instance is identified by an instance ID, where instanceId=host:instance-path.

Entries below the cn=Resource entry for the connection
handler thread contain the following groups of attributes:

Settings

threadID provides the unique thread identification
number.

threadStack provides the information on
threads stack.

State

operationalStatus identifies the status
of the element. The value 2 indicates that the element
is fully operational.

startTime identifies the date and time
at which the thread was started.

started identifies if the thread has started.

running identifies if the thread is in running state.

statusDescription provides the detailed status description.

Statistics

The following statistics can be gathered:

Byte buffer pool statistics under cn=ByteBufferPool:

numTries

numHits

numMissesEmpty

numMissesSize

numReleases

availableStandardBuffers

availableOversizedBuffers

String buffer pool statistics under cn=StringBufferPool:

numTries

numHits

numMisses

numReleases

availableBuffers

Vector pool statistics under cn=VectorPool:

numTries

numHits

numMisses

numReleases

availableBuffers

Work Queue

Incoming requests from clients are stored by connection handler threads
in the work queue. The requests are then processed by the worker thread. The cn=Resource entry for the work queue has the following monitoring
DN:

Entries below the cn=Resource entry for the search
thread contain the same groups of attributes as described in Connection Handler Thread.

Monitor Thread

The monitor thread checks the availability of remote data sources. A
remote data source is considered to be available when the monitor thread can
create one connection to the remote data source. The cn=Resource entry
for the monitor thread has the following monitoring DN:

If you installed software from native packages, you may also use the
packaging commands on your system to list the files installed. For example,
after installing from native packages on Solaris systems, you can obtain a
full list for a particular package using the pkgchk -v package-name command.

If you installed software from a zip distribution, find lists of installed
files in the install-path/dsee6/data/ directory.

Software Layout for Directory Proxy Server

This section describes the file layout you find after installing Directory Proxy Server from
the zip distribution. All files locations are relative to the path where you
installed the product. For information on default native package installation
locations, see Default Paths and Command Locations.

install-path/dps6/

Directory Proxy Server files shared by server instances. This
directory houses the following files of interest.

install-path/dps6/bin/dpadm

Directory Proxy Server command for local administration. See dpadm(1M).

install-path/dps6/bin/dpconf

Directory Proxy Server command for configuration over LDAP. See dpconf(1M).

install-path/dps6/etc/

Directory Proxy Server configuration templates, not intended to
be used directly.

install-path/dps6/examples/

Sample Directory Proxy Server plug-ins (currently empty).

install-path/dps6/lib/

Shared Directory Proxy Server libraries, not intended for use
directly.

install-path/dps6/resources/

Directory Proxy Server resource files, not intended to be used
directly.

install-path/dscc6/

Directory Service Control Center agent files shared by multiple Directory Server Enterprise Edition component
products. This directory houses the following files of interest.

install-path/dscc6/bin/dsccmon

Command to monitor servers managed through Directory Service Control Center. See dsccmon(1M).

install-path/dscc6/bin/dsccreg

Command to manage the Directory Service Control Center registry. See dsccreg(1M).

install-path/dscc6/bin/dsccsetup

Command to set up Directory Service Control Center. See dsccsetup(1M).

install-path/dscc6/etc/

Directory Service Control Center agent configuration information, not intended
to be used directly.