Sun Java System Directory Server Enterprise Edition 6.3 Reference

Part II Directory Proxy Server Reference

This part explains how Directory Proxy Server works. The information here is primarily descriptive. For instructions, try Part II, Directory Proxy Server Administration, in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide instead.

This part includes the following chapters:

Chapter 15 Directory Proxy Server Overview

This chapter outlines the architecture of Directory Proxy Server, and describes at a high level, the most important features of this release.

The chapter covers the following topics:

Introduction to Directory Proxy Server

Directory Proxy Server is an LDAP application-layer protocol gateway. Directory Proxy Server delivers enhanced directory access control, schema compatibility, and high availability.

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

Figure shows simplified architecture of the 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.

A Directory Proxy Server instance proxies client application requests to data sources through data views. Data sources and pools of data sources correspond to load balanced groups from 5.x.

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.

Data views therefore enable Directory Proxy Server to select the data sources via a data source pool to handle the LDAP operation. Data source pools, which correspond to 5.x load balanced groups, represent sets of data sources each holding equivalent data. A pool defines the load balancing and failover management that Directory Proxy Server performs to spread load across different data sources. As load balancing is performed per operation, the balancing itself is by nature operation based.

Data sources can be understood as sources of data for reads, and sinks of data for writes. Directory Proxy Server handles the following kinds of data sources:

Directory Proxy Server 5.x was essentially a connection based router. In Directory Proxy Server 5.x, a client connection was routed to a directory server. All requests from that client connection were sent to the same directory server until the connection was broken. For compatibility, Directory Proxy Server can be configured to behave in a similar way to Directory Proxy Server 5.2. For information about how to configure this, see Configuring Directory Proxy Server as a Connection Based Router in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide. For information about how to migrate to this version of Directory Proxy Server, see the Sun Java System Directory Server Enterprise Edition 6.3 Migration Guide.

Overview of Directory Proxy Server Features

Directory Proxy Server provides the following features:

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.

For information about how to configure load balancing and client affinity, see Chapter 21, Directory Proxy Server Load Balancing and Client Affinity, in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

For information about how the Directory Proxy Server performs load balancing and client affinity, see the following sections:

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

For information about how to create and configure an LDAP data source pool, see Creating and Configuring LDAP Data Source Pools in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Load Balancing

When more than one data source is attached to a pool, load balancing determines which data source in the pool responds to the request.

For information about load balancing, see the following sections:

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:

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.

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

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:

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

Figure shows how requests are distributed to a group
of data sources by using the proportional algorithm for load balancing.

For an example of how configure the proportional algorithm, see To Configure the Proportional Algorithm for Load Balancing in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows how requests are distributed to a group
of data sources by using 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.

For an example of how configure the saturation algorithm, see To Configure the Saturation Algorithm for Load Balancing in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows how requests are distributed by the operational
affinity algorithm for load balancing.

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

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.

For an example of how configure the operational affinity algorithm for global account lockout, see To Configure the Operational Affinity Algorithm for Global Account Lockout in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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.

For an example of how configure the operational affinity algorithm for cache optimization, see To Configure Operational Affinity Algorithm for Cache Optimization in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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.

For an example of how configure the failover algorithm, see To Configure the Failover Algorithm for Load Balancing in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

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:

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

For information about how to configure client affinity, see Configuring Client Affinity in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

The client affinity feature must be used to configure Directory Proxy Server as a simple, connection based router. For information, see Configuring Directory Proxy Server as a Connection Based Router in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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 Views

An LDAP data view exposes data in an LDAP server to a client request and specifies the data source pool that responds to the request. By defining LDAP data views, you can perform the following tasks:

There are additional types of data views but distribution can only be done with LDAP data views. For more information about other types of data views, see Chapter 18, Directory Proxy Server Virtualization.

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.

By default, Directory Proxy Server automatically configures the excluded-subtrees parameter in the superior data view to exclude subordinate data views. For information about how to disable the automatic configuration, see To Manually Configure the excluded-subtrees and alternate-search-base-dn Properties in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

The following subtrees are excluded by default from all data views: cn=config, cn=monitor, and cn=proxy manager.

Performing a Search Directed at a Superior Data View on an Excluded, Subordinate Data View

When an alternate search base is specified in a subordinate data view, search operations targeted at the superior data view are also performed in the subordinate data view.

By default, Directory Proxy Server automatically configures the alternateSearchBase parameter in the subordinate data view. For information about how to disable the automatic configuration, see To Manually Configure the excluded-subtrees and alternate-search-base-dn Properties in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows how attribute renaming is performed.

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.

For information about how to configure attribute renaming, see To Configure Attribute Renaming in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

DN Renaming

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

Figure 17–2 DN Renaming

Figure shows how DN renaming is performed.

In Figure 17–2, the client contains the dc=example, dc=com database. The LDAP server contains the dc=example, dc=org database. The Directory Proxy Server renames the DNs.

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.

For information about how to configure DN renaming, see To Configure DN Renaming in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

  • pattern-matching-base-object-search-filter

  • pattern-matching-dn-regular-expression

  • pattern-matching-one-level-search-filter

  • pattern-matching-subtree-search-filter

The syntax supported by the pattern matching algorithm is specified by the Java Pattern class (documented at http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html). This syntax is not the same as the usual regex syntax.

Numeric

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.

You can also configure Directory Proxy Server to support your custom distribution algorithms. For more information about configuring custom distribution algorithms, see To Configure Custom Distribution Algorithm in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

For information about how to configure a distribution algorithm, see Data Views With Hierarchy and a Distribution Algorithm in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide. For information about the parameters used with the distribution algorithms, see distribution-algorithm(5dpconf).

Limitations of Distribution Algorithms

The distribution algorithms provided with Directory Proxy Server have certain limitations in specific request scenarios.

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.

Use Cases for Data Views

This section describes use cases for LDAP data views. All of the examples assume that the connection handler allows all client connections to be processed by Directory Proxy Server.

For examples of data views in different deployments, see the following sections:

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

Figure shows an 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.

For information about how to configure the data view in Figure 17–3, see Data Views That Route All Requests, Irrespective of the Target DN of the Request in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows an example deployment that routes requests
targeted at a list of subtrees to a set of 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.

For information about how to configure the data views in this section, see Data Views That Route Requests When a List of Subtrees Is Stored on Multiple, Data-Equivalent Data Sources in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows an example deployment that provides a single
point of access to different subtrees stored in multiple 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.

For information about how to configure a data view to provide a single point of access to different subtrees stored in multiple data sources, see Data Views That Provide a Single Point of Access When Different Subtrees Are Stored in Different Data Sources in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows an example deployment that provides a single
point of access to different parts of subtree stored in multiple data sources.

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

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.

For information about how to configure a data view to provide a single point of access to different parts of subtree on multiple data sources, see Data Views That Provide a Single Point of Access When Different Parts of a Subtree Are Stored in Different Data Sources in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Data Views to Route Requests When Superior and Subordinate Subtrees Are Stored in Different Data Sources

This section describes how Directory Proxy Server provides a single point of access when a superior branch of a subtree is stored in a different data source to a subordinate branch.

