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:
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.
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 |
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 |
This section describes how 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.
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 but this command can only be used with the stopped instances.
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.
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.
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.
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.
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 |
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
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.
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.
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 |