Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

Chapter 18 Directory Proxy Server Configuration

This chapter describes how to configure an instance of Directory Proxy Server. The procedures in this chapter use the dpadm and dpconf commands. For information about these commands, see the dpadm(1M) and dpconf(1M) man pages.

The chapter covers the following topics:

Configuration Examples

This section demonstrates two example Directory Proxy Server configurations, one for load balancing, another for data distribution. For more on virtual directory, see Sample Virtual Configurations.

Configuring Directory Proxy Server To Perform Load Balancing

A simple case of load balancing consists of sending search and compare operations to one set of directories, and sending other operations to another set. Directory Proxy Server receives all client operations. The server must determine which set gets the reads, and which set gets the other operations.

The key stages in configuring Directory Proxy Server to handle this load balancing scenario are as follows.

Add directories as data sources for Directory Proxy Server.
Add the data sources to a data source pool.
Configure some of the data sources to accept search and compare, other data sources to accept add, bind, delete, modify, and modify DN operations.
Add the data source pool to a data view.

The following example involves Directory Proxy Server, listening on port 9389. The proxy is configured here to balance the load as described across one Directory Server instance, ds1:1389, handling search and compare operations, and another Directory Server instance, ds2:2389, handling other operations.

The first step creates the data sources, and enables the data sources. This step requires a proxy server restart.

$ dpconf create-ldap-data-source -p 9389 ds1 localhost:1389
$ dpconf create-ldap-data-source -p 9389 ds2 localhost:2389
$ dpconf set-ldap-data-source-prop -p 9389 ds1 is-enabled:true
$ dpconf set-ldap-data-source-prop -p 9389 ds2 is-enabled:true
$ dpadm restart /local/dps

The second step adds the data sources to a data source pool.

$ dpconf create-ldap-data-source-pool -p 9389 "Directory Pool"
$ dpconf attach-ldap-data-source -p 9389 "Directory Pool" ds1 ds2

The third step configures ds1 to accept search and compare operations, ds2 to accept other operations.

$ dpconf set-attached-ldap-data-source-prop -p 9389 "Directory Pool" ds1 \
add-weight:disabled bind-weight:disabled compare-weight:1 delete-weight:disabled \
modify-dn-weight:disabled modify-weight:disabled search-weight:1
$ dpconf set-attached-ldap-data-source-prop -p 9389 "Directory Pool" ds2 \
add-weight:1 bind-weight:1 compare-weight:disabled delete-weight:1 \
modify-dn-weight:1 modify-weight:1 search-weight:disabled

The fourth step adds the data source pool to a data view, so that client application requests are routed to the pool.

$ dpconf create-ldap-data-view -p 9389 "Balanced View" "Directory Pool" \
dc=example,dc=com

Configuring Directory Proxy Server for Distribution of Suffix Data

A simple case of data distribution consists of storing entries having UIDs beginning with A through M in one set of directories, and storing entries having UIDs beginning with N through Z in another set of directories. Directory Proxy Server receives all client operations. The server must determine which set of directories handles A through M, and which set handles N through Z.

The key stages in configuring Directory Proxy Server to handle this data distributions scenario are as follows.

Add directories as data sources for Directory Proxy Server.
Add the data sources to data source pools to handle the different data distributions.
Create data views designed to distribute client requests to the appropriate data pools.
Split the LDIF to be loaded into the appropriate data sources.
Import the split LDIF into the appropriate data sources.
Adjust the operation based weights for the data sources attached to the appropriate data pools.

The following example involves Directory Proxy Server, listening on port 9389. To keep the example simple, the proxy is configured here to distribute as described across only three Directory Server instances. For availability and read scalability, use replicated directory topologies to store LDAP data. One Directory Server instance, dsA-M:1389 handles the user entries having UIDs beginning with A through M. Another Directory Server instance, dsN-Z:2389, handles the user entries having UIDs beginning with N through Z. A final directory instance handles the base entries of the suffix, dsBase:3389.

The first step creates and enables the data sources. The base data source holds entries near the root of the suffix that do not have UIDs. In a typical deployment, these entries would be much fewer in number than distributed entries.

$ dpconf create-ldap-data-source -p 9389 dsA-M localhost:1389
$ dpconf set-ldap-data-source-prop -p 9389 dsA-M is-enabled:true

$ dpconf create-ldap-data-source -p 9389 dsN-Z localhost:2389
$ dpconf set-ldap-data-source-prop -p 9389 dsN-Z is-enabled:true

$ dpconf create-ldap-data-source -p 9389 dsBase localhost:3389
$ dpconf set-ldap-data-source-prop -p 9389 dsBase is-enabled:true

The second step adds the data sources to a data source pool.

$ dpconf create-ldap-data-source-pool -p 9389 "Base Pool"
$ dpconf attach-ldap-data-source -p 9389 "Base Pool" dsBase