By default, Directory Proxy Server automatically sets the excluded-subtrees property and the alternate-search-base-dn property. However, the automatic management of the excluded-subtrees property and the alternate-search-base-dn property can be disabled. For information about how to manually configure the excluded-subtrees property and the alternate-search-base-dn property, see To Manually Configure the excluded-subtrees and alternate-search-base-dn Properties in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows an example deployment that routes 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:

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.

For information about how to configure a data view to provide a single point of access to different parts of subtree in multiple data sources, see Data Views That Provide a Single Point of Access When Superior and Subordinate Subtrees Are Stored in Different Data Sources in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows an example with data views that combine
hierarchy and distribution algorithms.

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:

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.

For information about how to configure a complex data view, see Data Views With Hierarchy and a Distribution Algorithm in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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.

The chapter covers the following topics:

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

Figure shows transformation of a physical data view to
a 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 – 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:

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
 view-name model action attr-name [parameters...]

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:

$ dpconf set-virtual-transformation-prop -h host -p port -D bindDN /
 view-name transformation-name property:value [property:value]

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

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

Figure shows a high level view of how a mapping transformation
works

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

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
view-name mapping action attr-name [parameters]

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

Figure shows a high level view of how a write transformation
works

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

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
view-name write action attr-name [parameters]

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

Figure shows a high level view of how a read transformation
works

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

$ dpconf add-virtual-transformation -h host -p port -D bindDN /
view-name read action attr-name parameters

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:

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:

Transformation parameters take the following syntaxes:


Note –

The transformation parameter syntax is slightly different when used in the context of a join data view. For more information, see Virtual Data Transformations on Join Data Views.


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:

$ dpconf add-virtual-transformation -h myHost -p 2389 -D "cn=Proxy Manager" \
 exampleB-view-name mapping attr-value-mapping objectclass internal-value:user \
 view-value:inetOrgPerson


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.

Figure shows the creation of an attribute with a write
transformation

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

$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name write add-attr mail \${uid}@example.com

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.

Figure shows the creation of an attribute with a read
transformation

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

$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name read add-attr mail \${givenname}.\${sn}@example.com


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.

Figure shows transformation of an entry with no reference
to other entries.

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

$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name read remove-attr supportPerson
$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleA-view-name read add-attr hotline "0800755 8625"


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:


$ dpconf add-virtual-transformation -h myHost -p 2389 -d "cn=Proxy Manager" \
 exampleB-view-name mapping attr-value-mapping dn internal-value:cn=\${cn} \
 view-value:cn=\${cn},objectclass=\${objectclass}

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 and viewable attributes are mutually exclusive. Similarly, non-writable attributes and writable attributes are mutually exclusive.

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.

Figure shows aggregation of two join source data views.

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:

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.

How Directory Proxy Server Handles Read and Write Operations to Join Data Views

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:

\${primaryDataView.firstName}.\${secondaryDataView.lastName}@\${primaryDataView.domainName}

The firstName and domainName attributes are taken from the primary data view, and the lastName attribute is taken from the secondary data view.

LDIF Data Views

An LDIF data view is a simple virtual data view in which an LDIF file is made to look like an LDAP data source. An LDIF data view is defined by using the dpconf command as follows:

dpconf create-ldif-data-view VIEW_NAME LDIF_FILE_NAME SUFFIX_DN

No additional transformations are required. Directory Proxy Server automatically performs the transformations required to make the LDIF data look like LDAP data to client applications.

For information about creating and configuring LDIF data views, see Creating and Configuring LDIF Data Views in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

JDBC Data Views

A JDBC data view enables you to make a relational database accessible to LDAP client applications. The following configuration objects are required to set up a JDBC data view:

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.

Figure shows RDBMS accessible to LDAP client applications.

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:


$ dpconf get-jdbc-data-source-prop -h myHost -p 2389 -d "cn=Proxy Manager"\
 jdbc-data-source-name

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:


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:

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:

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.

$ dpconf add-jdbc-attr -h myHost -p 2389 -d "cn=Proxy Manager" \
 EMPLOYEE employeeNumber ID

The following properties apply to JDBC attributes:

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.

This section describes the syntax and architecture of virtual ACIs. For information about configuring virtual ACIs, see Defining Access Control on Virtual Data Views in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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.

Virtual ACI Syntax

The dpsaci attribute resembles the Directory Server aci attribute in syntax and behavior. For a description of Directory Server ACI syntax, see How Directory Server Provides Access Control.

The following list describes the differences between virtual ACIs and Directory Server ACIs.

Virtual ACI Storage and Access

Virtual ACIs are stored centrally, in an LDIF file or in an LDAP directory. When you create a Directory Proxy Server instance, the virtual ACIs are stored in the LDIF file instance-path /config/access_controls.ldif by default. You can change the location of the virtual ACIs, particularly if you need to share ACIs across multiple proxy servers. For information about how to change the location of virtual ACIs, see To Define a New ACI Storage Repository in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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.

Chapter 19 Connections Between Directory Proxy Server and Backend LDAP Servers

This chapter describes the connections between Directory Proxy Server and backend LDAP servers. The chapter covers the following topics:

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.

For information about how to create and configure LDAP data sources, see Creating and Configuring LDAP Data Sources in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Connections Between Directory Proxy Server and Backend LDAP Servers

This section describes how connections between Directory Proxy Server and backend LDAP servers are opened and closed. It also describes the use of connection pools for multiple client requests.

Opening and Closing Connections Between Directory Proxy Server and Backend LDAP Servers

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.

Connection Pools Between Directory Proxy Server and Backend LDAP Servers

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:

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.

Forwarding Request From Directory Proxy Server to Backend LDAP Servers

Client requests can be forwarded from Directory Proxy Server to backend LDAP servers with different levels of authorization and authentication, and with or without the identity of the client. The configuration of the data source determines the way in which a request is forwarded. For information about proxy authorization in client requests, see Directory Proxy Server Configured for Proxy Authorization. For information about how to configure proxy authorization in client requests, see Proxy Authorization in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

When client requests contain a proxy authorization control, the control is always forwarded with the request, irrespective of how Directory Proxy Server forwards the request. The use case where Directory Proxy Server is configured for proxy authorization and the client request itself contains a proxy authorization control is described in Directory Proxy Server Configured for Proxy Authorization and the Client Request Does Contain a Proxy Authorization.

For information about how client requests are forwarded from Directory Proxy Server to backend LDAP servers, see the following sections:

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

Figure shows the client identity and credentials being
used for authorization by 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:

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

  2. 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.

  3. The client issues a SEARCH request that is targeted at LDAP server 1.

  4. Directory Proxy Server forwards the SEARCH request to LDAP server 1, reusing connection 2.

    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.

  5. The client sends a SEARCH request targeted at LDAP server 2

  6. 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.

  7. The Directory Proxy Server forwards the SEARCH request to LDAP server 2, reusing connection 3.

If the client is not authenticated to Directory Proxy Server, the BIND request is forwarded as anonymous.

If the client identity is mapped onto another identity, Directory Proxy Server uses the mapped identity to bind to the LDAP server. All requests on that connection are processed with the authorization for the mapped identity. For information about user mapping, see Directory Proxy Server Configured to Forward Requests As an Alternate User.

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.

For information about how to configure proxy authorization in Directory Proxy Server, see Forwarding Requests With Proxy Authorization in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide

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 shows the connections between a client, Directory Proxy Server, and backend LDAP servers, when Directory Proxy Server is configured for proxy authorization.

Figure 19–2 Connections for Proxy Authorization

Figure shows the connections for proxy authorization.

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

  1. 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.

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

  3. 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

Figure 19–3 shows the flow of information when Directory Proxy Server is configured for proxy authorization. The client in Figure 19–2 makes, and Directory Proxy Server adds a proxy authorization control.

Figure 19–3 Information Flow When Proxy Authorization Control Is Added by Directory Proxy Server

Figure shows the flow of information when a client request
does not contain a proxy authorization control.

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

  2. 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.

  3. 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.

  4. The Directory Proxy Server forwards the SEARCH operation to LDAP server 2, reusing connection 3.

    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

Figure shows the flow of information when a proxy authorization
control is contained in a client request.

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

  2. Directory Proxy Server verifies that the clientDN has the right to use a proxy authorization control on LDAP server 1, by getting the effective rights of the client on LDAP server 1. For information about how to get effective rights, see Viewing Effective Rights in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide

  3. Directory Proxy Server 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. The authorization is defined in the RW ACIs on the LDAP server.

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

  5. Directory Proxy Server verifies that the clientDN has the right to use a proxy authorization control on LDAP server 2, by getting the effective rights of the client on LDAP server 2.

  6. The Directory Proxy Server forwards the SEARCH operation to LDAP server 2, reusing connection 3.

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

Security Issues When Directory Proxy Server Is Configured for Proxy Authorization

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

Directory Proxy Server Configured to Forward Requests Without the Client Identity

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.

Directory Proxy Server Configured to Forward Requests As an Alternate User

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

Figure shows local mapping of client ID to alternate
ID

Figure 19–6 Remote Mapping of Client Identity to an Alternate Identity

Figure shows a client identity being mapped 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.

For information about how to configure user mapping, see Forwarding Requests as an Alternate User in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide

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.

This chapter covers the following topics:

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.

The following list summarizes the criteria used to classify connections into connection handlers. For information about how to configure the criteria, see Creating, Configuring, and Deleting Connection Handlers in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

Figure shows a 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.

For information about how to configure data view affinity, see To Configure Affinity for Data Views in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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.

A connection handler can have zero or one resource limits policy. If no resource limits policy is defined, no limits are applied to connections, requests and referrals. For information about how to configure resource limits policies and examples of resource limits policies, see Creating and Configuring a Resource Limits Policy in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

For information about how to configure a resource limits policy, see Creating and Configuring a Resource Limits Policy in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide

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:

For information about how to configure a request filtering policy, see Creating and Configuring Request Filtering Policies and Search Data Hiding Rules in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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 in the Request Filtering Policy

Rules that determine how to return the result of a search operation to a client are called search data hiding rules. For information about creating search data hiding rules, see To Create Search Data Hiding Rules in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

The result of a search operation can be returned in one of the following ways:

Search data hiding rules can be applied to the following entries:

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.

Chapter 21 Directory Proxy Server Client Authentication

This chapter describes how Directory Proxy Server identifies incoming client connections. The chapter covers the following topics:

Client Authentication Overview

Client authentication determines how a client identifies itself to Directory Proxy Server.

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

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 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.

Password Encryption and Verification

The way in which passwords are encrypted and checked depends on the type of data view through which the client accesses the data source. For information about data views, see Chapter 17, Directory Proxy Server Distribution and Chapter 18, Directory Proxy Server Virtualization.

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.

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:

  1. 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.

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

  3. 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.

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

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

  6. 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:


      cert-data-view-routing-policy
      cert-data-view-routing-custom-list
      cert-search-bind-dn
      cert-search-bind-pwd-file
      cert-search-base-dn
      cert-search-attr-mappings
  7. When the proxy server has the bind DN, it can verify the validity of the client.

For more information about SSL for Directory Proxy Server, see Secure Sockets Layer for Directory Proxy Server.

For certificate-based authentication to occur, Directory Proxy Server must be configured to accept client certificates and the client must be configured to use SASL external bind.

Configuring Certificates in Directory Proxy Server

When you create a Directory Proxy Server instance, the certificate database is automatically populated with the CA certificates of certain trusted CAs. You can add trusted CA certificates to the certificate database if necessary, by using the Directory Service Control Center (DSCC) or by using the dpadm command. For more information, see To Install a CA-Signed Server Certificate for Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

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.

When an instance of Directory Proxy Server is created, a default self-signed certificate is created. By default, Directory Proxy Server manages the SSL certificate database password internally.

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.

For an explanation of how certificate-based authentication works, see Certificate-Based Authentication. For information about how to configure certificate-based authentication for Directory Proxy Server, see To Configure Certificate-based Authentication in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

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.

For information about how to configure authentication by SASL external bind, see To Configure Directory Proxy Server for SASL External Bind in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Anonymous Access

Anonymous access makes data available to any client, regardless of whether the user has authenticated.

For information about how to configure Directory Proxy Server for anonymous connections from clients, see To Configure Anonymous Access in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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

For information about how to configure listeners, see Configuring Listeners Between Clients and Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Chapter 22 Security in Directory Proxy Server

This chapter describes the mechanisms that can be used to secure data that passes through Directory Proxy Server.

The chapter covers the following topics:

How Directory Proxy Server Provides Security

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

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:

A randomly generated password to protect the certificate database

The password is stored in instance-path/etc/pass.txt

A key store database for certificates

The keystore database is located in instance-path/alias/cert.jks

A key store database for a symmetric encryption key

The keystore database is located in instance-path/alias/key.jceks

The key store databases are protected by the same password.

For more information about SSL, see Secure Sockets Layer (SSL). For information about how to configure SSL between clients and Directory Proxy Server, see Configuring Listeners Between Clients and Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide

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.

For reference information about cipher suites, see Cryptographic Algorithms Used With SSL. For information about how to choose ciphers, see Choosing SSL Ciphers and SSL Protocols for Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Chapter 23 Directory Proxy Server Logging

Directory Proxy Server logs information in access logs and error logs. Additionally, a plug-in can be configured to log messages to a syslog daemon. Unlike Directory Server, Directory Proxy Server does not provide an audit log.

Log files for Directory Proxy Server can be configured through Directory Service Control Center or on the command line. For information about how to configure log files, see Chapter 28, Directory Proxy Server Logging, in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

For information about access logs and error logs, see the following sections:

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:

Log messages can also be sent to the syslog daemon. For information about how to log messages to a syslog daemon, see Logging Alerts to the syslogd Daemon in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Log File Rotation

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

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

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:

By default, log file deletion is based on free disk space, with a default value of 1 Megabyte. When all three deletion policies are activated simultaneously, they are processed in order of time, size, and free disk space. For information about how to configure log file deletion, see Deleting Directory Proxy Server Logs in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

  1. error

  2. warning

  3. info

  4. 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:

  1. none No messages are included in the log file.

  2. error Only error messages are included in the log file.

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

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

  5. 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.

  6. 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 Error Message

An error log message has this format:

timestamp - message category - message severity - message text

Example 23–1 shows an extract from an error log.


Example 23–1 Extract of an Error Log