$ dpconf create-ldap-data-source-pool -p 9389 "A-M Pool"
$ dpconf attach-ldap-data-source -p 9389 "A-M Pool" dsA-M

$ dpconf create-ldap-data-source-pool -p 9389 "N-Z Pool"
$ dpconf attach-ldap-data-source -p 9389 "N-Z Pool" dsN-Z

The third step creates data views designed to distribute client requests to the appropriate data pools. Notice how the base pool handles dc=example,dc=com, whereas the pools holding data distributed according to UID values handle ou=people,dc=example,dc=com. This step requires a server restart.

$ dpconf create-ldap-data-view -p 9389 "Base View" "Base Pool" \
dc=example,dc=com

$ dpconf create-ldap-data-view -p 9389 "A-M View" "A-M Pool" \
ou=people,dc=example,dc=com
$ dpconf set-ldap-data-view-prop -p 9389 "A-M View" \
distribution-algorithm:lexicographic lexicographic-attrs:uid \
lexicographic-lower-bound:a lexicographic-upper-bound:m
The proxy server will need to be restarted in order for the changes to take effect

$ dpconf create-ldap-data-view -p 9389 "N-Z View" "N-Z Pool" \
ou=people,dc=example,dc=com
$ dpconf set-ldap-data-view-prop -p 9389 "N-Z View" \
distribution-algorithm:lexicographic lexicographic-attrs:uid \
lexicographic-lower-bound:n lexicographic-upper-bound:z
The proxy server will need to be restarted in order for the changes to take effect
$ dpadm restart /local/dps

The fourth step splits the LDIF to be loaded into the appropriate data sources. This example uses both the dsadm split-ldif command to perform the initial split, and also some file editing to retain the top entry in all the data sources. This makes it possible both to retain the top entry that specifies access control instructions, and to use a single import command for each data source.

$ dpadm split-ldif /local/dps /local/ds6/ldif/Example.ldif /tmp/
[14/May/2007:21:14:13 +0200] - STARTUP    - INFO  - Java Version: 1.5.0_09
 (Java Home: /local/jre)
[14/May/2007:21:14:13 +0200] - STARTUP    - INFO  - Java Heap Space: Total Memory
 (-Xms) = 3MB,
 Max Memory (-Xmx) = 63MB
[14/May/2007:21:14:13 +0200] - STARTUP    - INFO  - Operating System: SunOS/sparc 5.10
[14/May/2007:21:14:15 +0200] - INTERNAL   - ERROR - Entry starting at line 0 does not
 start with a DN
[14/May/2007:21:14:15 +0200] - INTERNAL   - ERROR - Unable to parse line "# Kirsten is
 a Directory Administrator and therefore should not" of entry "uid=kvaughan, ou=People,
 dc=example,dc=com" starting at line 112 as an attribute/value pair -- no colon found.
[14/May/2007:21:14:15 +0200] - INTERNAL   - ERROR - Unable to parse line "# Robert is
 a Directory Administrator and therefore should not" of entry "uid=rdaugherty,
 ou=People, dc=example,dc=com" starting at line 298 as an attribute/value pair --
 no colon found.
[14/May/2007:21:14:16 +0200] - INTERNAL   - ERROR - Unable to parse line "# Harry is
 a Directory Administrator and therefore should not" of entry "uid=hmiller, ou=People,
 dc=example,dc=com" starting at line 556 as an attribute/value pair -- no colon found.
[14/May/2007:21:14:16 +0200] - INTERNAL   - INFO  - SplitLDIF processing complete.
  Processed 156 entries.