[07/26/2005:10:41:38 +0200] - STARTUP    - INFO  - Sun Java(TM) 
  System Directory Proxy Server/6.1 (Build 0719051656 DEBUG) starting up
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Global log level INFO
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Logging Service conf
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Java Version: 1.5.0_03
 (Java Home: /usr/lang/JAVA/jdk1.5.0_03/solaris-sparc/jre)
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Operating System:
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Init LDAP server
  cn=Server-1, cn=LDAP servers,cn=config
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Init LDAP server
  cn=Server-2,cn=LDAP servers,cn=config
[07/26/2005:10:41:43 +0200] - STARTUP    - INFO  - Init LDAP server
  cn=Server-3, cn=LDAP servers,cn=config
[07/26/2005:10:41:44 +0200] - STARTUP    - INFO  - Performing SSL init
[07/26/2005:10:41:44 +0200] - STARTUP    - INFO  - Creating 20 worker 
  threads
[07/26/2005:10:41:44 +0200] - PLUGIN     - WARN  - Unable to load 
  plugin class
  com.sun.directory.proxy.plugin.StartTLSExtendedOpPlugin specified in 
  plugin
  entry cn=1.3.6.1.4.1.1466.20037,cn=Plugins,cn=config -- not loading 
  plugin.
[07/26/2005:10:41:45 +0200] - STARTUP    - INFO  - Starting client 
  listeners
[07/26/2005:10:41:45 +0200] - STARTUP    - INFO  - Sun Java(TM) 
  System Directory Proxy Server/6.1 (Build 0719051656 DEBUG) started 
  on host a
[07/26/2005:10:41:45 +0200] - STARTUP    - INFO  - Listening for secure
  client connections on 0.0.0.0:9636
[07/26/2005:10:41:45 +0200] - STARTUP    - INFO  - Listening for client 
  connections on 0.0.0.0:9389
[07/26/2005:10:42:13 +0200] - BACKEND    - WARN  - Proactive Monitor 
  thread determined that directory server ldap://nautilus:6389/ avail
[07/26/2005:10:42:13 +0200] - BACKEND    - WARN  - Proactive Monitor 
  thread determined directory server ldap://nautilus:7389/ is available.
[07/26/2005:10:42:13 +0200] - BACKEND    - WARN  - Proactive Monitor 
  thread determined directory server ldap://nautilus:5389/ is available.

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:

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:

  1. none No access messages are included in the log file.

  2. info Informational messages are included in the log file.

  3. 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.

  4. 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

An access log message has this format:

timestamp - category - severity - connectionNumber operationNumber
  messageID operationType messageText

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.


Example 23–2 Extract of an Access Log


[07/17/2005:17:29:45 +0200] - CONNECT    - INFO  - conn=1591031 
  client=129.157.192.132:49216 server=0.0.0.0:9389 protocol=LDAP
[07/17/2005:17:29:45 +0200] - OPERATION  - INFO  - conn=1591031 op=0 
  msgid=1 SEARCH base="o=movie" scope=2 filter="(objectClass=*)"
[07/17/2005:17:29:45 +0200] - SERVER_OP  - INFO  - conn=1591031 op=0 
  SEARCH base="o=movie" scope=2 filter="(objectClass=*)" 
  s_msgid=318022 s_authzid="" s_conn=39
[07/17/2005:17:29:45 +0200] - SERVER_OP  - INFO  - conn=1591031 op=0 
  SEARCH base="o=movie" scope=2 filter="(objectClass=*)" s_msgid=316902 
  s_authzid="" s_conn=76
[07/17/2005:17:29:45 +0200] - SERVER_OP  - INFO  - conn=1591031 op=0 
  SEARCH RESPONSE err=0 msg="" nentries=4 s_conn=76
[07/17/2005:17:29:45 +0200] - SERVER_OP  - DEBUG - Global status code = 0
[07/17/2005:17:29:45 +0200] - SERVER_OP  - INFO  - conn=1591031 op=0 
  SEARCH RESPONSE err=0 msg="" nentries=11 s_conn=39
[07/17/2005:17:29:45 +0200] - SERVER_OP  - DEBUG - Global status code = 0
[07/17/2005:17:29:45 +0200] - OPERATION  - INFO  - conn=1591031 op=0 
  SEARCH RESPONSE err=0 msg="" nentries=22
[07/17/2005:17:29:45 +0200] - OPERATION  - INFO  - conn=1591031 op=1 
  UNBIND
[07/17/2005:17:29:45 +0200] - DISCONNECT - INFO  - conn=1591031 
  reason=unbind"

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:

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.

You can configure the size of the access log buffer by setting the log-buffer-size property. For information about how to configure access log properties, see Configuring Directory Proxy Server Logs in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Tracking Client Requests Through Directory Proxy Server and Directory Server Access Logs

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 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.


[timestamp] - CONNECT    - INFO  - conn=0 client=129.157.192.132:59112 server=0.0.0.0:9389 protocol=LDAP
[timestamp] - OPERATION  - INFO  - conn=0 op=0 BIND dn="uid=u1,ou=users,o=movie" method="SIMPLE"
[timestamp] - SERVER_OP  - INFO  - conn=0 op=0 BIND dn="uid=u1,ou=users,o=movie" method="SIMPLE" s_msgid=2 
                                                    s_conn=server-1:1
[timestamp] - SERVER_OP  - INFO  - conn=0 op=0 BIND RESPONSE err=0 msg="" s_conn=server-1:1
[timestamp] - OPERATION  - INFO  - conn=0 op=0 BIND RESPONSE err=0 msg="" etime=0
[timestamp] - OPERATION  - INFO  - conn=0 op=1 msgid=2 SEARCH base="o=movie" scope=2 filter="(objectclass=*)"
[timestamp] - SERVER_OP  - INFO  - conn=0 op=1 SEARCH base="o=movie" scope=2 filter="(objectclass=*)" s_msgid=3 
                                                      s_conn=server-1:1
[timestamp] - SERVER_OP  - INFO  - conn=0 op=1 SEARCH RESPONSE err=0 msg="" nentries=12 s_conn=server-1:1
[timestamp] - OPERATION  - INFO  - conn=0 op=1 SEARCH RESPONSE err=0 msg="" nentries=12 etime=0
[timestamp] - OPERATION  - INFO  - conn=0 op=2 UNBIND
[timestamp] - SERVER_OP  - INFO  - conn=0 op=-1 BIND dn="" method="SIMPLE" s_msgid=4 s_conn=server-1:1
[timestamp] - SERVER_OP  - INFO  - conn=0 op=-1 BIND RESPONSE err=0 msg="" s_conn=server-1:1
[timestamp] - DISCONNECT - INFO  - conn=0 reason="unbind" 

Following this log, it is possible to track all operations that were performed by or on behalf of a particular client.

Tracking Operations Between Directory Proxy Server and Directory Server

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.


SERVER_OP - INFO - Created connection for BIND s_conn=server-1:1 client=129.157.192.132: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.


conn=244 op=-1 msgId=-1 - fd=19 slot=19 LDAP connection from 129.157.192.132:59100 to 129.157.192.132

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:


[timestamp] - CONNECT  - INFO  - conn=0 client=IP1:port1 server=IP2:port2 protocol=LDAP

Directory Proxy Server identifies this client connection as conn=0.

When Directory Proxy Server establishes a connection with a remote Directory Server, the following kind of message is logged in the Directory Proxy Server access log:


[timestamp] - SERVER_OP  - INFO  - Created connection for READ s_conn=server-1:1 client=IP2:port3 
 server=IP4:port4 protocol=LDAP main

Directory Proxy Server identifies this connection to the remote server as s_conn=server-1:1.

At the same time, the following kind of message is logged in the Directory Server access log:


[timestamp] conn=13 op=-1 msgId=-1 - fd=23 slot=23 LDAP connection from IP2:port3 to IP4

So, Directory Server identifies the connection as conn=13.

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:

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:

Table 24–1 lists the predefined administrative alerts for Directory Proxy Server.

Table 24–1 Administrative Alerts for Directory Proxy Server

Alert event 

Alert code 

Configuration Parameter 

Server startup 

1000

info-server-startup

Clean server shutdown 

1001

info-server-shutdown-clean

Abrupt server shutdown 

1002

error-server-shutdown-abrupt

Configuration reloaded 

1003

info-configuration-reload

Configuration reload failure due to bad configuration. Run-time configuration not impacted. 

1004

warning-configuration-reload-failure-no-impact

Configuration reload failure due to bad configuration. Run-time configuration possibly impacted. 

1005

error-configuration-reload-failure-with-impact

Data source not available 

2000

warning-data-source-unavailable

Data source available 

2001

info-data-source-available

Listener not available 

3000

warning-listener-unavailable

Data inconsistency on data sources 

4000

warning-data-sources-inconsistent

For information about how to configure administrative alerts for Directory Proxy Server, see Configuring Administrative Alerts for Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

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.

Directory Proxy Server can be configured to perform this type of reactive monitoring only, without performing the monitoring described in Monitoring Data Sources by Periodically Establishing Dedicated Connections and Monitoring Data Sources by Testing Established Connections. When only reactive monitoring is configured, the monitoring less complete but does not cause additional traffic.

Monitoring Data Sources by Periodically Establishing Dedicated Connections

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.

This type of monitoring is more complete than Monitoring a Data Source by Listening for Errors because Directory Proxy Server does not wait to detect a failure before it tests the data source. However, this type of monitoring is less complete than Monitoring Data Sources by Testing Established Connections, because the proxy does not test whether the existing connections to a data source are working.

This type of monitoring can be used in addition to Monitoring Data Sources by Testing Established Connections.

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.

This type of monitoring can be used in addition to Monitoring Data Sources by Periodically Establishing Dedicated Connections.

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

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:

If a connection is found to be down, Directory Proxy Server polls the connection at a specified interval to detect its recovery. You can configure this interval by setting the monitoring-interval property. For more information, see To Monitor a Data Source by Testing Established Connections in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

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:

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.

Monitoring Directory Proxy Server

Directory Proxy Server runs inside a Java Virtual Machine (JVM) and depends on the memory of the JVM. To ensure that Directory Proxy Server is running correctly, its memory consumption must be monitored. For information about how to monitor Directory Proxy Server memory consumption, see Retrieving Monitored Data About Directory Proxy Server by Using the JVM in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.

Monitoring information for Directory Proxy Server is provided under the cn=monitor entry. The cn=monitor entry is managed by Directory Proxy Server in a local, in-memory database.

For information about monitoring Directory Proxy Server, see the following sections:

Monitoring Framework for Directory Proxy Server

Directory Proxy Server monitoring relies on the Java Enterprise System (ES) Monitoring Framework. The Java ES monitoring framework has been extended to provide a monitoring framework for Directory Proxy Server. The following UML diagram illustrates the Directory Proxy Server monitoring framework.

Figure 24–1 Monitoring Framework for Directory Proxy Server

Figure shows the 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.


cn=monitor
|
+-- cn=Product (Installed Product)
    |
    +-- cn=ProductName
        |
        +-- cn=Operating System
        +-- cn=Instance (Application System)
            |
            +-- cn=InstanceId
                |
                +-- cn=Service
                    +-- cn=Add
                    +-- cn=Delete
                    +-- cn=Modify
                    +-- cn=ModifyDN
                    +-- cn=Search
                    +-- cn=Compare
                    +-- cn=Bind
                +-- cn=Resource (System Resource)
                    +-- cn=Work Queue
                    +-- cn=Worker Thread
                        +-- cn=worker_thread_name
                    +-- cn=Search Thread
                        +-- cn=search_thread_name
                    +-- cn=Monitor Thread
                        +-- cn=monitor_thread_name
                    +-- cn=Connection Handler Thread
                        +-- cn=connection_handler_thread_name
                +-- cn=SAP (Service Access Point)
                    +-- cn=LDAP
                    +-- cn=LDAPS
                +-- cn=RSAP (Remote SAP)
                    +-- cn=LDAP  Server servername
                    +-- cn=LDAPS Server servername
                    +-- cn=RDBM  Server servername
                +-- cn=Component (Logical Component)
                    +-- cn=DataSource Pool
                        +-- cn=poolname
                            +-- cn=Proportional Load Balancing
                                +-- cn=Add
                                +-- cn=Search
                                +-- cn=Delete
                                +-- cn=Compare
                                +-- cn=Modify
                                +-- cn=ModifyDN
                                +-- cn=Bind
                +-- cn=JVM
                +-- cn=DB System
                +-- cn=DB Service

Status of Monitored Information

Every element that is monitored has an operational status. Table 24–2 gives the status of monitored information.

Table 24–2 Status of Monitored Information

Value 

Name 

Description 

UNKNOWN

No information available for this element 

OK

Element is fully operational 

DEGRADED

Element is working but not optimally 

STRESSED

Element is working under stressed environment (for example, overload) 

PREDICTIVE_FAILURE

Element is working but may fail in the near future 

ERROR

Severe error has been raised 

STARTING

Element is starting 

STOPPING

Element is stopping 

10 

STOPPED

Element is stopped 

12 

NO_CONTACT

Element has never been reached 

13 

LOST_COMMUNICATION

Element has been reached once, but it is currently unreachable 

Description of Each Entry Under the cn=monitor Entry

For information about each entry in the cn=monitor subtree, see the following sections:

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.

The cn=Instance entry has the following monitoring DN:


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

cn=Operating System contains the following groups of attributes:

Settings

Provides configuration attribute values.

State

operationalStatus identifies the status of the element, with the following values: 0, 2, 8, 9, and 10. For information about the values, see Table 24–2.

Statistics

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

cn=Service

The cn=Service entry identifies information about LDAP operations, or services, for an instance of Directory Proxy Server.

LDAP operations are add, delete, modify, modifyDN, search, compare, and bind. Each LDAP operation has a specific monitoring entry below cn=Service. For example, the add operation has the following DN:


cn=add, cn=Service, cn=InstanceId, cn=Instance, cn=Operating System, 
  cn=ProductName, cn=Product, cn=monitor

Entries below cn=Service can contain the following groups of attributes:

Settings

Provides configuration attribute values.

State

Provides operational status and availability status.

Statistics
  • total identifies the number of operations received by this instance of Directory Proxy Server.

  • succeeded identifies the number of successful operations in this instance of Directory Proxy Server.

  • failed identifies the number of failed operations in this instance of Directory Proxy Server.

  • abandonned identifies the number of operations abandoned by this instance of Directory Proxy Server.

cn=SAP

A Service Access Point (SAP) provides information on how to access a service. The cn=SAP entry has the following monitoring DN:


cn=listenerThread, cn=SAP, cn=instanceId, cn=Instance, 
  cn=OperatingSystem, cn=Product, cn=monitor

Entries below cn=SAP can contain the following groups of attributes:

Settings
  • name identifies the SAP name, either LDAP or LDAPS.

  • isSecure identifies whether LDAPS is used. If the value is TRUE, LDAPS is used.

  • host identifies the hostname of the current data source.

  • port identifies the port number to access this instance of Directory Proxy Server.

State
  • enabled identifies if the SAP is enabled.

  • operationalStatus identifies the status of the SAP. If the value is 2 or OK, the SAP is fully operational.

  • statusDescription provides a detailed status description.

  • startTime identifies the date and time at which the SAP was started.

  • stopTime identifies the date and time at which the SAP was stopped.

  • stopException provides a description of the error if a stop operation fails. If this attribute is empty, no error has occurred.

Statistics
  • acceptedConnections identifies the number of accepted TCP connections. One counter exists for all LDAP operations. The counter is service agnostic.

  • refusedConnections identifies the number of refused TCP connections.

cn=RSAP

The cn=RSAP entry identifies the type of remote service. The remote SAP can be one of the following types:

LDAP Remote SAP

The cn=RSAP entry for an LDAP remote SAP can have one of the following monitoring DNs:


cn=LDAP  servername, cn=RSAP, cn=instanceId, cn=Instance, 
  cn=OperatingSystem, cn=Product, cn=monitor

cn=LDAPS  servername, cn=RSAP, cn=instanceId, cn=Instance, 
  cn=OperatingSystem, cn=Product, cn=monitor

Entries below cn=RSAP can contain the following groups of attributes:

Settings
  • name identifies the SAP name, either LDAP or LDAPS.

  • isSecure identifies whether LDAPS is used. If the value is TRUE, LDAPS is used.

  • host identifies the hostname of the host server.

  • port identifies the port number to access this instance of Directory Proxy Server.

State
  • operationalStatus identifies the status of the element, with the following values: 2, 4, 12, and 13. For information about these values, see Table 24–2.

  • statusDescription provides the detailed description of the status.

  • started identifies if RSAP is started.

  • readOnly identifies if it is in read only mode.

Statistics
  • totalConnections identifies the total number of connections including the established connections.

  • totalAvailableConnections identifies the total number of available connections for bind, read and write operations. The value 0 means that access to that data source is congested.

  • The following attributes are given for bind operations but also exist for read operations and write operations:

    • totalBindConnections identifies the number of established connections for bind operations. All of the connections are kept in a pool of bind connections.

    • availableBindConnections identifies the number of free bind connections in the pool.

    • bindConnectionsRequested identifies the number of requests to get a free bind connection from the pool.

    • bindConnectionsProvided identifies the number of bind connections provided upon request.

    • bindConnectionsRefused identifies the number of requests being refused because the pool is empty (even after a wait) or because the remote data source is down.

    • bindConnectionsWaitsRequired identifies the number of requests being blocked in a wait state, waiting for a bind connection to be freed.

    • bindConnectionsReturnedValid identifies the number of connections being released.

    • bindConnectionsReturnedInvalid identifies the number of connections being released as invalid. A connection is said to be invalid when errors have occurred.

cn=Component

The cn=Component entry identifies the part of the software being accessed through a service. The following parts of the software are identified by the cn=Component entry:

Proportional Load Balancing Algorithm For All Data Sources

The cn=Component entry for the proportional load balancing algorithm for all data sources has the following monitoring DN:


cn=ProportionalLB, cn=DataSourcePool poolname, cn=Component, 
  cn=instanceId, cn=Instance, cn=OperatingSystem, cn=Product, cn=monitor

Entries below the cn=Component entry for the proportional load balancing algorithm contain the following groups of attributes for all data sources:

Settings
  • className provides the name of the class.

State
  • enabled identifies the status of the remote SAP. If the value is TRUE, the load balancing algorithm is active.

Statistics
  • totalBindConnectionsProvided identifies the total number of connections provided for bind operations.

  • totalBindConnectionsRefused identifies the number of refused connections for bind operations.

    Connections can be refused for one of the following reasons:

    • The pool of data sources is empty.

    • All the data sources in the pool are down.

    • The data source selected by the load balancing algorithm has no free connection to reach the remote service.

  • totalAddConnectionsProvided see totalBindConnectionsProvided

  • totalAddConnectionsRefused see totalBindConnectionsRefused

  • totalCompareConnectionsProvided see totalBindConnectionsProvided

  • totalCompareConnectionsRefused see totalBindConnectionsRefused

  • totalDeleteConnectionsProvided see totalBindConnectionsProvided

  • totalDeleteConnectionsRefused see totalBindConnectionsRefused

  • totalModifyConnectionsProvided see totalBindConnectionsProvided

  • totalModifyConnectionsRefused see totalBindConnectionsRefused

  • totalModifyDNConnectionsProvided see totalBindConnectionsProvided

  • totalModifyDNConnectionsRefused see totalBindConnectionsRefused

  • totalCompareConnectionsProvided see totalBindConnectionsProvided

  • totalCompareConnectionsRefused see totalBindConnectionsRefused

Proportional Load Balancing Algorithm For Individual Data Sources

The cn=Component entry for the proportional load balancing algorithm for individual data sources has the following monitoring DN:


cn=Add, cn=servername, cn=Proportional LB, cn=DataSource Pool poolname,
  cn=Component, cn=instanceId, cn=Instance, cn=OperatingSystem, 
  cn=Product, cn=monitor

Similar monitoring DNs exist for the delete, modify, modifyDN, search, compare, and bind operations.

Entries below the cn=Component entry for the proportional load balancing algorithm contain the following groups of attributes for individual data sources:

Settings
  • Provides configuration attribute values.

State
  • operationalStatus identifies the status of the element, with the following values: 2, and 5. For information about these values, see Table 24–2.

  • statusDescription provides the detailed status description.

Statistics
  • providedConnections the number of connections provided to reach the data source for the operation.

  • providedPercentage the percentage of connections provided to reach the data source for the operation.

  • refusedConnections the number of refused requests to get a connection to that data source.

  • refusedPercentage the percentage of refused requests.

cn=JVM

The cn=JVM entry identifies the JVM that is being used to run the instance of Directory Proxy Server. The cn=JVM entry has the following monitoring DN:


cn=JVM, cn=instanceId, cn=Instance, cn=DPS60, cn=Product, cn=monitor

Entries below cn=JVM can contain the following groups of attributes:

Settings
  • version identifies the version of the JVM used to run the instance of Directory Proxy Server.

  • JVMInstallation identifies the location of the JVM installation.

State
  • operationalStatus identifies the status of the element, with the following values: 2, and 5. For information about these values, see Table 24–2.

  • statusDescription provides the detailed status description.

Statistics
  • totalJVMMemory identifies the total amount of memory allocated for the JVM to run.

  • maxJVMMemory identifies the maximum amount of JVM memory.

  • freeJVMMemory identifies the amount of free memory.

  • realFreeJVMMemory identifies the free JVM memory which can be used.

  • JVMMemoryLowLevelCount provides the number of times JVM memory changes its state from green to orange.

  • JVMMemoryVeryLowLevelCount provides the number of times JVM memory changes its state from orange to red.

  • availableCPU identifies the CPU capacity available.