$ ls /tmp/*ldif
/tmp/a-m view.ldif    /tmp/base view.ldif   /tmp/n-z view.ldif

This step also requires a top entry that is added to the LDIF before import.

$ cp /local/ds6/ldif/Example.ldif /tmp/top.ldif
$ vi /tmp/top.ldif 
$ cat /tmp/top.ldif  
dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc: example
aci: (target ="ldap:///dc=example,dc=com")(targetattr !=
 "userPassword")(version 3.0;acl "Anonymous read-search access";
 allow (read, search, compare)(userdn = "ldap:///anyone");)
aci: (target="ldap:///dc=example,dc=com") (targetattr =
  "*")(version 3.0; acl "allow all Admin group"; allow(all) groupdn =
  "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

$ cat /tmp/top.ldif /tmp/base\ view.ldif > /tmp/top\ and\ base\ view.ldif
$ cat /tmp/top.ldif /tmp/a-m\ view.ldif > /tmp/top\ and\ a-m\ view.ldif
$ cat /tmp/top.ldif /tmp/n-z\ view.ldif > /tmp/top\ and\ n-z\ view.ldif

The fifth step imports the split LDIF into the appropriate data sources. Here, the directory handling the base entries is on port 3389. The directory handling A-M is listening on port 1389. The directory handling N-Z is listening on port 2389.

$ dsconf import -p 1389 /tmp/top\ and\ a-m\ view.ldif dc=example,dc=com
...
Task completed (slapd exit code: 0).

$ dsconf import -p 2389 /tmp/top\ and\ n-z\ view.ldif dc=example,dc=com
...
Task completed (slapd exit code: 0).
$ dsconf import -p 3389 /tmp/top\ and\ base\ view.ldif dc=example,dc=com
...
Task completed (slapd exit code: 0).

The sixth step adjusts the operation based weights for the data sources attached to the appropriate data pools. If client applications perform operations other than searches, then weights must be set for those operations as well.

$ dpconf set-attached-ldap-data-source-prop -p 9389 "Base Pool" dsBase search-weight:1
$ dpconf set-attached-ldap-data-source-prop -p 9389 "A-M Pool" dsA-M search-weight:1
$ dpconf set-attached-ldap-data-source-prop -p 9389 "N-Z Pool" dsN-Z search-weight:1

After the operations based weights are set, client applications can search through Directory Proxy Server as if the data were not physically distributed.

The following search looks for a user whose UID begins with R.

$ ldapsearch -p 9389 -b dc=example,dc=com uid=rfisher
version: 1
dn: uid=rfisher, ou=People, dc=example,dc=com
cn: Randy Fisher
sn: Fisher
givenName: Randy
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
ou: Human Resources
ou: People
l: Cupertino
uid: rfisher
mail: rfisher@example.com
telephoneNumber: +1 408 555 1506
facsimileTelephoneNumber: +1 408 555 1992
roomNumber: 1579

The next search looks for one of the base entries.

$ ldapsearch -p 9389 -b ou=groups,dc=example,dc=com cn=hr\ managers
version: 1
dn: cn=HR Managers,ou=groups,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: HR Managers
ou: groups
uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com
uniqueMember: uid=cschmith, ou=People, dc=example,dc=com
description: People who can manage HR entries

Modifying the Configuration of Directory Proxy Server

This section describes how to modify the configuration of Directory Proxy Server.

To Modify the Configuration of Directory Proxy Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Find the current configuration of Directory Proxy Server.

$ dpconf get-server-prop -h host -p port

Alternatively, view the current setting of one or more configuration properties.

$ dpconf get-server-prop -h host -p port property-name ...

For example, find whether unauthenticated operations are allowed by running this command:

$ dpconf get-server-prop -h host -p port allow-unauthenticated-operations
allow-unauthenticated-operations  :  true

Change one or more of the configuration parameters.

$ dpconf set-server-prop -h host -p port property:value ...

For example, disallow unauthenticated operations by running this command:

$ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:false

If you attempt to perform an illegal change, the change is not made. For example, if you set the allow-unauthenticated-operations parameter to f instead of false, the following error is produced:

$ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:f
The value "f" is not a valid value for the property "allow-unauthenticated-operations".
Allowed property values: BOOLEAN
The "set-server-prop" operation failed.

If necessary, restart the instance of Directory Proxy Server for the changes to take effect.

For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.

Displaying Directory Proxy Server Instance Configuration Information

To display the Directory Proxy Server instance configurations, type dpconf info.

$ dpconf info
Instance Path           :  instance path
Host Name               :  host
Secure listen address   :  IP address
Port                    :  port
Secure port             :  secure port
SSL server certificate  :  defaultServerCert

Directory Proxy Server needs to be restarted.

dpconf info displays Secure listen address and Non-secure listen address only if these properties are set to non-default values. The above output does not display Non-secure listen address, as this property is not set to a non-default value.

dpconf info also reminds the user to restart the instance if it needs to be restarted.

You can also use dpadm info to display Directory Proxy Server instance configuration information.

Backing Up and Restoring a Directory Proxy Server Instance

When you use dpadm to back up Directory Proxy Server, the configuration files and server certificates are backed up. If you have implemented Directory Proxy Server virtual ACIs, the ACIs are also backed up.

Directory Proxy Server automatically backs up the conf.ldif file whenever the server starts successfully.

To Back Up a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Stop the instance of Directory Proxy Server.
$ dpadm stop instance-path

Back up the instance of Directory Proxy Server.
$ dpadm backup instance-path archive-dir
The archive-dir directory is created by the backup command and must not exist before you run the command. This directory contains a backup of each of the configuration files and the certificates.

To Restore a Directory Proxy Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

You must create a Directory Proxy Server instance before starting the restore operation.

Stop the instance of Directory Proxy Server.
$ dpadm stop instance-path

Restore the instance of Directory Proxy Server.
$ dpadm restore instance-path archive-dir
- If the instance path exists, the restore operation is performed silently. The configuration files and the certificates in the archive-dir directory replace those in the instance-path directory.
- If the instance path does not exist, the restore operation fails.

Configuring the Proxy Manager

The Proxy Manager is the privileged administrator, comparable to the root user on UNIX® systems. The Proxy Manager entry is defined when an instance of Directory Proxy Server is created. The default DN of the Proxy Manager is cn=Proxy Manager.

You can view and change the Proxy Manager DN and password, as shown in the following procedure.

To Configure the Proxy Manager

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Find the configuration of the Proxy Manager.

$ dpconf get-server-prop -h host -p port configuration-manager-bind-dn configuration-manager-bind-pwd
configuration-manager-bind-dn   :  cn=proxy manager
configuration-manager-bind-pwd  :  {3DES}U77v39WX8MDpcWVrueetB0lfJlBc6/5n

The default value for the Proxy Manager is cn=proxy manager. A hashed value is returned for the configuration manager password.

Change the DN of the Proxy Manager.

$ dpconf set-server-prop -h host -p port configuration-manager-bind-dn:bindDN

Create a file that contains the password for the Proxy Manager and set the property that points to that file.
$ dpconf set-server-prop -h host -p port configuration-manager-bind-pwd-file:filename

Configuration Changes Requiring Server Restart

Most configuration changes to Directory Proxy Server and its entities can be made online. Certain changes require that the server be restarted before the changes take effect. If you make configuration changes to any properties in the following list, the server must be restarted:

aci-data-view
bind-dn
client-cred-mode
custom-distribution-algorithm
db-name
db-pwd
db-url
db-user
distribution-algorithm
ldap-address
ldap-port
ldaps-port
listen-address
listen-port
load-balancing-algorithm
num-bind-init
num-read-init
num-write-init
number-of-search-threads
number-of-threads
number-of-worker-threads
ssl-policy
use-external-schema

The rws and rwd keywords of a property indicate whether changes to the property require the server to be restarted.

If a property has an rws (read, write, static) keyword, the server must be restarted when the property is changed.
If a property has an rwd (read, write, dynamic) keyword, modifications to the property are implemented dynamically (without restarting the server).

To determine whether a change to a property requires the server to be restarted, run the following command:

$ dpconf help-properties | grep property-name

For example, to determine whether changing the bind DN of an LDAP data source requires the server to be restarted, run the following command:

$ dpconf help-properties | grep bind-dn
connection-handler   	bind-dn-filters        rwd  STRING | any
This property specifies a set of regular expressions. The bind DN 
of a client must match at least one regular expression in order for 
the connection to be accepted by the connection handler. (Default: any)
ldap-data-source      bind-dn               rws  DN | ""
This property specifies the DN to use when binding to the LDAP data 
source. (Default: undefined)

To determine whether the server must be restarted following a configuration change, run the following command:

$ dpconf get-server-prop -h host -p port is-restart-required

Accessing Configuration Entries for a Directory Server by Using Directory Proxy Server

The configuration entries for Directory Proxy Server are in cn=config. When you use Directory Proxy Server to access configuration entries, by default, you access the configuration entries of Directory Proxy Server.

To access the configuration entries of a directory server, it is better to connect directly to Directory Server, not to Directory Proxy Server. For information about how to configure Directory Server, see Chapter 3, Directory Server Configuration.

Caution –

If you reconfigure Directory Proxy Server to access the configuration entries of a directory server, you are likely to break the administration framework of Directory Proxy Server.

If you really need to access the configuration entries of a directory server through Directory Proxy Server, take special steps to ensure that you do not break the administration framework of Directory Proxy Server. This section describes how to access the configuration entries of a directory server by using Directory Proxy Server.

To Access the Configuration Entries of a Directory Server by Using Directory Proxy Server

Create one or more data sources as described in Creating and Configuring LDAP Data Sources.

Create an LDAP data source pool as described in Creating and Configuring LDAP Data Source Pools.

Attach one or more data sources to the data source pool as described in Attaching LDAP Data Sources to a Data Source Pool.
- To expose the configuration entries of one specific data source, attach only one LDAP data source to the LDAP data source pool.
  $ dpconf attach-ldap-data-source -h host -p port pool-name data-source-name
  After performing this step, a client can access the configuration entries of the data source that is connected to Directory Proxy Server.
- To expose the configuration entries of any data source, attach more than one LDAP data source to the LDAP data source pool.
  $ dpconf attach-ldap-data-source -h host -p port pool-name data-source-name \ data-source-name ...
  After performing this step, a client can access the configuration entries of one of the data sources connected to Directory Proxy Server. However, the client cannot know which data source the configuration entries belong to.

Create an LDAP data view to expose cn=config.

$ dpconf create-ldap-data-view -h host -p port view-name pool-name cn=config