cn=Resource

The cn=Resource entry identifies the set of resources being used by the software. Resources include buffers, file descriptors, and hard disks.

The following elements are identified by the cn=Resource entry:

Connection Handler Thread

The connection handler thread decodes incoming requests. The connection handler is oriented to the LDAP or LDAPS protocol. When a request has been fully decoded, the request is put in the work queue.

The cn=Resource entry for the connection handler thread has the following monitoring DN:


cn=connection_handler_thread_name, cn=Connection Handler Thread,
  cn=Resource, cn=instanceId, cn=Instance, cn=DPS60, cn=Product, 
  cn=monitor

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:


cn=Work Queue, cn=Resource, cn=instanceId, cn=Instance, cn=DPS60, 
  cn=Product, cn=monitor

Entries below the cn=Resource entry for the work queue contain the following groups of attributes:

Settings
  • maxNormalPriorityPeak identifies the maximum number of requests of normal priority that can be put in the queue. When this threshold is reached, the connection handler is suspended.

  • maxHighPriorityPeak. identifies the maximum number of requests of high priority that can be put in the queue. When this threshold is reached, the connection handler is suspended.

State
  • curNormalPriorityInQueue provides the current normal priority requests in queue.

  • curHighPriorityInQueue provides the current high priority requests in queue.

  • operationalStatus identifies the status of the element, with the following values: 2, and 4. For information about these values, see Table 24–2.

  • statusDescription provides the detailed status description.

Statistics
  • numNormalPriorityPuts identifies the number of requests of normal priority that are put in the queue by the connection handler threads.

  • numNormalPriorityGets identifies the number of request of normal priority retrieved from the queue by worker threads.

  • numHighPriorityPuts identifies the number of requests of high priority that are put in the queue by the connection handler threads.

  • numHighPriorityGets identifies the number of request of high priority retrieved from the queue by worker threads.

  • numAbandonRequests identifies the number of requests that are abandoned.

  • numAbandonSuccesses identifies the number of requests that are abandoned while in the queue.

Worker Thread

The worker thread processes requests from the work queue.

The cn=Resource entry for the worker thread has the following monitoring DN:


cn=worker_thread_name, cn=Worker Thread, cn=Resource,
  cn=instanceId, cn=Instance, cn=DPS60, cn=Product, cn=monitor

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

Statistics
  • operationsProcessed identifies the number of operations processed by the worker thread.

  • exceptionsCaught identifies the number of exceptions raised during the processing of operations.

Search Thread

When a search is performed on several data views, parallel search threads can be used. The cn=Resource entry for the search thread has the following monitoring DN:


cn=search_thread_name, cn=Search Thread, cn=Resource, cn=instanceId,
  cn=Instance, cn=DPS60, cn=Product, cn=monitor

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:


cn=monitor_thread_name, cn=Monitor Thread, cn=Resource, cn=instanceId,
  cn=Instance, cn=DPS60, cn=Product, cn=monitor

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

Settings
  • backendServer identifies the name of the monitored remote data source.

  • checkInterval identifies the interval of time (in seconds) between two checks.

  • additionalCheckType identifies additional checking. The following values can be used:

    • 1 (no additional checks)

    • 2 (create a bind connection to the data source)

    • 3 (create a read connection to the data source)

State
  • serverAvailable identifies the status of the remote data source. The value is true if the remote data source is up and running.

Statistics
  • totalChecks identifies the total number of checks.

  • availabilityChecksFailed identifies the number of failed availability checks. An availability check is successful when a remote data source is up and running.

  • additionalChecksFailed identifies the number of failed additional checks.

Detailed Layout of the cn=monitor Entry

This section provides a detailed layout of the cn=monitor subtree.


cn=monitor
|
+-- cn=Product (Installed Product)
    |
    +-- cn=ProductName
        || setting:
        || - version
        || - buildNumber
        || - patchId
        +-- cn=Operating System
            || setting:
            || - operatingSystemName
            || - operatingSystemVersion
            || state:
            || - (empty)
            || statisitics:
            || - (empty)
        +-- cn=Instance  (Application System)
            |
            +-- cn=InstanceId (= host:port:instanceDir)
                |
                +-- cn=Service
                    +-- cn=Add
                        || statistics:
                        || - total
                        || - succeeded
                        || - failed
                        || - abandonned (?)
                    +-- cn=Search
                        || (same as Add operation above)
                    +-- cn=Delete
                    +-- cn=Compare
                    +-- cn=Modify
                    +-- cn=ModifyDN
                    +-- cn=Bind
                +-- cn=SAP  (Service Access Point)
                    +-- cn=listenerThread
                        || settings:
                        || - name
                        || - isSecure
                        || - host (?)
                        || - port (?)
                        || state:
                        || - enabled
                        || - operationalStatus
                        || - statusDescription
                        || - startTime
                        || - stopTime
                        || - stopException
                        || statistics:
                        || - acceptedConnections
                        || - refusedConnections
                    +-- cn=listenerThread
                        || (same as above)
                +-- cn=RSAP  (Remote SAP)
                    +-- cn=LDAP Server servername
                        || settings:
                        || - name
                        || - isSecure
                        || - host (?)
                        || - port (?)
                        || state:
                        || - operationalStatus
                        || - statusDescription
                        || - started
                        || - readOnly
                        || statistics:
                        || - totalConnections
                        || - totalAvailableConnections
                        || - totalBindConnections
                        || - availableBindConnections
                        || - bindConnectionsRequested
                        || - bindConnectionsProvided
                        || - bindConnectionsRefused
                        || - bindConnectionsWaitsRequired
                        || - bindConnectionsReturnedValid
                        || - bindConnectionsReturnedInvalid
                        || - (idem for readConnections)
                        || - (idem for writeConnections)
                    +-- cn=LDAPS Server servername
                        || (same as LDAP Server above)
                    +-- cn=RDBM Server servername
                        || settings:
                        || - TBC
                        || state:
                        || - TBC
                        || statistics:
                        || - TBC
                +-- cn=Component  (Logical Component)
                    +-- cn=DataSource Pool poolname
                        +-- cn=Proportional LB
                            || settings:
                            || - classname
                            || state:
                            || - enabled
                            || statistics:
                            || - totalBindConnectionsProvided
                            || - totalBindConnectionsRefused
                            || - totalAddConnectionsProvided
                            || - totalAddConnectionsRefused
                            || - totalCompareConnectionsProvided
                            || - totalCompareConnectionsRefused
                            || - totalDeleteConnectionsProvided
                            || - totalDeleteConnectionsRefused
                            || - totalModifyConnectionsProvided
                            || - totalModifyConnectionsRefused
                            || - totalModifyDNConnectionsProvided
                            || - totalModifyDNConnectionsRefused
                            || - totalCompareConnectionsProvided
                            || - totalCompareConnectionsRefused
                            +-- cn=Add
                                || settings:
                                || - (empty)
                                || status:
                                || - operationalStatus
                                || - statusDescription
                                || statistics:
                                || - providedConnections
                                || - providedPercentage
                                || - refusedConnections
                                || - refusedPercentage
                            +-- cn=Search
                                || (same as Add operation above)
                            +-- cn=Delete
                            +-- cn=Compare
                            +-- cn=Modify
                            +-- cn=ModifyDN
                            +-- cn=Bind
                +-- cn=JVM
                    || settings:
                    || - version
                    || - jvmInstallation
                    || state:
                    || - operationalStatus
                    || - statusDescription
                    || statistics:
                    || - totalJVMMemory
                    || - maxJVMMemory
                    || - freeJVMMemory
                    || - realFreeJVMMemory
                    || - JVMMemoryLowLevelCount
                    || - JVMMemoryVeryLowLevelCount
                    || - availableCPU
                +-- cn=Resource  (System Resource)
                    +-- cn=Worker Thread
                        +-- cn=worker_thread_name
                            || settings:
                            || - threadID
                            || - threadStack
                            || state:
                            || - operationalStatus
                            || - statusDescription
                            || - startTime
                            || - started
                            || - running
                            || statistics:
                            || - operationsProcessed
                            || - exceptionsCaught
                            +-- cn=Byte Buffer Pool
                                || statistics:
                                || - numTries
                                || - numHits
                                || - numMissesEmptyPool
                                || - numMissesBufferSize
                                || - numReleases
                                || - availableStandardBuffers
                                || - availableOversizedBuffers
                            +-- cn=String Buffer Pool
                                || statistics:
                                || - numTries
                                || - numHits
                                || - numMisses
                                || - numReleases
                                || - availableBuffers
                            +-- cn=Vector Pool
                                || statistics:
                                || - numTries
                                || - numHits
                                || - numMisses
                                || - numReleases
                                || - availableVectors
                    +-- cn=Search Thread
                        +-- cn=search_thread_name
                            || settings:
                            ||
                            || state:
                            || - operationalStatus
                            || - startTime
                            || - stopTime
                            || statistics:
                            ||
                            +-- cn=Byte Buffer Pool
                                || (see Worker Thread)
                            +-- cn=String Buffer Pool
                                || (see Worker Thread)
                            +-- cn=vector Pool
                                || (see Worker Thread)
                    +-- cn=Monitor Thread
                        +-- cn=monitor_thread_name
                            || settings:
                            || - started
                            || - running
                            || - startTime
                            || - threadID
                            || - threadStack
                            || - backendServer
                            || - checkInterval
                            || - additionalCheckType
                            || state:
                            || - operationalStatus
                            || - statusDescription
                            || - serverAvailable
                            || statistics:
                            || - totalChecks
                            || - availabilityChecksFailed
                            || - additionalChecksFailed
                            +-- cn=Byte Buffer Pool
                                || (see Worker Thread)
                            +-- cn=String Buffer Pool
                                || (see Worker Thread)
                            +-- cn=vector Pool
                                || (see Worker Thread)
                    +-- cn=Connection Handler Thread
                        +-- cn=connection_handler_thread_name
                            || settings:
                            || - threadID
                            || - threadStack
                            || state:
                            || - operationalStatus
                            || - startTime
                            || - started
                            || - running
                            || - statusDescription
                            || statistics:
                            || - (empty)
                            +-- cn=Byte Buffer Pool
                                || (see Worker Thread)
                            +-- cn=String Buffer Pool
                                || (see Worker Thread)
                            +-- cn=Vector Pool
                                || (see Worker Thread)
                    +-- cn=Work Queue
                        || settings:
                        || - maxNormalPriorityPeak
                        || - maxHighPriorityPeak
                        || - operationalStatus
                        || - statusDescription
                        || state:
                        || - curNormalPriorityInQueue
                        || - curHighPriorityInQueue
                        || statistics:
                        || - numNormalPriorityPuts
                        || - numNormalPriorityGets
                        || - numHighPriorityPuts
                        || - numHighPriorityGets
                        || - numAbandonRequests
                        || - numAbandonSuccesses
                +-- cn=DB System
                +-- cn=DB Service

Chapter 25 Directory Proxy Server File Reference

This chapter describes the files found after you install Directory Proxy Server, and after you create server instances.

The examples shown in this chapter are for Solaris systems. File extensions and path separators may differ for your operating system. This chapter includes the following sections.

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.

install-path/dscc6/lib/

Shared libraries, not intended to be used directly.

install-path/dsee6/

Files shared by multiple Directory Server Enterprise Edition component products. This directory houses the following files of interest.

install-path/dsee6/bin/certutil

NSS certificate manipulation command used by other tools, not intended to be used directly.

install-path/dsee6/bin/dsee_deploy

Command to install and remove software. See dsee_deploy(1M).

install-path/dsee6/bin/ldif

Command to base64 encode LDIF attribute values. See ldif(1)

install-path/dsee6/cacao_2.0/

Common agent container files shared by Directory Server Enterprise Edition component products, not intended to be used directly.

install-path/dsee6/data/

Lists of installed files used by the dsee_deploy command, not intended to be used directly.

install-path/dsee6/lib/

Libraries shared by Directory Server Enterprise Edition component products, not intended to be used directly.

install-path/dsee6/man/

Directory Server Enterprise Edition online reference manual pages. See also Sun Java System Directory Server Enterprise Edition 6.3 Man Page Reference.

install-path/dsee6/private/include/

Directory SDK for C header files used by Directory Server Enterprise Edition component products.

install-path/dsee6/private/lib/

Directory SDK for C shared libraries used by Directory Server Enterprise Edition component products.

install-path/dsrk6/bin/ldapcmp

Directory Server Resource Kit command to compare LDAP entries from two directories. See ldapcmp(1).

install-path/dsrk6/bin/ldapcompare

Directory Server Resource Kit command to perform LDAP compare operations. See ldapcompare(1).

install-path/dsrk6/bin/ldapdelete

Directory Server Resource Kit command to delete directory entries. See ldapdelete(1).

install-path/dsrk6/bin/ldapmodify

Directory Server Resource Kit command to update entries over LDAP. See ldapmodify(1).

install-path/dsrk6/bin/ldappasswd

Directory Server Resource Kit command to change user passwords. See ldappasswd(1).

install-path/dsrk6/bin/ldapsearch

Directory Server Resource Kit command to search a directory. See ldapsearch(1).

install-path/dsrk6/lib/

Libraries used by Directory Server Resource Kit commands, not intended to be used directly.

install-path/jre/

Java Runtime Environment, not intended to be used directly.

install-path/var/

Container for runtime files, not intended to be used directly.

Directory Proxy Server Instance Default Layout

This section describes the file layout you find after creating a Directory Proxy Server instance. The instance-path is the file system path where you created the instance.

instance-path/alias/

Certificate database files, not intended to be used directly.

instance-path/config/

Server configuration files, not intended to be used directly.

instance-path/etc/

Additional instance configuration, not intended to be used directly.

instance-path/logs/

Default server logs directory. The following files are stored here.

access logs

This file records information about the requests processed by Directory Proxy Server. For detail about access logs, see Access Logs for Directory Proxy Server.

errors logs

This file records errors, warnings, and informational messages logged during Directory Proxy Server operation. For detail about errors logs, see Error Logs for Directory Proxy Server.

instance-path/tmp/

Server runtime files directory, not intended to be used directly.