Sun JavaTM System Directory Proxy Server provides a browser interface and command-line tools to register and manage instances of Directory Proxy Server. The browser interface is called Directory Service Control Center (DSCC). This chapter describes basic tasks that are required to administer Directory Proxy Server by using DSCC or the command line.
To decide whether to use DSCC or the command line to perform a specific task, see Deciding When to Use DSCC and When to Use the Command Line.
For more information about the administration framework, see Directory Server Enterprise Edition Administration Model in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.
This chapter covers the following topics:
This section describes how to access DSCC for Directory Proxy Server.
Access DSCC in the same way as you would for Directory Server.
See To Access DSCC.
Click on the Proxy Server tab to view and manage Directory Proxy Server.
The following figure shows the initial window for Directory Proxy Server.
Click a Directory Proxy Server instance to view or to manage that server.
For more information about using DSCC, see the online help.
The commands-line tools that you use to work with Directory Proxy Server are called dpadm and dpconf. For information about how to use these commands, see the dpadm(1M) and dpconf(1M) man pages.
This section describes the location of the dpadm and dpconf commands. It also provides information on environment variables, comparisons between the commands, and where to find help for using the commands.
The Directory Proxy Server command-line tools are located in the following directory by default:
install-path/dps6/bin |
Your installation path depends on your operating system. Installation paths for all operating systems are listed in Default Paths and Command Locations.
The dpconf command requires some options that you can preset by using environment variables. If you do not specify an option when using the command, or do not set the environment variable, the default setting will be used. You can configure environment variables for the following options:
User bind DN. Environment variable: LDAP_ADMIN_USER. Default: cn=Proxy Manager.
Password file for the user bind DN. Environment variable: LDAP_ADMIN_PWF. Default: Prompt for password.
Host name or IP address. Environment variable: DIR_PROXY_HOST. Default: localhost.
LDAP port number. Environment variable: DIR_PROXY_PORT. Default: 389 if the server instance is running as root, and 1389 if the server instance is running as a regular user.
Specifies that dpconf should open a clear connection by default. Environment variable: DIR_PROXY_UNSECURED. If this variable is not set, dpconf opens a secure connection by default.
For more details, see the dpconf(1M) man page.
The following table shows a comparison of the dpadm and dpconf commands.
Table 16–1 Comparison of the dpadm and dpconf Commands
|
dpadm Command |
dpconf Command |
---|---|---|
Purpose |
To manage the process or the files on a local instance of Directory Proxy Server |
To configure a local or remote instance of Directory Proxy Server |
User |
Operating system user |
LDAP user |
Local or remote |
The command must be local to the instance, that is, the command must be run on the host on which the server is running. |
The command can be local to the instance but can also be run from anywhere on the network. |
Example uses of the command |
Create an instance of Directory Proxy Server. Start and stop an instance of Directory Proxy Server. Manage the certificate database. |
Modify the configuration of an instance of Directory Proxy Server. Create a data view. Configure load balancing in a data source pool. |
Server state |
The server can be running or stopped. |
The server must be running. |
How the command identifies the server instance |
By specifying the instance path. The instance path can be relative or absolute. |
By specifying the host name or IP address and the port number. The command uses the LDAP port (-p) or the LDAPS secure port (-P). If a port number is not specified on the command line, the environment variable PROXY_PORT is used. If the environment variable is not set, the default ports are used. |
Certain Directory Proxy Server properties can take multiple values. Use the following syntax to specify the following values:
$ dpconf set-container-prop -h host -p port \ property:value [property:value] |
For example, to set multiple writable attributes for an LDAP data view named my-view, type the following command:
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 \ writable-attr:uid writable-attr:cn writable-attr:userPassword |
To add a value to a multi-valued property that already contains values, type the following command:
$ dpconf set-container-prop -h host -p port \ property+:value |
To remove a value from a multi-valued property that already contains values, type the following command:
$ dpconf set-container-prop -h host -p port\ property-:value |
For example, in the scenario described previously, to add sn to the list of writable attributes, type the following command:
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 \ writable-attr+:sn |
To remove cn from the list of writable attributes, type the following command:
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 \ writable-attr-:cn |
For information about how to use the dpadm and dpconf commands, see the dpadm(1M) and dpconf(1M) man pages.
To obtain a list of subcommands, type the appropriate command:
$ dpadm --help |
$ dpconf --help |
To obtain information about how to use a subcommand, type the appropriate command:
$ dpadm subcommand --help |
$ dpconf subcommand --help |
To obtain information about the configuration properties used in the dpconf command, type:
$ dpconf help-properties |
To obtain information about the configuration properties for a subcommand, use this command:
$ dpconf help-properties subcommand-entity |
For example, to find information about the access log properties, type:
$ dpconf help-properties access-log |
To obtain information about a property used in a subcommand, use this command:
$ dpconf help-properties subcommand-entity property |
For example, to find information about the log-search-filters property of the set-access-log-prop subcommand, type:
$ dpconf help-properties access-log log-search-filters |
To list the key properties of a group of entities, such as data views or connection handlers, use the verbose option -v with the list subcommand.
For example, to view the key properties and relative priorities of all of the connection handlers, use this command:
$ dpconf -h host -p port list-connection-handlers -v Name is-enabled priority description -------------------------- ---------- -------- --------------------------- anonymous false 99 unauthenticated connections default connection handler true 100 default connection handler dscc administrators true 1 Administrators connection handler |
For more information about an individual property, see the man page corresponding to that property.
This chapter describes how to administer an instance of Directory Proxy Server. This chapter covers the following topics:
Starting, Stopping, and Restarting a Directory Proxy Server Instance
Performing Load Balancing, Distribution, and Virtualization using Directory Proxy Server Instance
When you create an instance of Directory Proxy Server, the files and directories required for the instance are created in the path that you specify.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
If you use DSCC to create a new server instance, you can choose to copy some or all of the server configuration settings from an existing server.
Create the instance of Directory Proxy Server.
$ dpadm create -p port instance-path |
For example, to create a new instance in the directory /local/dps, use this command:
$ dpadm create -p 2389 /local/dps |
To specify any other parameter of the instance, see the dpadm(1M) man page.
Type a password if required.
Confirm that the instance has been created by verifying the status of the instance.
$ dpadm info instance-path |
(Optional) If you installed Directory Proxy Server using the Sun JavaTM Enterprise System installer or a native package installation, and your OS provides a service management solution, you can enable the server to be managed as a service, as shown in this table.
Operating System |
Command |
---|---|
Solaris 10 |
dpadm enable-service --type SMF instance-path |
Solaris 9 |
dpadm autostart instance-path |
Linux, HP-UX |
dpadm autostart instance-path |
Windows |
dpadm enable-service --type WIN_SERVICE instance-path |
(Optional) Register the server instance, using one of these methods:
Access DSCC through the URL https://localhost:6789 and log in to the browser interface.
Use the command dsccreg add-server.
For details, see the dsccreg(1M) man page.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
(Optional) Stop the Directory Proxy Server instance.
$ dpadm stop instance-path |
If you do not stop the instance, the delete command will stop it automatically. However, if you have enabled the instance in a service management solution, you must stop it manually.
(Optional) If you have previously used DSCC to manage the server, use the command line to unregister the server.
$ dsccreg remove-server /local/dps Enter DSCC administrator's password: /local/dps is an instance of DPS Enter password of "cn=Proxy Manager" for /local/dps: Unregistering /local/dps from DSCC on localhost. Connecting to /local/dps Disabling DSCC access to /local/dps |
For details, see the dsccreg(1M) man page.
(Optional) If you previously enabled the server instance in a service management solution, then disable the server from being managed as a service.
Operating System |
Command |
---|---|
Solaris 10 |
dpadm disable-service --type SMF instance-path |
Solaris 9 |
dpadm autostart --off instance-path |
Linux, HP-UX |
dpadm autostart --off instance-path |
Windows |
dpadm disable-service --type WIN_SERVICE instance-path |
$ dpadm delete instance-path |
This procedure describes how to find the status of an instance 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.
This section provides information about starting, stopping, and restarting Directory Proxy Server from the command line.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Sometimes, a configuration change requires the server to be restarted before the change takes effect. Use this procedure to check whether it is necessary to restart a Directory Proxy Server instance after a configuration change.
View whether it is necessary to restart the server.
$ dpconf get-server-prop -h host -p port is-restart-required |
If the command returns true, you must restart the instance of Directory Proxy Server.
If the command returns false, it is not necessary to restart the instance 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.
Restart Directory Proxy Server.
$ dpadm restart instance-path |
For example, to restart an instance at /local/dps, use this command:
$ dpadm restart /local/dps |
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.
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 |
This chapter describes how to configure certificates on Directory Proxy Server. For information about configuring certificates on Directory Server, see Managing Certificates.
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.
This chapter covers the following topics:
Creating, Requesting and Installing Certificates for Directory Proxy Server
Renewing an Expired CA-Signed Certificate for Directory Proxy Server
Backing Up and Restoring a Certificate Database for Directory Proxy Server
When you create a Directory Proxy Server instance, it has a default self-signed certificate. A self-signed certificate is a public and private key pair, where the public key is self-signed by Directory Proxy Server.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
To run the Secure Sockets Layer (SSL) on Directory Proxy Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution.
The PKI solution involves an external Certificate Authority (CA). For a PKI solution you need a CA-signed server certificate, which contains both a public key and a private key. This certificate is specific to one Directory Proxy Server instance. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes called a CA root key or root certificate.
For information about how to create a non-default self-signed certificate and to request and install a CA-signed certificate, see the following procedures.
When you create a Directory Proxy Server instance, a default self-signed certificate is automatically provided. If you want to create a self-signed certificate with non-default settings, use this procedure.
The procedure creates the public and private key pair for a server certificate, where the public key is signed by Directory Proxy Server. A self-signed certificate is valid for three months.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
To create a non-default self-signed certificate for Directory Proxy Server, type:
$ dpadm add-selfsign-cert instance-path cert-alias |
where cert-alias is the name of the self-signed certificate.
For example, you could create a certificate called my-self-signed-cert as follows:
$ dpadm add-selfsign-cert /local/dps my-self-signed-cert |
For a description of all command options, see the dpadm(1M) man page or type dpadm add-selfsign-cert --help at the command line.
Self-signed certificates are useful for test purposes. However, in a production environment, using trusted Certificate Authority (CA) certificates is more secure.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Request a CA-signed server certificate.
$ dpadm request-cert instance-path cert-alias |
where cert-alias is the name of the certificate that you are requesting. Certificate Authorities might require all of the options of the command to identify the server. For a description of all command options, see the dpadm(1M) man page.
The process for obtaining a CA certificate depends on the CA that you use. Some commercial CAs provide a web site that allows you to download the certificate. Other CAs will send the certificate to you in email.
For example, you could request a certificate called my-CA-signed-cert as follows:
$ dpadm request-cert -S cn=my-request,o=test /local/dps my-CA-signed-cert -----BEGIN NEW CERTIFICATE REQUEST----- MIIBYDCBygIBADAhMQ0wCwYDVQQDEwRnZXJpMRAwDgYDVQQDEwdteWNlcnQ0MIGfMA0GCSqGSIb3 DQEBAQUAA4GNADCBiQKBgQC3v9ubG468wnjBDAMbRrEkmFDTQzT+LO30D/ALLXOiElVsHrtRyWhJ PG9cURI9uwqs15crxCpJvho1kt3SB9+yMB8Ql+CKnCQDHlNAfnn30MjFHShv/sAuEygFsN+Ekci5 W1jySYE2rzE0qKVxWLSILFo1UFRVRsUnORTX/Nas7QIDAQABoAAwDQYJKoZIhvcNAQEEBQADgYEA fcQMnZNLpPobiX1xy1ROefPOhksVz8didY8Q2fjjaHG5lajMsqOROzubsuQ9Xh4ohT8kIA6xcBNZ g8FRNIRAHCtDXKOdOm3CpJ8da+YGI/ttSawIeNAKU1DApF9zMb7c2lS4yEfWmreoQdXIC9YeKtF6 zwbn2EmIpjHzETtS5Nk= -----END NEW CERTIFICATE REQUEST----- |
When you request a certificate by using the dpadm request-cert command, the certificate request is a PKCS #10 certificate request in Privacy Enhanced Mail (PEM) format. PEM is the format specified by RFCs 1421 through 1424. For more information, see http://www.ietf.org/rfc/rfc1421.txt. The PEM format represents a base64-encoded certificate request in ASCII format.
When you request a CA-signed certificate, a temporary self-signed certificate is created. When you receive and install the CA-signed certificate from the CA, the new certificate replaces the temporary self-signed certificate.
Send the certificate request to the CA, according to its procedures.
After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the response time can be short. However, if the CA is external to your company, the CA can take several weeks to respond to your request.
Save the certificate that you receive from the CA.
Save your certificate in a text file, and back up the certificate in a safe location.
To trust the CA-signed server certificate, you must install the certificate on a Directory Proxy Server instance. This procedure installs the public key of a CA certificate to the certificate database on Directory Proxy Server.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
See if the trusted CA certificate for this CA is already installed.
To do this, list all installed CA certificates, as described in To List CA Certificates.
If the trusted CA certificate is not installed, add it to the certificate database on the Directory Proxy Server instance.
$ dpadm add-cert instance-path cert-alias cert-file |
where cert-alias is the name of the trusted CA certificate and cert-file is the name of the file containing the trusted CA certificate.
Install the CA-signed server certificate to the certificate database.
$ dpadm add-cert instance-path cert-alias cert-file |
Where cert-alias is the name of the CA-signed server certificate and cert-file is the name of the file containing the CA-signed server certificate. Note that this cert-alias must be the same as the cert-alias used in the certificate request
For example, you can add a CA-signed server certificate named CA-cert to the certificate database on/local/dps as follows:
$ dpadm add-cert /local/dps CA-cert /local/safeplace/ca-cert-file.ascii |
This section describes how to renew an expired CA-signed server certificate.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Obtain an updated certificate from your CA.
Install the certificate on your instance of Directory Proxy Server.
$ dpadm renew-cert instance-path cert-alias cert-file |
where cert-alias is the name of the new certificate and cert-file is the name of the file containing the certificate. For a description of all command options, see the dpadm(1M) man page.
For information about how to list server and CA certificates, see the following procedures.
This procedure lists all certificates that are installed on an instance 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.
List the server certificates in the certificate database on the Directory Proxy Server instance.
$ dpadm list-certs instance-path |
By default, an instance of Directory Proxy Server contains a server certificate named defaultservercert. The text Same as issuer indicates that the default certificate is a self-signed server certificate.
For example:
$ dpadm list-certs /local/dps Alias Valid from Expires on Self-signed? Issued by Issued to ----------------- ---------------- ---------------- ------------ ------------------ -------------- defaultservercert 2006/06/01 04:15 2008/05/31 04:15 y CN=myserver:myport Same as issuer 1 certificate found. |
This procedure lists CA certificates that are installed on an instance 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.
List the CA certificates in the certificate database on the Directory Proxy Server instance.
$ dpadm list-certs -C instance-path |
For example:
$ dpadm list-certs -C /local/dps Alias Valid from Expires on Built-in Issued by Issued to ------ ---------- ---------------- --------- --------- --------- CAcert1 1999/06/21 06:00 2020/06/21 06:00 y CN=company1, O=company2 ... |
This section describes how to add a certificate from a back-end LDAP server to the certificate database on Directory Proxy Server.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Display the certificate from the back-end Directory Server in PEM format by using this command syntax:
dsadm show-cert -F ascii instance-path [cert-alias] |
If you do not specify a cert-alias, the default server certificate is displayed. For a description of all command options, see the dsadm(1M) man page.
For example, show the default self-signed server certificate as follows:
$ dsadm show-cert -F ascii /local/ds defaultCert -----BEGIN CERTIFICATE----- MIICJjCCAY+gAwIBAgIFAIKL36kwDQYJKoZIhvcNAQEEBQAwVzEZMBcGA1UEChMQ U3VuIE1pY3Jvc3lzdGVtczEZMBcGA1UEAxMQRGlyZWN0b3J5IFNlcnZlcjENMAsG A1UEAxMEMjAxMTEQMA4GA1UEAxMHY29uZHlsZTAeFw0wNjA1MjIxMTQxNTVaFw0w NjA4MjIxMTQxNTVaMFcxGTAXBgNVBAoTEFN1biBNaWNyb3N5c3RlbXMxGTAXBgNV BAMTEERpcmVjdG9yeSBTZXJ2ZXIxDTALBgNVBAMTBDIwMTExEDAOBgNVBAMTB2Nv bmR5bGUwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAK9U3ry3sJmEzwQY8CGd 7S2MTZuBedo03Vea1lfDtD08WIsdDMzhHplTdeHAkWWNc8g2PDcEFXeWp9UXFMuD Pcia7t8HtFkm73VmlriWhMd8nn3l2vkxhsPK2LHFEeOIUDR9LBBiMiEeLkjdoEhE VLMSoYKqKI+Aa5grINdmtFzBAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAF4eDbSd7 qy2l10dIogT+rnXZ362gLTlQFCblhbGpmmptbegUdL1ITGv/62q1isPV2rW7CkjM Cqb0fo3k5UkKKvW+JbMowpQeAPnlgpX612HuDr1tldnKV4eyU7gpG31t/cpACALQ 7OPi1A7oVb2Z8OJKfEJHkp3txBSsiI2gTkk= -----END CERTIFICATE----- |
Save the certificate.
Save your certificate in a text file, and back up the certificate in a safe location.
Add the certificate from the back-end LDAP server to the certificate database on an instance of Directory Proxy Server.
$ dpadm add-cert instance-path cert-alias cert-file |
where cert-alias is the name of the certificate and cert-file is the name of the file containing the certificate.
For example, you could add the certificate defaultCert as follows:
$ dpadm add-cert /local/dps defaultCert /local/safeplace/defaultCert.ascii |
Back-end LDAP servers might require a certificate from Directory Proxy Server. This section describes how to configure Directory Proxy Server to export a certificate to a back-end LDAP server.
Specify the certificate to be sent to the back-end LDAP server.
$ dpconf set-server-prop -h host -p port ssl-client-cert-alias:cert-alias |
Where cert-alias is the name of the certificate. For a description of all command options, see the dpconf(1M) man page.
Copy the contents of the certificate to a file.
$ dpadm show-cert -F ascii -o filename instance-path cert-alias |
Add the certificate to the certificate database for the back-end LDAP server as described in To Add the CA-Signed Server Certificate and the Trusted CA Certificate.
Configure the back-end LDAP server for client authentication. For information about how to do this for Directory Server, see Configuring Credential Levels and Authentication Methods.
For information about configuring certificate-based authentication between clients and Directory Proxy Server, see To Configure Certificate-based Authentication.
Server certificates are backed up when you use dpadm to back up Directory Proxy Server. The backed up certificates are stored in the archive-path/alias directory.
For information about how to back up and restore Directory Proxy Server, see Backing Up and Restoring a Directory Proxy Server Instance.
By default, the password for the certificate database is managed internally. Therefore, you do not need to type a certificate password or specify the password file. When the certificate database is managed internally through a stored password, the password is stored in a secure environment.
For more security and more control over certificates, configure Directory Proxy Server to prompt for a password on the command line. You are then prompted to enter the password for all dpadm subcommands except autostart, backup, disable-service, enable-service, info, restore, and stop.
For information about configuring Directory Proxy Server to prompt or not to prompt for passwords, see the following procedures.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Stop the server.
$ dpadm stop instance-path Directory Proxy Server instance 'instance-path' stopped |
Set the password prompt flag to on, then type and confirm the certificate database password.
$ dpadm set-flags instance-path cert-pwd-prompt=on Choose the certificate database password: Confirm the certificate database password: |
Start the server, then type the certificate database password.
$ dpadm start instance-path Enter the certificate database password: |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Stop the server.
$ dpadm stop instance-path Directory Proxy Server instance 'instance-path' stopped |
Set the password prompt flag to off, then type the existing password.
$ dpadm set-flags instance-path cert-pwd-prompt=off Enter the old password: |
Start the server.
$ dpadm start instance-path |
This chapter describes how to use the dpconf command to create and configure LDAP data sources and data source pools. For reference information about these topics, see LDAP Data Sources in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This chapter covers the following topics:
For information about how to create and configure LDAP data sources, see the following procedures.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
$ dpconf create-ldap-data-source -h host -p port source-name host:port |
In this command, source-name is a name that you assign to the new data source. host and port refer to the host and port on which the LDAP server is running. Note that the data source does not use SSL by default.
If the host is specified by an IP V6 address, you need to use the IP V6 reference when you create the data source. For example, if Directory Proxy Server will bind to a host with the IP V6 address fe80::209:3dff:fe00:8c93 on port 2389, use the following command to create the data source:
$ dpconf create-ldap-data-source -h host1 -p 1389 ipv6-host \ [fe80::209:3dff:fe00:8c93]:2389 |
If you use the console to create the data source, you must specify the actual IP V6 address (without the square brackets).
For information about how to modify the properties of an LDAP data source, see To Configure an LDAP Data Source.
(Optional) View the list of data sources.
$ dpconf list-ldap-data-sources -h host -p port |
This procedure configures authorization between Directory Proxy Server and an LDAP data source. The procedure also configures how Directory Proxy Server monitors an LDAP data source.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the properties of the data source by using this command syntax:
dpconf get-ldap-data-source-prop -h host -p port [-M unit] [-Z unit] source-name [property...] |
In this command, -M and -Z refer to the units in which you want data to be displayed. The M option specifies the unit of time. The value for -M can be M, w, d, h, m, s, or ms, to represent months, weeks, days, hours, minutes, seconds, or miliseconds. The -Z option specifies the data size unit. The value for -Z can be T, G, M, k, or b, to represent Terabytes, Gigabytes, Megabytes, kilobytes, or bytes.
If you do not specify a property, all properties are displayed. The default properties of an LDAP data source are as follows:
bind-dn : - bind-pwd : - client-cred-mode : use-client-identity connect-timeout : 10s description : - is-enabled : false is-read-only : true ldap-address : host ldap-port : port ldaps-port : ldaps monitoring-bind-timeout : 5s monitoring-entry-dn : "" monitoring-entry-timeout : 5s monitoring-inactivity-timeout : 2m monitoring-interval : 30s monitoring-mode : proactive monitoring-search-filter : (|(objectClass=*)(objectClass=ldapSubEntry)) num-bind-incr : 10 num-bind-init : 10 num-bind-limit : 1024 num-read-incr : 10 num-read-init : 10 num-read-limit : 1024 num-write-incr : 10 num-write-init : 10 num-write-limit : 1024 proxied-auth-check-timeout : 1.8s proxied-auth-use-v1 : false ssl-policy : never use-tcp-no-delay : true |
Enable the data source.
$ dpconf set-ldap-data-source-prop -h host -p port source-name is-enabled:true |
Configure all the properties that are listed in Step 1, if you want to change the default settings.
$ dpconf set-ldap-data-source-prop -h host -p port source-name property:value |
For example, if you want to modify entries on a data source, configure the data source to allow write operations.
$ dpconf set-ldap-data-source-prop -h host -p port source-name is-read-only:false |
To find information about a property used in a subcommand, run this command:
$ dpconf help-properties ldap-data-source property |
To list the key properties for data sources, use the verbose option -v with the list subcommand.
$ dpconf list-ldap-data-sources -v Name is-enabled ldap-address ldap-port ldaps-port description ----------- ---------- ------------ --------- ---------- ----------- datasource0 true myHost myPort ldaps - datasource1 true myHost myPort ldaps - |
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. For a list of configuration changes that require a server restart, see Configuration Changes Requiring Server Restart.
For information about how to create and configure data source pools, see the following procedures:
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create one or more data source pools.
$ dpconf create-ldap-data-source-pool -h host -p port pool-name |
Additional data source pools can be specified after the first pool-name. For information about how to modify the properties of a data source pool, see To Configure an LDAP Data Source Pool.
(Optional) View the list of data source pools.
$ dpconf list-ldap-data-source-pools -h host -p port |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the properties of the data source pool by using this command syntax:
dpconf get-ldap-data-source-pool-prop -h host -p port [-M unit] [-Z unit] \ pool-name [property...] |
In this command, -M and -Z refer to the units in which you want data to be displayed. The M option specifies the unit of time. The value for -M can be M, w, d, h, m, s, or ms, to represent months, weeks, days, hours, minutes, seconds, or miliseconds. The -Z option specifies the data size unit. The value for -Z can be T, G, M, k, or b, to represent Terabytes, Gigabytes, Megabytes, kilobytes, or bytes.
If you do not specify a property, all properties are displayed. The default properties of an LDAP data source pool are as follows:
client-affinity-policy : write-affinity-after-write client-affinity-timeout : 20s description : - enable-client-affinity : false load-balancing-algorithm : proportional |
Configure the properties that are listed in Step 1.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ property:value |
For information about how to configure the properties of a data source pool for load balancing and client affinity, see Chapter 21, Directory Proxy Server Load Balancing and Client Affinity.
A data source that is attached to a data source pool is called an attached data source. The properties of an attached data source determine the load balancing configuration of the data source pool. When you configure the weights of an attached data source, consider the weights of all of the attached data sources in a data source pool. Ensure that the weights work together as required. For information about how to configure weights for load balancing, see To Configure Weights for Load Balancing.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Attach one or more data sources to a data source pool.
$ dpconf attach-ldap-data-source -h host -p port pool-name \ source-name [source-name ...] |
(Optional) View the list of attached data sources for a given data source pool.
$ dpconf list-attached-ldap-data-sources -h host -p port -E pool-name |
In this command, -E is optional, and modifies the display output to show one property value per line.
(Optional) View the key properties of the attached data sources for a given data source pool.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name |
In this command, -v specifies verbose output. For example, view the properties of an example data source pool.
$ dpconf list-attached-ldap-data-sources -h host1 -p 1389 -v My-pool Name add-weight bind-weight compare-weight ----------- ---------- ----------- -------------- datasource0 disabled disabled disabled datasource1 disabled disabled disabled delete-weight modify-dn-weight modify-weight search-weight ------------- ---------------- ------------- ------------- disabled disabled disabled disabled disabled disabled disabled disabled |
(Optional) View the properties of an attached data source by using the following command syntax:
$ dpconf get-attached-ldap-data-source-prop -h host -p port [-M unit] [-Z unit] \ pool-name source-name [property...] |
In this command, -M and -Z refer to the units in which you want data to be displayed. The M option specifies the unit of time. The value for -M can be M, w, d, h, m, s, or ms, to represent months, weeks, days, hours, minutes, seconds, or miliseconds. The -Z option specifies the data size unit. The value for -Z can be T, G, M, k, or b, to represent Terabytes, Gigabytes, Megabytes, kilobytes, or bytes.
If you do not specify a property, all properties are displayed.
The properties of an attached data source define the weight for each type of operation in load balancing. The default weights of an attached data source are as follows:
add-weight : disabled bind-weight : disabled compare-weight : disabled delete-weight : disabled modify-dn-weight : disabled modify-weight : disabled search-weight : disabled |
For information about how to configure weights of an attached data source for load balancing, see To Configure Weights for Load Balancing.
For a description of load balancing and client affinity, see Chapter 16, Directory Proxy Server Load Balancing and Client Affinity, in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This chapter covers the following topics:
For information about load balancing, see Load Balancing in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This section explains how to configure load balancing and provides sample configurations.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Obtain the current load balancing algorithm by viewing the properties of the LDAP data source pool.
$ dpconf get-ldap-data-source-pool-prop -h host -p port pool-name |
The default properties of an LDAP data source pool are as follows:
client-affinity-policy : write-affinity-after-write client-affinity-timeout : 20s description : - enable-client-affinity : false load-balancing-algorithm : proportional |
By default, the load balancing algorithm is proportional.
Configure the LDAP data source pool to use an algorithm.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ load-balancing-algorithm:selected-algorithm |
where selected-algorithm is one of the following:
failover
operational-affinity
proportional
saturation
For more information about the algorithms, see Introduction to Load Balancing in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
Restart the instance of Directory Proxy Server.
$ dpadm restart instance-path |
You need to configure the weights of an attached data source in relation to the weights of any other attached data sources in the data source pool. Consider the weights of all of your attached data sources. If a data source has a weight of disabled for a type of operation, requests of that type are never sent to that data source. If a data source has a weight of 0 (zero), no requests are distributed to that data source unless all other data sources are unavailable. Therefore, data sources configured with a weight of 0 are used only when all other data sources are down.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the list of data sources that are attached to the data source pool.
$ dpconf list-attached-ldap-data-sources -h host -p port pool-name |
View the properties of one of the attached data sources.
$ dpconf get-attached-ldap-data-source-prop pool-name \ attached-data-source-name |
The properties of an attached data source define the weight for each type of operation. The default weights of an attached data source are as follows:
add-weight : disabled bind-weight : disabled compare-weight : disabled delete-weight : disabled modify-dn-weight : disabled modify-weight : disabled search-weight : disabled |
Configure the weights of one of the attached data sources.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name \ attached-data-source-name add-weight:value \ bind-weight:value compare-weight:value delete-weight:value \ modify-dn-weight:value modify-weight:value search-weight:value |
Repeat Step 2 and Step 3 for the other attached data sources.
Compare the key parameters of the attached data sources.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name |
For example, a data source pool can contain data sources with the following weights:
$ dpconf list-attached-ldap-data-sources -h host1 -p 1389 -v myPool Name add-weight bind-weight compare-weight delete-weight modify-dn-weight modify-weight search-weight ---- ---------- ----------- -------------- ------------- ---------------- ------------- ------------- DS-1 disabled 3 disabled disabled disabled disabled disabled DS-2 2 2 2 2 2 2 2 DS-3 1 1 1 1 1 1 1 |
This section contains sample procedures for configuring each of the load balancing algorithms.
For a description of the proportional algorithm, see Proportional Algorithm for Load Balancing in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
In this example, the data source ds–1 is configured with twice the weight of the other two data sources.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Chapter 20, LDAP Data Sources and Data Source Pools.
Configure the data source pool to use the proportional algorithm for load balancing.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ load-balancing-algorithm:proportional |
Configure the properties of the first data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \ add-weight:2 bind-weight:2 compare-weight:2 delete-weight:2 modify-dn-weight:2 \ modify-weight:2 search-weight:2 |
Configure the properties of the second data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Configure the properties of the third data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Compare the key parameters of the attached data sources.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name Name add-weight bind-weight compare-weight delete-weight modify-dn-weight modify-weight search-weight --- ---------- ----------- -------------- ------------- ---------------- ------------- ------------- ds-1 2 2 2 2 2 2 2 ds-2 1 1 1 1 1 1 1 ds-3 1 1 1 1 1 1 1 |
Restart the instance of Directory Proxy Server.
$ dpadm restart instance-path |
For a description of the saturation algorithm, see Saturation Algorithm for Load Balancing in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
In this example, the data source ds-1 performs the majority of bind operations but does not perform any other types of operations. The three data sources are configured with the following weights :
ds-1 is configured with weight 3 for bind operations and is disabled for all other types of operations.
ds-2 is configured with weight 2 for all operations.
ds-3 is configured with weight 1 for all operations.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Chapter 20, LDAP Data Sources and Data Source Pools.
Configure the data source pool to use the saturation algorithm for load balancing.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ load-balancing-algorithm:saturation |
Configure the properties of the first data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \ add-weight:disabled bind-weight:3 compare-weight:disabled delete-weight:disabled \ modify-dn-weight:disabled modify-weight:disabled search-weight:disabled |
Configure the properties of the second data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \ add-weight:2 bind-weight:2 compare-weight:2 delete-weight:2 modify-dn-weight:2 \ modify-weight:2 search-weight:2 |
Configure the properties of the third data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Compare the key parameters of the attached data sources.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name Name add-weight bind-weight compare-weight delete-weight modify-dn-weight modify-weight search-weight --- ---------- ----------- -------------- ------------- ---------------- ------------- ------------- ds-1 disabled 3 disabled disabled disabled disabled disabled ds-2 2 2 2 2 2 2 2 ds-3 1 1 1 1 1 1 1 |
Restart the instance of Directory Proxy Server.
$ dpadm restart instance-path |
For a description of this algorithm, Operational Affinity Algorithm for Global Account Lockout in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This example has three data sources. The data source ds-1 is configured to receive all bind requests.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Chapter 20, LDAP Data Sources and Data Source Pools.
Configure the data source pool to use the operational affinity algorithm.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ load-balancing-algorithm:operational-affinity |
Configure the properties of the first data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \ add-weight:1 bind-weight:100 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Configure the properties of the second data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Configure the properties of the third data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Compare the key parameters of the attached data sources.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name Name add-weight bind-weight compare-weight delete-weight modify-dn-weight modify-weight search-weight -- ---------- ----------- -------------- ------------- ---------------- ------------- ------------- ds-1 1 1 1 1 1 1 1 ds-2 1 100 1 1 1 1 1 ds-3 1 1 1 1 1 1 1 |
Restart the instance of Directory Proxy Server.
$ dpadm restart instance-path |
For a description of this algorithm, see Operational Affinity Algorithm for Cache Optimization in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This example has three data sources. All search and compare operations are treated by the data source ds-1. When ds-1 responds to a request, the targeted entry is stored in the cache. If ds-1 responds repeatedly to the same request, the data source can use cached data.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Chapter 20, LDAP Data Sources and Data Source Pools.
Configure the data source pool to use the operational affinity algorithm.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ load-balancing-algorithm:operational-affinity |
Configure the properties of the first data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \ add-weight:1 bind-weight:1 compare-weight:100 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:100 |
Configure the properties of the second data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Configure the properties of the third data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Compare the key parameters of the attached data sources.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name Name add-weight bind-weight compare-weight delete-weight modify-dn-weight modify-weight search-weight --- ---------- ----------- -------------- ------------- ---------------- ------------- ------------- ds-1 1 1 100 1 1 1 100 ds-2 1 1 1 1 1 1 1 ds-3 1 1 1 1 1 1 1 |
Restart the instance of Directory Proxy Server.
$ dpadm restart instance-path |
For a description of the failover algorithm, see Failover Algorithm for Load Balancing in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This example has three data sources. The data source ds-1 receives all requests. If ds-1 fails, ds-2 receives all requests until ds-1 recovers. If ds-2 fails before ds-1 recovers, ds-3 receives all requests.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Ensure that you have a data source pool with at least three attached data sources. For information about how to create data sources and data source pools, see Chapter 20, LDAP Data Sources and Data Source Pools.
Configure the data source pool to use the failover algorithm for load balancing.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ load-balancing-algorithm:failover |
Configure the properties of the first data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-1 \ add-weight:3 bind-weight:3 compare-weight:3 delete-weight:3 modify-dn-weight:3 \ modify-weight:3 search-weight:3 |
Configure the properties of the second data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-2 \ add-weight:2 bind-weight:2 compare-weight:2 delete-weight:2 modify-dn-weight:2 \ modify-weight:2 search-weight:2 |
Configure the properties of the third data source.
$ dpconf set-attached-ldap-data-source-prop -h host -p port pool-name ds-3 \ add-weight:1 bind-weight:1 compare-weight:1 delete-weight:1 modify-dn-weight:1 \ modify-weight:1 search-weight:1 |
Compare the key parameters of the attached data sources.
$ dpconf list-attached-ldap-data-sources -h host -p port -v pool-name Name add-weight bind-weight compare-weight delete-weight modify-dn-weight modify-weight search-weight --- ---------- ----------- -------------- ------------- ---------------- ------------- ------------- ds-1 3 3 3 3 3 3 3 ds-2 2 2 2 2 2 2 2 ds-3 1 1 1 1 1 1 1 |
Restart the instance of Directory Proxy Server.
$ dpadm restart instance-path |
Client affinity reduces the risk of propagation delay in load-balanced deployments. For information about client affinity, see Client Affinity in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This section explains how to configure affinity between a client connection and a data source, and provides sample configurations.
This procedure describes how to configure affinity between a client connection and a data source.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the current load balancing algorithm by viewing the properties of the data source pool.
$ dpconf get-ldap-data-source-pool-prop -h host -p port pool-name |
The default properties of a data source pool are as follows:
client-affinity-policy : write-affinity-after-write client-affinity-timeout : 20s description : - enable-client-affinity : false load-balancing-algorithm : proportional |
These parameters configure client affinity: client-affinity-policy, client-affinity-timeout, and enable-client-affinity. For a description of the properties and a list of their valid values, type:
dpconf help-properties ldap-data-source-pool client-affinity-policy \ client-affinity-timeout enable-client-affinity |
For more information about the properties, see these man pages: client-affinity-policy(5dpconf), client-affinity-timeout(5dpconf), and enable-client-affinity(5dpconf).
Enable client affinity.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ enable-client-affinity:true |
Select a policy for client affinity.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ client-affinity-policy:selected-policy |
where selected-policy is one of the following:
Affinity for write requests after the first write request
Affinity for all requests after the first write request
Affinity for all requests after the first read request or write request
Affinity for the first read request after a write request
Configure the duration of the client affinity.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ client-affinity-timeout:time-out[unit] |
The default unit for timeout is milliseconds.
This section contains example configurations related to client affinity, and includes examples for replication delay, verifying write operations, and connection-based routing.
This procedure configures client affinity for all read and write operations that occur up to three seconds after the first write operation.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the affinity parameters for the data source pool.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ client-affinity-policy:read-write-affinity-after-write client-affinity-timeout:3000 \ enable-client-affinity:true |
This procedure configures client affinity for the first read operation after each write operation. The example could be for an application where a specified bind DN validates each write operation by performing a read operation.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the affinity parameters for the data source pool.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ client-affinity-policy:read-affinity-after-write enable-client-affinity:true |
In versions prior to Directory Proxy Server 6.0, one connection was opened between a client and an LDAP server. The same connection was used for all requests from the client until the connection was closed. This type of routing is called connection-based routing. This procedure describes how to configure client affinity for connection-based routing.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Ensure that all data sources are attached to the data source pool and that clientCredentialsForwarding is set to useBind.
Configure the affinity parameters for the data source pool.
$ dpconf set-ldap-data-source-pool-prop -h host -p port pool-name \ client-affinity-policy:read-write-affinity-after-any enable-client-affinity:true |
For an overview of Directory Proxy Server distribution and a description of example use cases, see Chapter 17, Directory Proxy Server Distribution, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This chapter covers the following topics:
For information about how to create and configure LDAP data views, see the following procedures:
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create an LDAP data view.
$ dpconf create-ldap-data-view -h host -p port view-name pool-name suffix-DN |
For information about how to modify the properties of an LDAP data view, see To Configure an LDAP Data View.
View the list of LDAP data views.
$ dpconf list-ldap-data-views -h host -p port |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the properties of an LDAP data view.
$ dpconf get-ldap-data-view-prop -h host -p port view-name |
If you create a data view without configuring any of the properties, your data view has the following configuration:
alternate-search-base-dn : "" attr-name-mappings : none base-dn : suffix-DN contains-shared-entries : false custom-distribution-algorithm-class : none description : - distribution-algorithm : none dn-join-rule : none dn-mapping-attrs : none dn-mapping-source-base-dn : none excluded-subtrees : - filter-join-rule : none is-enabled : true is-read-only : false is-routable : true ldap-data-source-pool : pool-name lexicographic-attrs : all lexicographic-lower-bound : none lexicographic-upper-bound : none non-viewable-attr : none non-writable-attr : none numeric-attrs : all numeric-default-data-view : false numeric-lower-bound : none numeric-upper-bound : none pattern-matching-base-object-search-filter : all pattern-matching-dn-regular-expression : all pattern-matching-one-level-search-filter : all pattern-matching-subtree-search-filter : all process-bind : - replication-role : master viewable-attr : all except non-viewable-attr writable-attr : all except non-writable-attr |
All users except the Proxy Manager see the cn=config and cn=monitor suffixes from the back-end server. By default, data from the back-end servers is not available to the Proxy Manager. The cn=config and cn=monitor subtrees that are available to the Proxy Manager are those of the proxy itself.
When you create a Directory Proxy Server instance, a connection handler for the Proxy Manager is created with an empty data view policy. If the Proxy Manager requires access to back-end data, you must add a data view to the data view policy of the Proxy Manager connection handler. On such a data view, the cn=config and cn=monitor subtrees are excluded by default.
Change one or more of the properties that are listed in Step 1.
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ property:value [property:value ... ] |
For example, to access the dc=example,dc=com subtree on a data source, specify base-dn in the data view.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView base-dn:dc=example,dc=com |
To add a value to a multi-valued property, use this command:
$ dpconf set-ldap-data-view-prop -h host -p port view-name property+:value |
To remove a value from a multi-valued property, use this command:
$ dpconf set-ldap-data-view-prop -h host -p port view-name property-:value |
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.
Custom distribution algorithm can be configured for all types of data views, that is, ldap-data-view, jdbc-data-view, ldif-data-view, and join-data-view. In the following procedure the algorithm is set only for ldap-data-view.
Set the extension-jar-file-url property to contain the path of the Java Archive (JAR) file containing your distribution algorithm class.
$ dpconf set-server-prop -h host -p port extension-jar-file-url:jar file path |
The jar file path can be replaced with a valid JAR file path such as file:/expt/dps/custom_plugin/myjar.jar.
Before you configure custom-distribution-algorithm, set distribution-algorithm to none.
$ dpconf set-ldap-data-view-prop view name distribution-algorithm:none |
Set the custom-distribution-algorithm property to your custom distribution algorithm class.
$ dpconf set-ldap-data-view-prop view name custom-distribution-algorithm:PackageName.AlgoClassName |
Each entry in a directory is identified by a DN and a set of attributes and their values. Often, the DNs and the attributes defined on the client side do not map to the DNs and the attributes defined on the server side. Data views can be defined to rename DNs and attributes. 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 DNs and attributes are changed back to match the client side.
For information about attribute renaming and DN renaming, see Attribute Renaming and DN Renaming in Sun Java System Directory Server Enterprise Edition 6.2 Reference. For information about how to rename attributes and DNs, see the following procedures:
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Set one or more attr-name-mappings properties on the data view for which you want to configure attribute mapping.
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ attr-name-mappings:client-side-attribute-name#server-side-attribute-name [attr-name-mappings:client-side-attribute-name#server-side-attribute-name ...] |
For example, rename surname on the client side to sn on the server side.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView \ attr-name-mappings:surname#sn |
To add an attribute mapping to an existing list of mappings, use this command:
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ attr-name-mappings+:client-side-attribute-name#server-side-attribute-name |
To remove an attribute mapping from an existing list of mappings, use this command:
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ attr-name-mappings-:client-side-attribute-name#server-side-attribute-name |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the base-dn property and the DN mapping properties of the data view for which you want to rename DNs.
$ dpconf get-ldap-data-view-prop -h host -p port view-name base-dn \ dn-mapping-source-base-dn dn-mapping-attrs |
The properties have the following meanings:
base-dn is the DN of the subtree on the client side, which is equivalent to the base DN of the data view.
dn-mapping-source-base-dn is the DN of the subtree on the server side.
dn-mapping-attrs defines a list of attributes that contain DNs of entries.
For example, the data view for the dc=example,dc=com database on the client side has the following values when DN renaming is not defined:
$ dpconf get-ldap-data-view-prop myDataView base-dn \ dn-mapping-source-base-dn dn-mapping-attrs base-dn : dc=example,dc=com dn-mapping-attrs : none dn-mapping-source-base-dn : none |
Map a DN on the client side to a DN on the server side.
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ dn-mapping-source-base-dn:server-side-dn |
For example, map the dc=example,dc=com database on the client side to dc=example,dc=org on the server side.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView \ dn-mapping-source-base-dn:dc=example,dc=org |
Rename attributes in the portion of the DIT that is affected by Step 2, if those attributes contain DNs.
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ dn-mapping-attrs:attribute-name [dn-mapping-attrs:attribute-name ...] |
For example, if the group attribute contains DNs in the namespace affected by the rename operation in Step 2, rename the attribute as follows:
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 myDataView dn-mapping-attrs:group |
To add a DN mapping to an existing list of mappings, use this command:
$ dpconf set-ldap-data-view-prop -h host -p port view-name dn-mapping-attrs+:attribute-name |
To remove a DN mapping from an existing list of mappings, use this command:
$ dpconf set-ldap-data-view-prop -h host -p port view-name dn-mapping-attrs-:attribute-name |
View the base-dn property and the DN mapping properties of the data view for which you have renamed DNs.
$ dpconf get-ldap-data-view-prop -h host -p port view-name base-dn \ dn-mapping-source-base-dn dn-mapping-attrs |
For example, the data view for the dc=example,dc=com database on the client side has the following values after DN renaming:
$ dpconf get-ldap-data-view-prop -h host1 -p 1389 myDataView base-dn \ dn-mapping-source-base-dn dn-mapping-attrs base-dn : dc=example,dc=com dn-mapping-attrs : group dn-mapping-source-base-dn : dc=example,dc=org |
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, not to the superior 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 excluded-subtrees and alternate-search-base-dn properties. The following procedure describes how to configure these properties manually.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure Directory Proxy Server to manually route requests.
$ dpconf set-server-prop -h host -p port data-view-automatic-routing-mode:manual |
When data-view-automatic-routing-mode is manual, Directory Proxy Server does not generate the excluded-subtrees and alternate-search-base-dn properties. You must set the values of these properties manually. The values that you set here are not checked by Directory Proxy Server. Be aware that setting these values incorrectly can break the administration path.
Alternatively, configure Directory Proxy Server to partially route requests manually.
$ dpconf set-server-prop -h host -p port data-view-automatic-routing-mode:limited |
When data-view-automatic-routing-mode is limited, Directory Proxy Server does not generate the excluded-subtrees and alternate-search-base-dn properties. However, Directory Proxy Server does check that the values set here do not conflict with the administration path.
Configure the view exclusion base.
$ dpconf set-ldap-data-view-prop -h host -p port view-name excluded-subtrees:suffix-DN |
The view exclusion base determines branches of the DIT whose entries are not exposed by the data view.
Configure the alternate search base.
$ dpconf set-ldap-data-view-prop -h host -p port view-name \ alternate-search-base-dn:search-base-DN |
The alternate search base determines other branches of the DIT in which entries belonging to this data view may be located. The base DN is defined by default as an alternate search base in all data views.
This section contains the following information about data views and how to create and configure them:
The examples in this section assume that the connection handler allows all client connections to be processed by Directory Proxy Server.
If you create a data view without configuring any of the properties, your data view has the following configuration:
alternate-search-base-dn : "" alternate-search-base-dn : base-DN attr-name-mappings : none base-dn : suffix-DN contains-shared-entries : - description : - distribution-algorithm : - dn-join-rule : - dn-mapping-attrs : none dn-mapping-source-base-dn : none excluded-subtrees : - filter-join-rule : - is-enabled : true is-read-only : false is-routable : true ldap-data-source-pool : pool-name lexicographic-attrs : all lexicographic-lower-bound : none lexicographic-upper-bound : none non-viewable-attr : - non-writable-attr : - numeric-attrs : all numeric-default-data-view : false numeric-lower-bound : none numeric-upper-bound : none pattern-matching-base-object-search-filter : all pattern-matching-dn-regular-expression : all pattern-matching-one-level-search-filter : all pattern-matching-subtree-search-filter : all process-bind : - replication-role : master viewable-attr : all except non-viewable-attr writable-attr : all except non-writable-attr |
This section shows the configuration of 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. For information about the root data view, see Data Views to Route All Requests, Irrespective of the Target DN of the Request in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The root data view has the following configuration:
alternate-search-base-dn : - attr-name-mappings : none base-dn : "" contains-shared-entries : - description : Automatically-generated data view able to route client operations independently of the operation base dn distribution-algorithm : - dn-join-rule : - dn-mapping-attrs : none dn-mapping-source-base-dn : none excluded-subtrees : "" excluded-subtrees : cn=config excluded-subtrees : cn=monitor excluded-subtrees : cn=proxy manager excluded-subtrees : cn=virtual access controls excluded-subtrees : dc=example,dc=com filter-join-rule : - is-enabled : true is-read-only : false is-routable : true ldap-data-source-pool : defaultDataSourcePool lexicographic-attrs : all lexicographic-lower-bound : none lexicographic-upper-bound : none non-viewable-attr : - non-writable-attr : - numeric-attrs : all numeric-default-data-view : false numeric-lower-bound : none numeric-upper-bound : none pattern-matching-base-object-search-filter : all pattern-matching-dn-regular-expression : all pattern-matching-one-level-search-filter : all pattern-matching-subtree-search-filter : all process-bind : - replication-role : master viewable-attr : all except non-viewable-attr writable-attr : all except non-writable-attr |
This section describes how to configure a data view that routes requests targeted at a list of subtrees to a set of data-equivalent data sources. For information about this type of deployment, see Data Views to Route Requests When a List of Subtrees Are Stored on Multiple, Data-Equivalent Data Sources in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The example in this section has multiple data sources that contain the same set of subtrees. The data sources are data-equivalent and are pooled into one data source pool for load balancing. A data view is configured for each subtree to expose that subtree to client requests. The following figure shows the sample deployment.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.
Create a data source pool as described in Creating and Configuring LDAP Data Source Pools.
Attach the data sources to the data source pool as described in Attaching LDAP Data Sources to a Data Source Pool.
(Optional) Configure load balancing.
For information, see Configuring Load Balancing.
Create a data view with a base DN at dc=example1,dc=com that refers to the data source pool.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-1 \ base-dn:dc=example1,dc=com ldap-data-source-pool:data-source-pool-1 |
Create another data view with a base DN at dc=example2,dc=com that refers to the data source pool.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-2 \ base-dn:dc=example2,dc=com ldap-data-source-pool:data-source-pool-1 |
The other properties of the data views are the same as the default data view in Default Data View.
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.
This section describes how to configure a data view that provides a single point of access to different subtrees stored in multiple data sources. For information about this type of deployment, see Data Views to Provide a Single Point of Access When Different Subtrees Are Stored on Different Data Sources in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The example in this section contains a data view for each subtree. A data source pool is configured for each set of data-equivalent data sources. The following figure shows the example deployment.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.
Create two data source pools as described in Creating and Configuring LDAP Data Source Pools.
Attach the data sources that contain dc=example1,dc=com to data-source-pool-1, and the data sources that contain dc=example2,dc=com to data-source-pool-2, as described in Attaching LDAP Data Sources to a Data Source Pool.
(Optional) Configure load balancing.
For information, see Configuring Load Balancing.
Create a data view with a base DN at dc=example1,dc=com that refers to data-source-pool-1.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-1 \ base-dn:dc=example1,dc=com ldap-data-source-pool:data-source-pool-1 |
Create another data view with a base DN at dc=example2,dc=com that refers to data-source-pool-2.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-2 \ base-dn:dc=example2,dc=com ldap-data-source-pool:data-source-pool-2 |
The other properties of the data views are the same as the default data view in Default Data View.
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.
This section describes how to configure a data view that provides a single point of access to different parts of a subtree. This example 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. The following figure shows the example deployment.
For information about this type of deployment, see Data Views to Route Requests When Different Parts of a Subtree Are Stored in Different Data Sources in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.
Create two data source pools as described in Creating and Configuring LDAP Data Source Pools.
Attach the data sources that contain one part of the subtree to data-source-pool-1, and the data sources that contain the other part of the subtree to data-source-pool-2, as described in Attaching LDAP Data Sources to a Data Source Pool.
(Optional) Configure load balancing.
For information, see Configuring Load Balancing.
Create a data view with a distribution algorithm to select entries in ou=people,dc=example,dc=com with uid between 0 and 99, and configure the data view to direct requests to data-source-pool-1.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-1 \ ldap-data-source-pool:data-source-pool-1 base-dn:ou=people,dc=example,dc=com \ distribution-algorithm :numeric numeric-attrs:uid numeric-lower-bound :0 \ numeric-upper-bound :99 |
Create another data view with a distribution algorithm to select entries in ou=people,dc=example,dc=com with uid between 100 and 199, and configure the data view to direct requests to data-source-pool-2.
$ dpconf set-ldap-data-view-prop -h host1 -p 1389 dataview-2 \ ldap-data-source-pool:data-source-pool-2 base-dn:ou=people,dc=example,dc=com \ distribution-algorithm:numeric numeric-attrs:uid numeric-lower-bound:100 numeric-upper-bound :199 |
The other properties of the data views are the same as the default data view in Default Data View.
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.
This section describes how to configure a data view for a single point of access when a superior branch of a subtree is stored in a different data source to a subordinate branch. For information about this type of deployment, see Data Views to Route Requests When Superior and Subordinate Subtrees Are Stored in Different Data Sources in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The example in this section contains three data views. The base DN of data view 1 is superior to the base DN of data view 2 and the base DN of data view 3. Or, in other words, data source 2 and data source 3 contain subtrees that are subordinate to the subtree on data source 1. The following figure shows the example deployment.
Directory Proxy Server automatically excludes a subordinate branch of a subtree from a data view when the subordinate branch is configured as the base DN of a separate data view.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.
Create three data source pools as described in Creating and Configuring LDAP Data Source Pools.
Attach the data sources to the data source pools by following the instructions in Attaching LDAP Data Sources to a Data Source Pool.
Attach the data sources that contain dc=example,dc=com to data-source-pool-1.
Attach the data sources that contain ou=computer,dc=example,dc=com to data-source-pool-2.
Attach the data sources that contain ou=people,dc=example,dc=com to data-source-pool-3.
(Optional) Configure load balancing.
For information, see Configuring Load Balancing.
Create a data view with a base DN at dc=example,dc=com and a data source pool data-source-pool-1.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-1 \ data-source-pool-1 dc=example,dc=com |
Create a data view with a base DN at ou=computer,dc=example,dc=com and a data source pool data-source-pool-2.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-2 \ data-source-pool-2 ou=computer,dc=example,dc=com |
Create a data view with a base DN at ou=people,dc=example,dc=com and a data source pool data-source-pool-3.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-3 \ data-source-pool-3 ou=people,dc=example,dc=com |
Verify that the subtrees ou=computer,dc=example, dc=com and ou=people,dc=example, dc=com have been excluded from dataview-1 by looking at the excluded-subtrees parameter.
$ dpconf get-ldap-data-view-prop -h host1 -p 1389 dataview-1 excluded-subtrees |
The list of excluded subtrees is returned.
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.
This section describes how to configure a data view to combine hierarchy with distribution algorithms. For information about this type of deployment, see Data Views With Hierarchy and a Distribution Algorithm in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The example in this section 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 the entries into different data views.
Directory Proxy Server automatically excludes a subordinate branch of a subtree from a data view when the subordinate branch is configured as the base DN of a separate data view. A numeric distribution algorithm separates entries from the same subtree into different data views. A data source pool is configured for each set of data-equivalent data sources.
The following figure shows the example deployment.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create a data source for each LDAP server as described in Creating and Configuring LDAP Data Sources.
Create four data source pools as described in Creating and Configuring LDAP Data Source Pools.
Attach the data sources to the data source pools by following the instructions in Attaching LDAP Data Sources to a Data Source Pool.
Attach the data sources that contain dc=example,dc=com to data-source-pool-1.
Attach the data sources that contain ou=computer,dc=example,dc=com to data-source-pool-2.
Attach the data sources that contain entries in ou=people,dc=example,dc=com with uid between 0 and 99 to data-source-pool-3.
Attach the data sources that contain entries in ou=people,dc=example,dc=com with uid between 100 and 199 to data-source-pool-4.
(Optional) Configure load balancing.
For information, see Configuring Load Balancing.
Create a data view with a base DN at dc=example,dc=com, that refers to data-source-pool-1.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-1 \ data-source-pool-1 dc=example,dc=com |
Create a data view with a base DN at ou=computer,dc=example,dc=com that refers to data-source-pool-2.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-2 \ data-source-pool-2 ou=computer,dc=example,dc=com |
Create a data view with a base DN at ou=people,dc=example,dc=com that refers to data-source-pool-3. Configure a distribution algorithm on the data view to select entries with uid between 0 and 99.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-3 \ data-source-pool-3 ou=people,dc=example,dc=com $ dpconf set-ldap-data-view-prop dataview-3 distribution-algorithm:numeric \ numeric-attrs:uid numeric-lower-bound:0 numeric-upper-bound:99 |
Create a data view with a base DN at ou=people,dc=example,dc=com that refers to data-source-pool-4, and configure a distribution algorithm on the data view to select entries with uid between 100 and 199.
$ dpconf create-ldap-data-view -h host1 -p 1389 dataview-4 \ data-source-pool-4 ou=people,dc=example,dc=com $ dpconf set-ldap-data-view-prop dataview-4 distribution-algorithm:numeric \ numeric-attrs:uid numeric-lower-bound:100 numeric-upper-bound:199 |
Verify that the subtrees ou=computer,dc=example, dc=com and ou=people,dc=example, dc=com have been excluded from dataview-1 by looking at the excluded-subtrees parameter.
$ dpconf get-ldap-data-view-prop -h host1 -p 1389 dataview-1 excluded-subtrees |
The list of excluded subtrees is returned.
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.
This chapter describes how to create virtual data views. Virtual data views transform the source data and present a different view of that data to client applications. Virtual data views include transformed LDAP data views, LDIF data views, join data views, and JDBCTM data views. For an overview of the features of virtual data views and a description of example use cases, see Chapter 18, Directory Proxy Server Virtualization, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You cannot use Directory Service Control Center (DSCC) to perform the procedures in this chapter. You must use the command line.
This chapter covers the following topics:
An LDIF data view is a simple virtual data view in which an LDIF file is made to look like an LDAP data source. Unlike for LDAP data views, you do not create data sources or data source pools when you set up LDIF data views. Instead, you specify an LDIF file when you create the data view. By default, you cannot write to an LDIF data view. For more information, see Defining Access Control on Virtual Data Views.
For information about creating and configuring LDIF data views, see the following procedures.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create an LDIF data view.
$ dpconf create-ldif-data-view -h host -p port view-name path-to-ldif-file suffix-dn |
(Optional) View the list of LDIF data views.
$ dpconf list-ldif-data-views -h host -p port |
The virtual access controls data view is the only default LDIF data view. This data view is generated by the server and enables requests to be routed to virtual access control instructions (ACIs).
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
View the properties of an LDIF data view.
$ dpconf get-ldif-data-view-prop -h host -p port view-name |
An LDIF data view has the following default properties:
alternate-search-base-dn : "" alternate-search-base-dn : dc=com attr-name-mappings : none base-dn : suffixDN bind-pwd-attr : userPassword contains-shared-entries : - db-pwd-encryption : clear-text description : - distribution-algorithm : - dn-join-rule : - dn-mapping-attrs : none dn-mapping-source-base-dn : none excluded-subtrees : - filter-join-rule : - is-enabled : true is-read-only : false is-routable : true ldif-data-source : /path/to/filename.ldif lexicographic-attrs : all lexicographic-lower-bound : none lexicographic-upper-bound : none non-viewable-attr : - non-writable-attr : - numeric-attrs : all numeric-default-data-view : false numeric-lower-bound : none numeric-upper-bound : none pattern-matching-base-object-search-filter : all pattern-matching-dn-regular-expression : all pattern-matching-one-level-search-filter : all pattern-matching-subtree-search-filter : all process-bind : - replication-role : master viewable-attr : all except non-viewable-attr writable-attr : all except non-writable-attr |
Change one or more of the properties that are listed in Step 1.
$ dpconf set-ldif-data-view-prop -h host -p port view-name property:value \ [property:value ... ] |
For example, to change the source LDIF file for the data view, set the ldif-data-source property.
$ dpconf set-ldif-data-view-prop -h host1 -p 1389 -D cn="Proxy Manager" \ myLDIFDataView ldif-data-source:/local/files/example.ldif |
Virtual data transformations are defined on existing data views, and create a virtual data view from a physical data view. For information about how they work, see Virtual Data Transformations in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You can add a virtual data transformation to any type of data view: an LDAP data view, an LDIF data view, a join data view, or a JDBC data view.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Add the transformation to a data view.
$ dpconf add-virtual-transformation -h host -p port view-name \ transformation-model transformation-action attribute-name [parameters...] |
Note that parameters might be mandatory, depending on the transformation-model and the transformation-action. For information about transformation models, transformation actions, and transformation parameters, see Virtual Data Transformations in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
(Optional) View the list of virtual transformations that are defined on a data view.
$ dpconf list-virtual-transformations -h host -p port view-name
A join data view is an aggregation of multiple data views. For information about how a join data view works, see Join Data Views in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
For information about how to create and configure join data views, see the following procedures.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Identify the primary and secondary data views that will be aggregated to form the join view.
The primary and secondary data views must exist before the join view can be created. The primary and secondary views can be any type of data view, including an LDAP data view, LDIF data view, JDBC data view, or another join data view. Specific properties must be configured on the secondary view to allow it to function as the source for a join view. For more information, see To Configure the Secondary View of a Join View.
Create the join data view.
$ dpconf create-join-data-view -h host -p port view-name primary-view secondary-view \ suffix-dn |
(Optional) View the list of join views to check that your data view has been created successfully.
$ dpconf list-join-data-views -h host -p port |
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
View the properties of a join data view.
$ dpconf get-join-data-view-prop -h host -p port view-name |
The default properties of a join data view are as follows:
alternate-search-base-dn : "" alternate-search-base-dn : dc=com attr-name-mappings : none base-dn : suffixDN contains-shared-entries : - description : - distribution-algorithm : - dn-join-rule : - dn-mapping-attrs : none dn-mapping-source-base-dn : none excluded-subtrees : - filter-join-rule : - is-enabled : true is-read-only : false is-routable : true join-rule-control-enabled : false lexicographic-attrs : all lexicographic-lower-bound : none lexicographic-upper-bound : none non-viewable-attr : - non-writable-attr : - numeric-attrs : all numeric-default-data-view : false numeric-lower-bound : none numeric-upper-bound : none pattern-matching-base-object-search-filter : all pattern-matching-dn-regular-expression : all pattern-matching-one-level-search-filter : all pattern-matching-subtree-search-filter : all primary-view : primary-view process-bind : - replication-role : master secondary-view : secondary-view viewable-attr : all except non-viewable-attr writable-attr : all except non-writable-attr |
Change one or more of the properties that are listed in Step 1.
$ dpconf set-join-data-view-prop -h host -p port view-name property:value \ [property:value ... ] |
For example, to change the primary data view of a data source to myLDAPDataView, use the following command:
$ dpconf set-join-data-view-prop -h host1 -p 1389 -D cn="Proxy Manager" \ myJoinDataView primary-view:myLDAPDataView |
When a join data view is configured, set viewable-attr and writable-attr properties on primary data view and secondary data view.
Setting of these properties helps in splitting the search filters appropriately on primary and secondary data views. Otherwise, there might be discrepancies in search results when search filter contains attributes from secondary data view.
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.
Setting join rule configuration information in the join data view makes the data view to be referenced by multiple join data views. To do so, perform the following:
Set join-rule-control-enabled to true on the join data view.
$ dpconf set-join-data-view-prop view-name join-rule-control-enabled:true |
After setting join-rule-control-enabled to true, join rule configuration information stored in the join data view is used by the server. If you have a join data view with the join rule configuration information stored in the secondary data view then this information is not used by the server. To have this information used by the server, you will have to manually add the configuration information at the join data view level.
Define a join rule that determines how the secondary view is related to the primary view.
The join rule can be one of the following:
DN join rule
$ dpconf set-join-data-view-prop view-name \ dn-join-rule:uid=\${primary-view-name.uid},ou=People,dc=example |
Filter join rule
$ dpconf set-join-data-view-prop view-name \ filter-join-rule:uid=\${primary-view-name.uid} |
Specific properties must be configured on the secondary data view to allow it to function as the source for a join view. Because the secondary view can be any type of data view, the command you use will depend on the data view type. The following sample commands assume that the secondary view is an LDAP data view. For more information about the properties described here, see Additional Secondary Data View Properties in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Define a join rule that determines how the secondary view is related to the primary view.
The join rule can be one of the following:
DN join rule
$ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \ dn-join-rule:uid=\${primary-view-name.uid},ou=People,dc=example |
Filter join rule
$ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \ filter-join-rule:uid=\${primary-view-name.uid} |
The configuration for the dn-join-rule and filter-join-rule properties is used by the server only if the join-rule-control-enabled property on the join data view is set to false. Otherwise, if the join-rule-control-enabled property is set to true on the join data view, then the information set on the secondary view will be ignored.
If the filter join rule is set on the join data view, you need to set a virtual transformation rule on the secondary data view to be able to add an entry on the join data view.
dpconf add-virtual-transformation secondary-view-name \ write add-attr-value dn uid=\${uid} |
Without setting this rule, addition of entries to join data view would not be possible.
(Optional) Specify whether binds are allowed on the secondary view.
By default, binds are permitted on all data views. If you want to prohibit binds to the secondary data view, run the following command:
$ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name process-bind:false |
For more information about this property, see Handling of Binds in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
(Optional) Specify whether the secondary view contains shared entries.
$ dpconf set-ldap-data-view-prop -h host -p port secondary-view-name \ contains-shared-entries:true |
For more information about this property, see Handling of Shared Entries in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
A JDBC data view enables you to make a relational database accessible to LDAP client applications. For information about how JDBC data views work, see JDBC Data Views in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
For information about how to create and configure JDBC data views, see the following procedures.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create a JDBC data source for the relational database.
$ dpconf create-jdbc-data-source -h host -p port -b db-name -B db-url -J driver-url \ [-J driver-url]... -S driver-class 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. To access multiple JDBC data sources, you can create a data view for each data source, and join them together with a join data view.
The following properties must be set when you create a JDBC data source:
The name of the relational database, for example, payrolldb.
The URL to the database, in the form jdbc:vendor:driver://dbhost:dbport.
The db-url is not a complete JDBC database URL, because it does not contain the database name. (The database name is specified by the db-name property.)
You must finish db-url with a / for MySQL, DB2, and Derby databases and with a : for Oracle database.
The JDBC driver class, for example org.hsqldb.jdbcDriver.
The path to the JDBC driver, for example file:///path/to/hsqldb/lib/hsqldb.jar.
The driver-url property is multi-valued. Hence, driver-url can support multiple JAR files for the JDBC driver to ensure connectivity to the JDBC source on different platforms.
Create a JDBC data source pool.
$ dpconf create-jdbc-data-source-pool -h host -p port pool-name |
Attach the JDBC data source to the JDBC data source pool.
$ dpconf attach-jdbc-data-source -h host -p port pool-name source-name |
Create a JDBC data view.
$ dpconf create-jdbc-data-view -h host -p port view-name pool-name suffix-DN |
(Optional) View the list of JDBC data views to check that your data view has been created successfully.
$ dpconf list-jdbc-data-views -h host -p port |
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
View the properties of a JDBC data view.
$ dpconf get-jdbc-data-view-prop -h host -p port view-name |
The default properties of a JDBC data view are as follows:
alternate-search-base-dn : - attr-name-mappings : none base-dn : o=sql1 contains-shared-entries : - description : - distribution-algorithm : - dn-join-rule : - dn-mapping-attrs : none dn-mapping-source-base-dn : none excluded-subtrees : - filter-join-rule : - is-enabled : true is-read-only : false is-routable : true jdbc-data-source-pool : pool-name lexicographic-attrs : all lexicographic-lower-bound : none lexicographic-upper-bound : none non-viewable-attr : - non-writable-attr : - numeric-attrs : all numeric-default-data-view : false numeric-lower-bound : none numeric-upper-bound : none pattern-matching-base-object-search-filter : all pattern-matching-dn-regular-expression : all pattern-matching-one-level-search-filter : all pattern-matching-subtree-search-filter : all process-bind : - replication-role : master viewable-attr : all except non-viewable-attr writable-attr : all except non-writable-attr |
Change one or more of the properties that are listed in Step 1.
$ dpconf set-jdbc-data-view-prop -h host -p port view-name property:value \ [property:value ... ] |
When you configure a JDBC data view, you must also configure the following objects:
JDBC object class. Maps one or more JDBC tables to an LDAP object class.
JDBC table. Defined for each relational database table.
JDBC attribute. Defines an LDAP attribute from a specified column in a JDBC table.
Create a JDBC table for each table in the relational database.
% dpconf create-jdbc-table jdbc-table-name db-table |
The name of the db-table is case sensitive. Make sure that you use the identical case that is used in the relational database, otherwise operations that target that table might fail.
Create a JDBC attribute for each column in each relational database table.
% dpconf add-jdbc-attr table-name attr-name sql-column |
Creating a JDBC attribute maps the table column to an LDAP attribute.
(Optional) If the column in the relational database is case sensitive, change the LDAP syntax of the JDBC attribute.
% dpconf set-jdbc-attr-prop table-name attr-name ldap-syntax:ces |
The value of ldap-syntax is cis by default. This implies that the jdbc-attr is case insensitive. Change the value to ces if your relational database is case sensitive.
Certain relational databases, such as Oracle and DB2, are case sensitive by default. LDAP is case insensitive by default. When Directory Proxy Server detects that a column of the relational database table is case sensitive, an ldapsearch query with the corresponding attribute in the filter is translated into a SQL query using the function UPPER.
For example, the query ldapsearch -b "dc=mysuffix" "(attr=abc)" is translated into the following SQL query:
SELECT * FROM mytable WHERE (UPPER(attr)='ABC') |
By default, this type of query is not indexed. Queries of this nature can therefore have a substantial performance impact.
You can alleviate the performance impact in two ways:
By setting the ldap-syntax property of the jdbc-attr to ces.
By creating an index with the function UPPER for each jdbc-attr that might be used in an LDAP filter.
If your relational database is not case sensitive, use ldap-syntax with the default value, that is, cis. ldap-syntax:ces is not supported with the case insensitive databases.
Create a JDBC object class for the LDAP relational database table.
% dpconf create-jdbc-object-class view-name objectclass primary-table \ [secondary-table... ] DN-pattern |
Creating a JDBC object class essentially specifies an LDAP object class with which these tables will be associated. The JDBC object class also specifies the primary table and the secondary tables, if they exist.
When you create a JDBC object class, you specify a DN pattern. The DN pattern shows how the DN of the entry will be constructed.
All the subtree components defined in the DN pattern of JDBC object class should have a JDBC object class defined for them. For example, if there is a DN pattern uid,ou in a JDBC object class, there should be a JDBC object class definition with a DN pattern ou. This is necessary for Directory Proxy Server to construct a properly structured DIT. Otherwise, the subtree with values like ou=xxx,base-DN would not be returned in the search results.
If a secondary table exists, define the join rule between the primary table and the secondary table.
% dpconf set-jdbc-table-prop secondary-table-name filter-join-rule:join-rule |
A join rule is defined on the secondary table and determines how data from that table is linked to data from the primary table. How you define the relationships between the primary and secondary tables of an object class is important. For more information, see Defining Relationships Between JDBC Tables.
Specify the super class for the JDBC object class.
% dpconf set-jdbc-object-class-prop view-name objectclass super-class:value |
The super class indicates the LDAP object class from which the JDBC object class inherits.
In the simplest case, a JDBC object class contains only a single (primary) table. There is no secondary table, and thus no need to define relationships between tables.
If the object class contains more than one table, the relationships between these tables must be clearly defined. The relationships between tables are always defined on the secondary table. The following properties of a secondary table enable you to define these relationships:
is-single-row-table specifies that an LDAP entry has only one matching row in the table.
contains-shared-entries specifies that a row in the secondary table is used by more than one row in the primary table.
filter-join-rule indicates how an entry should be retrieved from the secondary table based on something in the primary table.
The following examples illustrate how the filter join rule is defined, based on the values of the first two properties. These examples assume that the object class has one primary table and one secondary table.
These are the default values of these properties. In this case, the relationship between the primary and secondary tables is n->1, that is, n rows in the primary table reference one shared row in the secondary table.
In the relational database, a foreign key (FK) is defined in the primary table, and points to a column in the secondary table.
Take, for example, an organization in which several employees can share the same manager. Two relational database tables are defined, with the following structure:
primary table : EMPLOYEE [ID, NAME, FK_MANAGER_ID] secondary table : MANAGER [ID, NAME] |
The following object class and attributes are defined:
object-class : employee attr : name (from primary EMPLOYEE.NAME) attr : manager (from secondary MANAGER.NAME) |
The following filter join rule is defined in the secondary table:
"${ID}=${EMPLOYEE.FK_MANAGER_ID}" |
With this configuration, the following behavior occurs for LDAP operations:
Adding an employee entry. If the manager in the employee entry does not exist in the table, a new row is created. If the manager does exist, an existing row is used.
Replacing the value of the “manager” attribute in an entry. The value of the row MANAGER.NAME is changed.
Deleting an employee entry. The row in the secondary table is not deleted because the manager entries are shared.
Deleting the “manager” attribute from an entry. The row in the secondary table is deleted and the foreign key (EMPLOYEE.FK_MANAGER_ID) is set to NULL.
In this case, the relationship between the primary and secondary tables is 1->1 or 1<-1, that is, one row in the primary table is referenced by one row in the secondary table.
In the relational database, the foreign key (FK) might be defined in the primary table, or in the secondary table.
Take, for example, an organization in which the UID of employees is stored in one table, and the surname of employees is stored in a second table. Two relational database tables are defined, with the following structure:
primary table : UID [ID, VALUE, FK_SN_ID] secondary table : SN [ID, VALUE] |
The following object class and attributes are defined:
object-class : employee attr : uid (from primary UID.VALUE) attr : sn (from secondary ID.VALUE) |
The following filter join rule is defined in the secondary table:
"${ID}=${UID.FK_SN_ID}" |
This configuration could be the other way around, with the foreign key FK_UID_ID stored in the secondary table, and pointing to UID.ID.
In this case, the relationship between the primary and secondary tables is 1->n, that is, one row in the primary table is referenced by n rows in the secondary table. This example illustrates the case of multi-valued attributes. A multi-valued attribute is represented as a set of rows in the secondary table, with one row per attribute value.
In the relational database, the foreign key is defined in the secondary table, and points to a column in the primary table.
Take, for example, an organization in which an employee can have several telephone numbers. Two relational database tables are defined, with the following structure:
primary table : EMPLOYEE [ID, NAME] secondary table : PHONE [ID, VALUE, USER_ID] |
The following object class and attributes are defined:
object-class : employee attr : cn (from primary EMPLOYEE.NAME) attr : telephoneNumber (from secondary PHONE.VALUE) |
The following filter join rule is defined in the secondary table:
"${USER_ID}=${EMPLOYEE.ID}" |
This case is currently unsupported in Directory Proxy Server.
ACIs on virtual data views can be stored in an LDAP directory or in an LDIF file. For information about how virtual ACIs work, see Access Control On Virtual Data Views in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
When you create a Directory Proxy Server instance, the following default configuration for virtual access controls is defined:
An LDIF file in which ACIs are stored by default (instance-path/config/access_controls.ldif)
An LDIF data view named virtual access controls
This data view enables Directory Proxy Server to access the ACIs stored in the LDIF file.
If you do not want to use the default ACI configuration described previously, you can define a different storage repository.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create a data view for the repository in which the virtual ACIs will be stored.
If the ACIs will be stored in an LDAP directory, create an LDAP data source and an LDAP data view, as described in Creating and Configuring LDAP Data Views.
If the ACIs will be stored in an LDIF file, create an LDIF data view, as described in Creating and Configuring LDIF Data Views.
Specify the name of the data view created in the previous step as the ACI data view.
$ dpconf set-virtual-aci-prop -h host -p port aci-data-view:data-view-name
If the ACI repository is an LDAP directory, define the credentials required to access the ACI data view.
$ dpconf set-virtual-aci-prop -h host -p port aci-manager-bind-dn:bind-dn $ dpconf set-virtual-aci-prop -h host -p port aci-manager-bind-pwd-file:filename
Regardless of the ACI repository that you use, you must configure the virtual access controls.
Only the Proxy Manager can create a pool of ACIs and manage ACIs directly through the ACI data view. If the ACI repository is an LDAP directory, you must modify the schema of that directory to include the aciSource object class and the dpsaci attribute. For more information about customizing the schema, see Extending Directory Server Schema.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Create a pool of ACIs in the ACI repository, and set up global ACIs.
For information about global ACIs, see Global ACIs in Sun Java System Directory Server Enterprise Edition 6.2 Reference. To set up global ACIs, add an aciSource entry under the view base of the ACI data view. For example:
% ldapmodify -p port -D "cn=proxy manager" -w - dn: cn=data-source-name,cn=virtual access controls changetype: add objectclass: aciSource dpsaci: (targetattr="*") (target = "ldap:///ou=people,o=virtual") (version 3.0; \ acl "perm1"; allow(all) groupdn="ldap:///cn=virtualGroup1,o=groups,o=virtual";) cn: data-source-name |
Configure one or more connection handlers to use this pool of ACIs.
% dpconf set-connection-handler-prop -h host -p port connection-handler \ aci-source:data-source-name |
Add the required ACIs to the data.
To do this, create a virtual entry that contains the ACIs. For example:
% ldapmodify -p port -D "cn=virtual application,ou=application users,dc=com" -w - dn: ou=people,o=virtual changetype: modify add: dpsaci dpsaci: (targetattr="*")(version 3.0; acl "perm1"; allow(all) userdn ="ldap:///self";) dpsaci: (targetattr="*")(version 3.0; acl "perm1"; allow(search, read, compare) \ userdn ="ldap:///anyone";) |
Any user with the appropriate access rights can add and retrieve virtual ACIs through the data view.
Generally, for LDAP data views, schema checking is performed by the backend directory, using the backend directory's schema. Use the following procedure if you want schema checking to be performed by Directory Proxy Server.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
To normalize requests, particularly the DN, set the use-external-schema property of the server, as follows:
Indicate that the server instance should use an external schema.
$ dpconf set-server-prop -h host -p port use-external-schema:true |
Enable schema checking on the connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler \ schema-check-enabled:true |
Create a data view that exposes cn=schema.
If the external schema is defined in an LDAP directory, create an LDAP data view, as described in Creating and Configuring LDAP Data Views, with a view base of cn=schema.
If the external schema is defined in an LDIF file, create an LDIF data view, as described in Creating and Configuring LDIF Data Views with a view base of cn=schema.
Add this data view to the list of data views exposed by the connection handler.
By default, all data views are exposed by the connection handler. If you have a defined a custom list of data views that are exposed by the connection handler, add this data view to the list.
$ dpconf set-connection-handler-prop -h host -p port connection-handler \ data-view-routing-custom-list+:data-view-name |
The following section provides two sample configurations. These configurations illustrate the main features of a virtual directory, and indicate how these features are configured.
The procedures in this section describe a sample virtual configuration that joins an LDAP directory and a MySQL database. The LDAP directory is the primary data source, that contains most of the user information. The mySQL database contains additional information about the users. The resulting configuration is illustrated in the following figure.
You can use the sample data provided in install-path/ds6/ldif/Example.ldif to duplicate this example, or you can substitute the sample data with your own data.
This configuration can be broken into three sections:
Configuring and testing the LDAP data view
Configuring and testing the JDBC data view
Configuring and testing the join data view
For simplicity, all the commands in this section assume that the Directory Proxy Server is running on the local host in /local/dps. The commands also assume that the following environment variables have been set:
1389
pwd.txt, a file containing the administrator password.
4389
cn=Directory Manager
The tasks in this section assume the following information:
A Directory Server instance is running on host1, on port 4389.
Data in the Directory Server is stored under the suffix dc=example,dc=com. To duplicate this example, create a Directory Server instance, create the suffix dc=example,dc=com, and import the sample data in install-path/ds6/ldif/Example.ldif.
Create an LDAP data source named myds1 for the Directory Server instance.
% dpconf create-ldap-data-source myds1 host1:4389 |
Enable the data source, and allow write operations to the data source.
% dpconf set-ldap-data-source-prop myds1 is-enabled:true is-read-only:false |
Create an LDAP data source pool named myds1-pool.
% dpconf create-ldap-data-source-pool myds1-pool |
Attach the LDAP data source to the LDAP data source pool.
% dpconf attach-ldap-data-source myds1-pool myds1 |
Specify that the data source should receive 100% of the bind, add, search, and modify operations from that data source pool.
% dpconf set-attached-ldap-data-source-prop myds1-pool myds1 add-weight:100 \ bind-weight:100 modify-weight:100 search-weight:100 |
Create an LDAP data view for the data source pool, named myds1–view, with a base DN of dc=example,dc=com.
% dpconf create-ldap-data-view myds1-view myds1-pool dc=example,dc=com |
As a user under dc=example,dc=com, search all entries in the LDAP data source to verify that you can read from the data view.
% ldapsearch -p 1389 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery \ -b dc=example,dc=com "objectclass=*" |
You must use the credentials of a user under dc=example,dc=com. If you want to use cn=Directory Manager, you must define a data view to handle that DN.
As a user under dc=example,dc=com, modify the userPassword attribute to verify that you can write to the data view.
% ldapmodify -p 1389 -D "uid=kvaughan,ou=people,dc=example,dc=com" -w bribery dn: uid=kvaughan,ou=people,dc=example,dc=com changetype: modify replace: userPassword userPassword: myNewPassword |
A default ACI in Directory Server allows users to modify their own passwords.
The following tasks assume that a mySQL database is installed, running and populated with data, and that the mySQL database has the following characteristics:
Database name : sample_sql
Database URL : host2.example.com:3306/
JDBC driver URL : file:/net/host2.example/local/mysql/lib/jdbc.jar
Driver class : com.mysql.jdbc.Driver
Database user : root
Database password file : mysqlpwd.txt
The following table describes the tables in the database, and their composite fields. You need this information to set up the JDBC data view.
mySQL Table |
Fields |
---|---|
EMPLOYEE |
ID, SURNAME,PASSWORD, TITLE, COUNTRY_ID |
COUNTRY |
ID, NAME |
PHONE |
USER_ID, NUMBER |
Create a JDBC data source named mysql1 for the SQL database.
% dpconf create-jdbc-data-source -b sample_sql -B jdbc:mysql://host2.example.com:3306 \ -J file:/net/host2.example/local/mysql/lib/jdbc.jar -S com.mysql.jdbc.Driver mysql1 |
Specify the user name and password file for the SQL database.
% dpconf set-jdbc-data-source-prop mysql1 db-pwd-file:sqlpwd.txt db-user:root |
Restart the proxy server.
% dpadm restart /local/dps |
Enable the data source, and allow write operations to the data source.
% dpconf set-jdbc-data-source-prop mysql1 is-enabled:true is-read-only:false |
Create a JDBC data source pool named mysql1–pool.
% dpconf create-jdbc-data-source-pool mysql1-pool |
Attach the JDBC data source to the data source pool.
% dpconf attach-jdbc-data-source mysql1-pool mysql1 |
Create a JDBC data view for the data source pool, named myjdbc1–view, with a base DN of o=sql.
% dpconf create-jdbc-data-view mysql1-view mysql1-pool o=sql |
Create a JDBC table for each table in the MySQL database.
% dpconf create-jdbc-table employee1 EMPLOYEE % dpconf create-jdbc-table country1 COUNTRY % dpconf create-jdbc-table phone1 PHONE |
The name of the table in the SQL database is case sensitive. Make sure that you use the same case that is used in the SQL database.
Create a JDBC attribute for each column in each table.
Creating a JDBC attribute maps the MySQL column to an LDAP attribute.
% dpconf add-jdbc-attr employee1 uid ID % dpconf add-jdbc-attr employee1 sn SURNAME % dpconf add-jdbc-attr employee1 userPassword PASSWORD % dpconf add-jdbc-attr employee1 room ROOM % dpconf add-jdbc-attr phone1 tel NUMBER % dpconf add-jdbc-attr country1 country NAME |
It is not necessary to create JDBC attributes for the phone1 user_id and country1 id columns, because these columns are used only in the context of the MySQL database. They will not have a corresponding LDAP attribute.
Create a JDBC object class for the LDAP person object class.
In this step, the employee1 table is identified as the primary table, and the country1 and phone1 tables are identified as secondary tables. The creation of a JDBC object class also requires a DN. In this example, the DN is constructed from the uid attribute and the base DN of the data view.
% dpconf create-jdbc-object-class mysql1-view person employee1 country1 phone1 uid |
Define the join rules between the primary table and the secondary tables.
A join rule is defined on the secondary table and determines how data from that table is linked to data from the primary table.
% dpconf set-jdbc-table-prop country1 filter-join-rule:'ID=${EMPLOYEE.COUNTRY_ID}' % dpconf set-jdbc-table-prop phone1 filter-join-rule:'USER_ID=${EMPLOYEE.ID}' |
Specify the super class for the JDBC object class.
The super class indicates the LDAP object class from which the JDBC object class inherits attributes.
% dpconf set-jdbc-object-class-prop mysql1-view person super-class:top |
Before you can test the JDBC data view, you must enable write access to the data view by configuring ACIs. By default, write access to non-LDAP data views is denied. For the purposes of this example, it is sufficient to add one global ACI that allows users to modify their own passwords.
As the Proxy Manager, add a pool of ACIs to the JDBC data source and add a global ACI that allows users to modify their own entries.
% ldapmodify -p 1389 -D "cn=proxy manager" -w password dn: cn=mysql1,cn=virtual access controls changetype: add objectclass: acisource dpsaci: (targetattr="*") (target = "ldap:///o=sql") \ (version 3.0; acl "enable all access for all users "; allow(all) \ userdn="ldap:///uid=kvaughan,o=sql";) cn: mysql1 |
Create a connection handler to handle connections to the o=sql domain.
% dpconf create-connection-handler mysql1-handler |
Enable the connection handler and configure it to handle all binds from users in the o=sql domain.
% dpconf set-connection-handler-prop mysql1-handler is-enabled:true \ bind-dn-filters:"uid=.*,o=sql" |
Configure the connection handler to use the pool of ACIs added previously.
% dpconf set-connection-handler-prop mysql1-handler aci-source:mysql1 |
As a user under o=sql, search the JDBC data source to verify that you can read from the data view.
% ldapsearch -p 1389 -D "uid=kvaughan,o=sql" -w mypwd -b o=sql "objectclass=*" |
You must use the credentials of a user under o=sql, or an anonymous bind.
As a user under o=sql, modify the userPassword attribute to verify that you can write to the data view.
% ldapmodify -p 1389 -D "uid=kvaughan,o=sql" -w mypwd dn: uid=kvaughan,o=sql changetype: modify replace: userPassword userPassword: myNewpwd |
Create a join data view named myjoin1–view.
Specifying the LDAP data view as the primary data view, and the JDBC data view as the secondary data view.
% dpconf create-join-data-view myjoin1-view myds1-view mysql1-view o=join |
Define a join rule on the secondary data view.
The following join rule specifies that the uid attribute of entries from the secondary data view should match the uid attribute of entries from the primary data view.
% dpconf set-jdbc-data-view-prop mysql1-view filter-join-rule:uid='${myds1-view.uid}' |
If the filter join rule is set on the join data view, you need to set a virtual transformation rule on the secondary data view to be able to add an entry on the join data view.
dpconf add-virtual-transformation secondary-view-name \ write add-attr-value dn uid=\${uid} |
Without setting this rule, addition of entries to join data view would not be possible.
Define the set of attributes that can be read from and written to the primary data view through a join data view.
% dpconf set-ldap-data-view-prop myds1-view viewable-attr:dn viewable-attr:cn \ viewable-attr:sn viewable-attr:givenName viewable-attr:objectClass viewable-attr:ou \ viewable-attr:l viewable-attr:uid viewable-attr:mail viewable-attr:telephoneNumber \ viewable-attr:facsimileTelephoneNumber viewable-attr:roomNumber viewable-attr:userPassword % dpconf set-ldap-data-view-prop myds1-view writable-attr:dn writable-attr:cn \ writable-attr:sn writable-attr:givenName writable-attr:objectClass writable-attr:ou \ writable-attr:l writable-attr:uid writable-attr:mail writable-attr:telephoneNumber \ writable-attr:facsimileTelephoneNumber writable-attr:roomNumber writable-attr:userPassword |
These definitions apply only in the context of the join view. By default all attributes can be read and written if you access the LDAP data view directly.
Define the set of attributes that can be read from and written to the secondary data view through a join data view.
% dpconf set-jdbc-data-view-prop mysql1-view viewable-attr:dn viewable-attr:objectclass \ viewable-attr:sn viewable-attr:room viewable-attr:userpassword viewable-attr:jobtitle \ viewable-attr:country viewable-attr:tel % dpconf set-jdbc-data-view-prop mysql1-view writable-attr:dn writable-attr:objectclass \ writable-attr:sn writable-attr:room writable-attr:userpassword writable-attr:jobtitle \ writable-attr:country writable-attr:tel |
These definitions apply only in the context of the join view. By default all attributes can be read and written if you access the JDBC data view directly.
As the proxy manager, add a global ACI that allows anonymous access to the join data view.
% ldapmodify -p 1389 -D "cn=proxy manager" -w password dn: cn=myjoin1,cn=virtual access controls changetype: add objectclass: acisource dpsaci: (targetattr="*") (target = "ldap:///o=join") \ (version 3.0; acl "anonymous_access"; allow(all) userdn="ldap:///anyone";) cn: myjoin1 |
Create a connection handler to handle connections to the o=join domain.
% dpconf create-connection-handler myjoin1-handler |
Enable the connection handler and configure it to handle all binds from users under o=join.
% dpconf set-connection-handler-prop myjoin1-handler is-enabled:true \ bind-dn-filters:"uid=.*,ou=people,o=join" |
Configure the connection handler to use the pool of ACIs added previously.
% dpconf set-connection-handler-prop myjoin1-handler aci-source:myjoin1 |
As an anonymous user, search the join data view.
In this step, we search Kirsten Vaughan's entry to see whether data from both join views is retrieved.
% ldapsearch -p 1389 -b o=join "uid=kvaughan" |
Note that the returned entry includes the attributes from both the LDAP data view and the JDBC data view.
As a user under o=join, modify the userPassword attribute to verify that you can write to the join data view.
% ldapmodify -p 1389 -D "uid=kvaughan,ou=people,o=join" -w myNewPassword dn: uid=kvaughan,ou=people,o=join changetype: modify replace: userPassword userPassword: myPassword |
This configuration describes an organization, Example.com, whose specific directory service requirements are met by some of the features of a virtual directory.
Example.com stores organizational data in multiple disparate data sources. For legacy reasons, user data is spread across an LDAP directory, a flat LDIF file, and an SQL database. The HR department stores user data in an LDAP directory, with a base DN of o=example.com. The Payroll department stores data in an SQL database. Administrative data such as departments and building numbers is stored by the administration department in an LDIF file, with a base DN of dc=example,dc=com.
In addition, Example.com has acquired a company named Company22. Company 22 also stores its user data in an LDAP directory, with a base DN of dc=company22,dc=com.
The following diagram provides a high level view of how Example.com's user data is stored.
Example.com has several LDAP client applications that require access to the data stored in the disparate data sources. The requirements of the client applications are not all the same. Different views of the data are required. In some cases, the clients require the data to be aggregated. In addition, some client applications require access to Company22's user data so that these new employees of Example.com can be administered along with the old employees.
The following diagram provides a high level view of Example.com's client application requirements.
The following sections walk you through sufficient configuration Directory Proxy Server data views to meet the client application requirements described in this sample scenario. For information about how data views work, see Chapter 17, Directory Proxy Server Distribution, in Sun Java System Directory Server Enterprise Edition 6.2 Reference and Chapter 18, Directory Proxy Server Virtualization, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The configuration of the sample scenario is divided into the following sections:
Aggregate Data From the HR LDAP Directory and the Administration LDIF File
Add Data From Company 22 to Example.Com's DIT by Renaming the DN
Enable LDAP Clients to Access the Payroll Data in an SQL Database
The HR department stores information such as employee names, job start data, and job level. The administration department stores additional data such as building codes and office numbers. The client application that handles the HR data requires access to the combined data from both sources. Both data sources have a common attribute, the employeeNumber that exists in each entry.
The following diagram illustrates the requirements of the client application.
To fulfill this application requirement, a data view is created for the payroll directory and for the administration LDIF file. These two data views are then joined to provide access to the aggregated data. This common attribute enables Directory Proxy Server to aggregate the data for each user.
For simplicity, the commands used in this section assume the following information:
A Directory Proxy Server instance runs on the local host, with the default LDAP port (389).
The Directory Proxy Server instance is located at /local/myDPS.
The path to the file containing the Proxy Manager password has been set as a variable, LDAP_ADMIN_PWF. For more information about setting Directory Proxy Server environment variables, see Environment Variables in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.
The payroll LDAP directory runs on a host named payrollHost, on port 2389.
The LDIF file used to store the administration data is named example.ldif.
To obtain the complete syntax of each command, run the command without any options. For example:
$ dpconf create-ldap-data-view Operands are missing Usage: dpcfg create-ldap-data-view VIEW_NAME POOL_NAME SUFFIX_DN
Create an LDAP data source for the payroll directory.
$ dpconf create-ldap-data-source payroll-directory payrollHost:2389
Create an LDAP data source pool for the payroll directory.
$ dpconf create-ldap-data-source-pool payroll-pool
Attach the payroll data source to the data source pool.
$ dpconf attach-ldap-data-source payroll-pool payroll-directory
Configure the weights of the attached data source.
$ dpconf set-attached-ldap-data-source-prop -h payrollHost -p 2389 \ payroll-pool payroll-directory add-weight:2 \ bind-weight:2 compare-weight:2 delete-weight:2 \ modify-dn-weight:2 modify-weight:2 search-weight:2
Create an LDAP data view for the payroll directory.
$ dpconf create-ldap-data-view payroll-view payroll-pool o=example.com
Enable the LDAP data view so that client requests can be routed to this data view.
$ dpconf set-ldap-data-view-prop payroll-view is-enabled:true
Restart Directory Proxy Server for the changes to take effect.
$ dpadm restart /local/myDPS
Create an LDIF data view for the administration data.
$ dpconf create-ldif-data-view admin-view example.ldif dc=example,dc=com
Enable the LDIF data view for the administration data.
$ dpconf set-ldif-data-view-prop admin-view is-enabled:true
Specify that the admin view contains entries that are used by more than one entry in the payroll view.
$ dpconf set-ldif-data-view-prop admin-view contains-shared-entries:true
When this property is set to TRUE, deleting an entry in the payroll data view will not result in the deletion of the shared entry in the admin data view. Adding an entry to the payroll data view will only add the entry to the secondary data view if it does not already exist.
Restart Directory Proxy Server for the changes to take effect.
$ dpadm restart /local/myDPS
Create a filter join rule on the admin data view that specifies how the data should be aggregated.
The following join rule specifies that data should be joined based on the employeeNumber attribute of the user entry.
$ dpconf set-ldif-data-view-prop admin-view \ filter-join-rule:'employeeNumber=\${payroll-view.employeeNumber}'
Create a join data view that aggregates the two data views.
For the join data view, the organization uses the suffix DN dc=example,dc=com.
$ dpconf create-join-data-view example-join-view payroll-view admin-view \ dc=example,dc=com
The user data for Company 22 is stored under the DN dc=company22,dc=com. While Example.com wants to keep this user data separate in most cases, one client application needs to administer Company 22 employees along with the rest of the Example.com employees. This client application requires Company 22's user data to look like Example.com data.
The following diagram illustrates the requirements of the client application.
To fulfill this application requirement, a data view with a virtual DN of dc=example,dc=com is created for the Company 22's directory.
For simplicity, the commands used in this section assume the following information:
A Directory Proxy Server instance runs on the local host, with the default LDAP port (389).
The Directory Proxy Server instance is located at /local/myDPS.
The path to the file containing the Proxy Manager password has been set as a variable, LDAP_ADMIN_PWF. For more information about setting Directory Proxy Server environment variables, see Environment Variables in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.
The Company 22 LDAP directory runs on a host named company22Host, on port 2389.
Create an LDAP data source for Company 22's directory.
$ dpconf create-ldap-data-source company22-directory company22Host:2389
Create an LDAP data source pool for Company 22's directory.
$ dpconf create-ldap-data-source-pool company22-pool
Attach Company 22's data source to the data source pool.
$ dpconf attach-ldap-data-source company22-pool company22-directory
Configure the weights of the attached data source.
$ dpconf set-attached-ldap-data-source-prop -h company22Host -p 2389 \ company22-pool company22-directory add-weight:2 \ bind-weight:2 compare-weight:2 delete-weight:2 \ modify-dn-weight:2 modify-weight:2 search-weight:2
Create an LDAP data view for Company 22's directory with a virtual DN of dc=example,dc=com.
$ dpconf create-ldap-data-view company22-view company22-pool dc=example,dc=com
Instruct Directory Proxy Server to map this virtual DN to the real DN that is in Company 22's directory.
$ dpconf set-ldap-data-view-prop company22-view \ dn-mapping-source-base-dn:dc=company22,dc=com
Enable the LDAP data view for Company 22's directory so that client requests can be routed to this data view.
$ dpconf set-ldap-data-view-prop company22-view is-enabled:true
Restart Directory Proxy Server for the changes to take effect.
$ dpadm restart /local/myDPS
The HR department requires an aggregated view of the HR data for Example.com and the newly acquired Company 22. The following diagram illustrates the requirements of the global HR application.
Create a filter join rule on the Company 22 data view that specifies how the data should be aggregated.
The following join rule specifies that data should be joined based on the employeeNumber attribute of the user entry.
$ dpconf set-ldif-data-view-prop company22-view \ filter-join-rule:'employeeNumber=\${example-join-view.employeeNumber}'
Create a join data view that aggregates Company 22's data view and Example.com's join data view.
$ dpconf create-join-data-view global-join-view example-join-view \ company22-view dc=example,dc=com
Example.com's payroll department stores salary data in an SQL database. The database has two tables, and employee table and a salary table. Example.com has an LDAP client application that requires access to that data. The client application requires the SQL data to look like LDAP data.
The following diagram illustrates the requirements of the client application.
To fulfill this application requirement, a JDBC data view is created that maps columns in the SQL tables to LDAP attributes.
For simplicity, the commands used in this section assume the following information:
A Directory Proxy Server instance runs on the local host, with the default LDAP port (389).
The Directory Proxy Server instance is located at /local/myDPS.
The path to the file containing the Proxy Manager password has been set as a variable, LDAP_ADMIN_PWF. For more information about setting Directory Proxy Server environment variables, see Environment Variables in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.
The SQL database is up and running.
The JAVA_HOME variable has been set to the correct Java path.
The password to the SQL database is myPassword stored in the myPasswordFile file.
Create a JDBC data source for the payroll database.
$ dpconf create-jdbc-data-source -b payrollsqldb \ -B jdbc:payrollsqldb:payrollsql://localhost/ \ -J file://payrollsqldb.jar \ -S org.payrollsqldb.jdbcDriver payroll-src
Configure the JDBC data source with the properties of the SQL database.
$ dpconf set-jdbc-data-source-prop payroll-src \ db-user:proxy db-pwd-file:password-file-location/myPasswordFile
Enable the JDBC data source.
$ dpconf set-jdbc-data-source-prop payroll-src is-enabled:true
Create a JDBC data source pool for the payroll database.
$ dpconf create-jdbc-data-source-pool payroll-pool
Attach the payroll data source to the data source pool.
$ dpconf attach-jdbc-data-source payroll-pool payroll-src
Create a JDBC data view for the payroll database, with a virtual DN of o=payroll.
$ dpconf create-jdbc-data-view payroll-view payroll-pool o=payroll
Create a JDBC table for each table in the SQL database.
$ dpconf create-jdbc-table jdbc-employee employee $ dpconf create-jdbc-table jdbc-salary salary
Add a JDBC attribute for each column in the SQL tables.
$ dpconf add-jdbc-attr jdbc-employee eid employee_id $ dpconf add-jdbc-attr jdbc-employee first firstname $ dpconf add-jdbc-attr jdbc-employee last lastname $ dpconf add-jdbc-attr jdbc-employee description description $ dpconf add-jdbc-attr jdbc-employee spouse spousename $ dpconf add-jdbc-attr jdbc-salary salary salary $ dpconf add-jdbc-attr jdbc-salary social ssn
Specify which attributes can be viewed and which can be written, through the JDBC data view.
$ dpconf set-jdbc-data-view-prop payroll-view \ viewable-attr:eid \ viewable-attr:first \ viewable-attr:last \ viewable-attr:desc \ viewable-attr:spouse \ viewable-attr:salary \ viewable-attr:social $ dpconf set-jdbc-data-view-prop payroll-view \ writable-attr:eid \ writable-attr:first \ writable-attr:last \ writable-attr:description \ writable-attr:spouse \ writable-attr:salary \ writable-attr:social
Create a JDBC object class that maps to an LDAP object class.
The following command creates an object class that maps to the LDAP person object class. The object class specifies that the employee table should be used as the primary table, and that the salary table should be used as the secondary table. The eid attribute should be used to construct the DN.
$ dpcfg create-jdbc-object-class payroll-view \ person jdbc-employee jdbc-salary eid
Create a filter join rule on the secondary table that specifies how data from the secondary table should be linked to data from the primary table.
The following join rule specifies that data should be joined based on the employee_id attribute.
$ dpconf set-jdbc-table-prop jdbc-salary \ filter-join-rule:'employee_id=\${employee.employee_id}'
Create a super class on the JDBC object class.
$ set-jdbc-object-class-prop payroll-view person super-class:extensibleObject
Access control on LDAP directories is handled by defining ACIs in the directories themselves. When data sources are accessed through virtual data views, ACIs must be defined that apply only to the data viewed through these data views.
Any access that goes through Directory Proxy Server is controlled by a connection handler. For information about connection handlers, see Chapter 25, Connections Between Clients and Directory Proxy Server .
Add the ACI.
$ ldapadd -v -D "cn=proxy manager" -w password -p 389 dn: cn=ldifonly-acis,cn=virtual access controls objectclass: top objectclass: aciSource cn: ldifonly-acis dpsaci: (targetattr="*")(version 3.0; acl "anonymous_access"; allow(all) \ (userdn="ldap:///anyone");)
Point the connection handler to the virtual ACI.
$ dpconf set-connection-handler-prop anonymous aci-source:ldifonly-acis
Enable the connection handler.
$ dpconf set-connection-handler-prop anonymous is-enabled:true
This chapter describes how to configure connections between Directory Proxy Server and back-end LDAP servers. The chapter covers the following topics:
Configuring Connections Between Directory Proxy Server and Back-End LDAP Servers
Configuring SSL Between Directory Proxy Server and Back-End LDAP Servers
Choosing SSL Ciphers and SSL Protocols for Directory Proxy Server
When an LDAP data source is created, the number of default connections opened for the LDAP data source are six, that is, two for each read, bind, and write operations respectively. To verify the default connections, type the following command:
dpconf get-ldap-data-source-prop src-name num-read-init num-write-init num-bind-init num-bind-init : 2 num-read-init : 2 num-write-init : 2 |
The number of connections increases automatically when the traffic increases.
For information about how to configure connections between Directory Proxy Server and back-end LDAP servers, see the following procedures:
This procedure configures the number of connections for bind operations. To configure the number of connections for read or write operations, perform the same procedure but replace bind with read or write.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the initial number of connections between Directory Proxy Server and a back-end LDAP server for bind operations.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ num-bind-init:new-value |
Configure the increment of connections for bind operations.
The increment is the number of connections that are added each time more than the current number of connections are requested.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ num-bind-incr:new-value |
Configure the maximum number of connections for bind operations.
When this maximum number of connections is reached, no more connections can be added.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ num-bind-limit:new-value |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the maximum length of time that Directory Proxy Server can attempt to connect to a data source.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ connect-timeout:new-value |
For example, configure the connection timeout to 10 milliseconds.
$ dpconf set-ldap-data-source-prop -h host1 -p 1389 data-source-name connect-timeout:10 |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the maximum length of time that Directory Proxy Server can wait for an established connection in a connection pool to become available.
$ dpconf set-server-prop -h host -p port data-source-name \ connection-pool-wait-timeout:value |
For example, configure the timeout to 20 seconds.
$ dpconf set-ldap-data-source-prop -h host1 -p 1389 data-source-name \ connection-pool-wait-timeout:20000 |
The following procedure describes how to configure SSL between Directory Proxy Server and back-end LDAP servers.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure a secure port between Directory Proxy Server and the back-end LDAP server.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ ldaps-port:port-number |
Configure when SSL is used for connections between Directory Proxy Server and the back-end LDAP server.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name ssl-policy:value |
If value is always, SSL is always used for connections.
If value is client, SSL is used if the client is using SSL.
If the connection is not using SSL, you can promote the connection to SSL by using the startTLS command.
Choose the protocols and ciphers for SSL as described in Choosing SSL Ciphers and SSL Protocols for Directory Proxy Server.
Configure Directory Proxy Server to validate an SSL server certificate from the back-end LDAP server.
For information, see To Add a Certificate From a Back-End Directory Server to the Certificate Database on Directory Proxy Server.
If the back-end LDAP server requests a certificate from Directory Proxy Server, configure Directory Proxy Server to send an SSL client certificate.
For information, see Exporting a Certificate to a Back-End LDAP Server.
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.
The ciphers and protocols that can be used by Directory Proxy Server depend on the JavaTM Virtual Machine (JVMTM) that is being used. By default, Directory Proxy Server uses the default ciphers and protocols that are enabled for the JVM machine.
Use this procedure to retrieve the supported ciphers and protocols, and the enabled ciphers and protocols. If a cipher or protocol is supported, you can enable or disable it.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the list of supported ciphers and protocols.
$ dpconf get-server-prop -h host -p port supported-ssl-cipher-suites \ supported-ssl-protocols |
View the list of enabled ciphers and protocols.
$ dpconf get-server-prop -h host -p port enabled-ssl-cipher-suites \ enabled-ssl-protocols |
Enable one or more supported ciphers or protocols.
Enable one or more supported ciphers.
$ dpconf set-server-prop -h host -p port \ enabled-ssl-cipher-suites:supported-ssl-cipher-suite \ [enabled-ssl-cipher-suites:supported-ssl-cipher-suite ...] |
To add a cipher to an existing list of supported ciphers, use this command:
$ dpconf set-server-prop -h host -p port \ enabled-ssl-cipher-suites+:supported-ssl-cipher-suite |
Enable one or more supported protocols.
$ dpconf set-server-prop -h host -p port \ enabled-ssl-cipher-protocols:supported-ssl-cipher-protocol \ [enabled-ssl-cipher-protocols:supported-ssl-cipher-protocol ...] |
To add a protocol to an existing list of supported protocols, use this command:
$ dpconf set-server-prop -h host -p port \ enabled-ssl-cipher-protocols+:supported-ssl-cipher-protocol |
(Optional) Disable a supported cipher or protocol.
$ dpconf set-server-prop -h host -p port \ enabled-ssl-cipher-protocols-:supported-ssl-cipher-protocol |
This section contains information about the various methods you can use to forward requests from Directory Proxy Server to back-end LDAP servers.
For information about bind replay for client credentials in Directory Proxy Server, see Directory Proxy Server Configured for BIND Replay in Sun Java System Directory Server Enterprise Edition 6.2 Reference. The following procedure describes how to forward requests from Directory Proxy Server to a back-end LDAP server by using bind replay.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the data source client credentials to authenticate to a back-end LDAP server by using the credentials provided by a client.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ client-cred-mode:use-client-identity |
For information about proxy authorization in Directory Proxy Server, see Directory Proxy Server Configured for Proxy Authorization in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This section contains procedures for forwarding requests by using proxy authorization and by using a proxy authorization control.
Configure the data source to expect proxy authorization controls of either version 1 or version 2.
For example, configure the data source to expect proxy authorization controls of version 1.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ proxied-auth-use-v1:true |
Alternatively, configure the data source to expect proxy authorization controls of version 2.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ proxied-auth-use-v1:false |
Configure the data source to authenticate to a back-end LDAP server by using proxy authorization.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ client-cred-mode:use-proxy-auth |
To configure a data source to authenticate to a back-end LDAP server by using proxy authorization for write operations only, run this command:
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ client-cred-mode:use-proxy-auth-for-write |
When write operations only are performed with a proxy authorization control, the client identity is not forwarded to the LDAP server for read requests. For more information about forwarding requests without the client identity, see Forwarding Requests Without the Client Identity.
Configure the data source with the bind credentials of Directory Proxy Server.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ bind-dn:DPS-bind-dn bind-pwd-file:filename |
Configure the data source with the timeout.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ proxied-auth-check-timeout:value |
Directory Proxy Server verifies that the client DN has the relevant ACIs for proxy authorization by using the getEffectiveRights command. The result is cached in Directory Proxy Server and renewed when the proxied-auth-check-timeout expires.
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.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure Directory Proxy Server to accept proxy authorization controls of version 1, version 2, or both.
$ dpconf set-server-prop -h host -p port allowed-ldap-controls:proxy-auth-v1 \ allowed-ldap-controls:proxy-auth-v2 |
The following procedure describes how to forward requests from Directory Proxy Server to a back-end LDAP server without forwarding the client identity.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the data source to authenticate to a back-end LDAP server by using the credentials of Directory Proxy Server.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ client-cred-mode:use-specific-identity |
Configure the data source with the bind credentials of Directory Proxy Server.
$ dpconf set-ldap-data-source-prop -h host -p port data-source-name \ bind-dn:bind-dn-of-DPS bind-pwd-file:filename |
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.
This section contains information about how to forward requests as an alternate user.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Enable operations to be forwarded with an alternate user.
$ dpconf set-server-prop -h host -p port enable-user-mapping:true |
Specify the name of the attribute that contains the ID for remote mapping.
$ dpconf set-server-prop -h host -p port \ remote-user-mapping-bind-dn-attr:attribute-name |
Enable Directory Proxy Server to map the client ID remotely.
$ dpconf set-server-prop -h host -p port enable-remote-user-mapping:true |
Configure the default mapping.
$ dpconf set-server-prop -h host -p port \ user-mapping-default-bind-dn:default-mapping-bind-dn \ user-mapping-default-bind-pwd-file:filename |
If the mapped identity is not found on the remote LDAP server, the client identity is mapped to the default identity.
Configure the user mapping in the entry for the client on the remote LDAP server.
For information about configuring user mapping in Directory Server, see Proxy Authorization.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Enable operations to be forwarded with an alternate user.
$ dpconf set-server-prop -h host -p port enable-user-mapping:true |
Ensure that Directory Proxy Server is not configured to map the client ID remotely.
$ dpconf set-server-prop -h host -p port enable-remote-user-mapping:false |
Configure the default mapping.
$ dpconf set-server-prop -h host -p port \ user-mapping-default-bind-dn:default-mapping-bind-dn \ user-mapping-default-bind-pwd-file:filename |
The client ID is mapped to this DN if the mapping on the remote LDAP server fails.
If you permit unauthenticated users to perform operations, configure the mapping for unauthenticated clients.
$ dpconf set-server-prop -h host -p port \ user-mapping-anonymous-bind-dn:anonymous-mapping-bind-dn \ user-mapping-anonymous-bind-pwd-file:filename |
For information about how to permit unauthenticated users to perform operations, see To Configure Anonymous Access.
Configure the ID of the client.
$ dpconf set-user-mapping-prop -h host -p port \ user-bind-dn:client-bind-dn user-bind-pwd-file:filename |
Configure the ID of the alternate user.
$ dpconf set-user-mapping-prop -h host -p port \ mapped-bind-dn:alt-user-bind-dn mapped-bind-pwd-file:filename |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Configure the mapping for unauthenticated clients.
$ dpconf set-server-prop -h host -p port \ user-mapping-anonymous-bind-dn:anonymous-mapping-bind-dn \ user-mapping-anonymous-bind-pwd-file:filename |
The mapping for anonymous clients is configured in Directory Proxy Server because the remote LDAP server does not contain an entry for an anonymous client.
For information about permitting unauthenticated users to perform operations, see To Configure Anonymous Access.
For an overview of the connections between clients and Directory Proxy Server, connection handlers, and a description of the criteria and policies used in connection handlers, see Chapter 20, Connections Between Clients and Directory Proxy Server, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This chapter covers the following topics:
Creating and Configuring Request Filtering Policies and Search Data Hiding Rules
Configuring Directory Proxy Server as a Connection Based Router
For information about how to create, configure, and delete connection handlers, and to configure affinity for data views, see the following procedures.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a connection handler.
$ dpconf create-connection-handler -h host -p port connection-handler-name |
(Optional) View the list of connection handlers.
$ dpconf list-connection-handlers -h host -p port |
The properties of a connection handler must be defined in relation to the properties of the other connection handlers that are defined for the Directory Proxy Server instance. Consider the properties of all of your connection handlers to ensure that they specify different sets of criteria and are prioritized correctly.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View a verbose list of connection handlers to see their key properties and relative priorities.
$ dpconf list-connection-handlers -h host -p port -v Name is-enabled priority description -------------------------- ---------- -------- --------------------------- anonymous false 99 unauthenticated connections default connection handler true 100 default connection handler |
The connection handlers anonymous and default connection handler are created when you create an instance of Directory Proxy Server.
View all of the properties of one connection handler.
$ dpconf get-connection-handler-prop -h host -p port connection-handler-name |
The default properties of a new connection handler are as follows:
aci-source : - allowed-auth-methods : anonymous allowed-auth-methods : sasl allowed-auth-methods : simple allowed-ldap-ports : ldap allowed-ldap-ports : ldaps bind-dn-filters : any data-view-routing-custom-list : - data-view-routing-policy : all-routable description : - domain-name-filters : any enable-data-view-affinity : false ip-address-filters : any is-enabled : false is-ssl-mandatory : false priority : 99 request-filtering-policy : no-filtering resource-limits-policy : no-limits schema-check-enabled : false user-filter : any |
Configure the priority of the connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name priority:value |
The priority can be any number from 1 to 100, where 1 is the highest priority. For an instance of Directory Proxy Server, the connection handlers are evaluated in order of priority.
(Optional) Specify the DN filtering property of the connection handler.
This property enables you to control access based on part or all of the bind DN. The value of the property is a regular expression.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ bind-dn-filters:regular-expression |
The bind DN filter takes the form of a JavaTM regular expression. For information about creating Java regular expressions, see http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html.
For example, to send all binds from users under ou=people,dc=example,dc=com to a connection handler named secure-handler, set the bind-dn-filters property as follows:
$ dpconf set-connection-handler-prop -h host1 -p 1389 secure-handler \ bind-dn-filters:"uid=.*,ou=people,dc=example,dc=com" |
(Optional) Specify the name of a request filtering policy to use with this connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ request-filtering-policy:policy-name |
where policy-name is the name of an existing request filtering policy. For information about how to create and configure a request filtering policy, see Creating and Configuring Request Filtering Policies and Search Data Hiding Rules.
(Optional) Specify the name of a resource limits policy to use with this connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ resource-limits-policy:policy-name |
where policy-name is the name of an existing resource limits policy. For information about how to create and configure a resource limits policy, see Creating and Configuring a Resource Limits Policy.
Configure any other properties that are listed in Step 2.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ property:value [property:value ...] |
For example, configure the connection handler to accept SSL connections only.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ is-ssl-mandatory:true |
For a description of a property and a list of its valid values, run this command:
$ dpconf help-properties connection-handler |
Enable the connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name is-enabled:true |
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.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
(Optional) View the list of connection handlers.
$ dpconf list-connection-handlers -h host -p port |
Delete one or more connection handlers.
$ dpconf delete-connection-handler -h host -p port connection-handler-name [connection-handler-name ... ] |
When a connection is allocated to a connection handler, requests on that connection are exposed to the list of data views that are configured for that connection handler, or to all of the configured data views. Successive requests on that connection are exposed exclusively to the data view that is used for the first request.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Enable affinity for data views.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ enable-data-view-affinity:true |
(Optional) Configure the connection handler to route requests to a custom list of data views.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name data-view-routing-policy:custom |
(Optional) Configure the list of data views.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ data-view-routing-custom-list:view-name [data-view-routing-custom-list:view-name ...] |
To add a data view to an existing list of data views, use this command:
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ data-view-routing-custom-list+:view-name |
To remove a data view from an existing list of data views, use this command:
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ data-view-routing-custom-list-:view-name |
For an overview of request filtering policies, see Request Filtering Policies for Connection Handlers in Sun Java System Directory Server Enterprise Edition 6.2 Reference. For an overview of search data hiding rules, see Search Data Hiding Rules in the Request Filtering Policy in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
For information about how to create and configure request filtering policies and search data hiding rules, see the following procedures.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a request filtering policy.
$ dpconf create-request-filtering-policy policy-name |
Associate the request filtering policy with a connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ request-filtering-policy:policy-name |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the properties of a request filtering policy.
$ dpconf get-request-filtering-policy-prop -h host -p port policy-name |
The default properties of a request filtering policy are as follows:
allow-add-operations : true allow-bind-operations : true allow-compare-operations : true allow-delete-operations : true allow-extended-operations : true allow-inequality-search-operations : true allow-modify-operations : true allow-rename-operations : true allow-search-operations : true allowed-comparable-attrs : all allowed-search-scopes : base allowed-search-scopes : one-level allowed-search-scopes : subtree allowed-subtrees : "" description : - prohibited-comparable-attrs : none prohibited-subtrees : none |
Configure the request filtering policy by setting one ore more of the properties listed in Step 1.
$ dpconf set-request-filtering-policy-prop -h host -p port policy-name \ property:value [property:value ...] |
By setting the properties listed in Step 1, you configure the following features of the request filtering policy:
The types of operations that clients are allowed to perform
The subtrees that are exposed to a client or hidden from a client
The scope for search operations
The types of search filters
The attribute types that can or cannot be compared in search and compare operations
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create one or more search data hiding rules for a request filtering policy.
$ dpconf create-search-data-hiding-rule -h host -p port policy-name rule-name \ [rule-name ...] |
View the properties of a search data hiding rule.
$ dpconf get-search-data-hiding-rule-prop policy-name rule-name |
The default properties of a search data hiding rule are as follows:
attrs : - rule-action : hide-entry target-attr-value-assertions : - target-dn-regular-expressions : - target-dns : - |
Configure a search data hiding rule by setting one or more of the properties listed in Step 2.
$ dpconf set-search-data-hiding-rule-prop -h host -p port policy-name rule-name \ property:value [property:value ...] |
One of the following rule actions can be used:
The target entry is not returned.
The target entry is returned but the specified attributes are filtered out.
The target entry is returned but the unspecified attributes are filtered out.
The rule can be applied to the following entries:
Entries with the specified DN
Entries with the specified DN pattern
Entries with a specified attribute name and attribute value pair (attrName#attrValue)
The following configuration defines a search data hiding rule that hides entries of type inetorgperson.
$ dpconf set-search-data-hiding-rule-prop -h host1 -p port my-policy my-rule \ target-attr-value-assertions:objectclass#inetorgperson |
The following examples contain a request filtering policy and a search data hiding rule. When the request filtering policy is combined with the search data hiding rule, access to data is limited as follows:
The following types of operations are disallowed: add, delete, extended, modify, and rename.
Only the ou=people,dc=sun,dc=com subtree can be accessed.
Entries other than inetorgperson type are returned by search operations.
allow-add-operations : false allow-bind-operations : true allow-compare-operations : true allow-delete-operations : false allow-extended-operations : false allow-inequality-search-operations : true allow-modify-operations : false allow-rename-operations : false allow-search-operations : true allowed-comparable-attrs : all allowed-search-scopes : base allowed-search-scopes : one-level allowed-search-scopes : subtree allowed-subtrees : ou=people,dc=sun,dc=com description : myRequestFilteringPolicy prohibited-comparable-attrs : none prohibited-subtrees : none |
attrs : - rule-action : hide-entry target-attr-value-assertions : objectclass:inetorgperson target-dn-regular-expressions : - target-dns : - |
For an overview of resource limits policies, see Resource Limits Policies for Connection Handlers in Sun Java System Directory Server Enterprise Edition 6.2 Reference. For information about how to create and configure resource limits policies and to customize search limits, see the following procedures.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create a resource limits policy.
$ dpconf create-resource-limits-policy -h host -p port policy-name |
For information about how to modify the properties of a resource limits policy, see To Configure a Resource Limits Policy.
Associate the resource limits policy to a connection handler.
$ dpconf set-connection-handler-prop -h host -p port connection-handler-name \ resource-limits-policy:policy-name |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the properties of a resource limits policy.
$ dpconf get-resource-limits-policy-prop -h host -p port policy-name |
The default properties of a resource limits policy are as follows:
description : - max-client-connections : unlimited max-connections : unlimited max-simultaneous-operations-per-connection : unlimited max-total-operations-per-connection : unlimited minimum-search-filter-substring-length : unlimited referral-bind-policy : default referral-hop-limit : default referral-policy : default search-size-limit : unlimited search-time-limit : unlimited |
Configure the resource limits policy by setting one or more of the properties that are listed in Step 1:
$ dpconf set-resource-limits-policy-prop -h host -p port policy-name \ property:value [property:value ...] |
Customized limits can be defined for search operations according to the search base and search scope. If the target DN and scope of a search operation matches the specified criteria, the maximum size of the search result is limited.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Create one or more custom search limits.
$ dpconf create-custom-search-size-limit -h host -p port policy-name \ custom-search-limit-name [custom-search-limit-name ...] |
Set the criteria for the custom search limit.
$ dpconf set-custom-search-size-limit-prop -h host -p port policy-name \ custom-search-limit-name one-level-search-base-dn:value subtree-search-base-dn:value |
Set the limit for the number of results that are returned when a search meets one of the criteria in Step 2.
$ dpconf set-custom-search-size-limit-prop -h host -p port policy-name \ custom-search-limit-name search-size-limit:value |
View the properties of a custom search limit.
$ dpconf get-custom-search-size-limit-prop -h host -p port policy-name \ custom-search-limit-name |
The default properties of a custom search limit are as follows:
one-level-search-base-dn : - search-size-limit : unlimited subtree-search-base-dn : - |
Directory Proxy Server 5.2 is a connection based router. In Directory Proxy Server 5.2, a client connection is routed to a specific directory server. All requests on that client connection are sent to the same directory server until the connection is broken or until the client unbinds.
Directory Proxy Server 6.2 is an operation based router. However, for compatibility, this version of Directory Proxy Server can be configured as a connection based router, as described in the following procedure.
Create and configure one or more connection handlers as described in Creating, Configuring, and Deleting Connection Handlers.
You can also use the default connection handler.
Configure all connection handlers to route requests to the root data view only.
For example:
$ dpconf set-connection-handler-prop -h host1 -p 1389 myConnectionHandler \ data-view-routing-policy:custom data-view-routing-custom-list:"root data view" |
Create and configure a data source for each backend LDAP server as described in Creating and Configuring LDAP Data Sources.
For example:
$ dpconf create-ldap-data-source -h host1 -p 1389 myDataSource host2:2389 |
Create and configure a data source pool as described in Creating and Configuring LDAP Data Source Pools.
For example:
$ dpconf create-ldap-data-source-pool -h host1 -p 1389 myDataSourcePool |
Attach all of the data sources to the data source pool as described in Attaching LDAP Data Sources to a Data Source Pool.
For example,
$ dpconf attach-ldap-data-source -h host1 -p 1389 myDataSourcePool myDataSource |
Configure each data source to authenticate clients by using BIND replay as described in Forwarding Requests With Bind Replay.
For example:
$ dpconf set-ldap-data-source-prop -h host1 -p 1389 myDataSource \ client-cred-mode:use-client-identity |
Configure affinity between the client connection and the data source pool as described in Configuring Client Affinity.
For example:
$ dpconf set-ldap-data-source-pool-prop -h host1 -p 1389 myDataSourcePool \ enable-client-affinity:true client-affinity-policy:read-write-affinity-after-write |
For an overview of client authentication in Directory Proxy Server, see Chapter 21, Directory Proxy Server Client Authentication, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This chapter covers the following topics:
Directory Proxy Server provides a secure listener and a nonsecure listener for communication with clients. For information about listeners for Directory Proxy Server, see Directory Proxy Server Client Listeners in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This section describes how to configure the listeners.
This procedure configures the nonsecure listener between a client and Directory Proxy Server. To configure the secure listener, perform the same procedure but replace ldap with ldaps.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. In DSCC, you can configure this property on the Performance tab.
View the properties of the nonsecure listener.
$ dpconf get-ldap-listener-prop -h host -p port |
The default properties of the nonsecure listener are as follows:
connection-idle-timeout : 1h connection-read-data-timeout : 2s connection-write-data-timeout : 1h is-enabled : true listen-address : 0.0.0.0 listen-port : port-number max-connection-queue-size : 128 max-ldap-message-size : unlimited number-of-threads : 2 use-tcp-no-delay : true |
Change one or more of properties that are listed in Step 1 according to your requirements.
$ dpconf set-ldap-listener-prop -h host -p port property:new-value |
For example, to disable the nonsecure port for an instance of Directory Proxy Server running on host1, run the following command:
$ dpconf set-ldap-listener-prop -h host1 -p 1389 is-enabled:false |
If you plan to use a non-privileged port number, you must run Directory Proxy Server as root.
To change the nonsecure port number, run the following command:
$ dpconf set-ldap-listener-prop -h host -p port listen-port:new-port-number |
If necessary, restart the instance of Directory Proxy Server for the changes to take effect.
Changes to certain listener properties require a server restart. dpconf alerts you if the server must be restarted. For information about restarting Directory Proxy Server, see To Restart Directory Proxy Server.
By default, Directory Proxy Server is configured for simple bind authentication. No additional configuration is required for simple bind authentication.
For information about authentication between clients and Directory Proxy Server, see Client Authentication Overview in Sun Java System Directory Server Enterprise Edition 6.2 Reference. For information about how to configure authentication, see the following procedures.
For information about certificate-based authentication of clients, see Configuring Certificates in Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This section describes how to configure certificate-based authentication.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Certificate-based authentication can only be performed over an SSL connection.
Configure Directory Proxy Server to require a client to present a certificate when the client establishes an SSL connection.
$ dpconf set-server-prop -h host -p port allow-cert-based-auth:require |
For information about anonymous access, see Anonymous Access in Sun Java System Directory Server Enterprise Edition 6.2 Reference. For information about how to map the identity of an anonymous client to another identity, see Forwarding Requests as an Alternate User.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Permit unauthenticated users to perform operations.
$ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:true |
For information about SASL external bind, see Using SASL External Bind in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Disallow unauthenticated operations.
$ dpconf set-server-prop -h host -p port allow-unauthenticated-operations:false |
Require clients to present a certificate when establishing a connection.
$ dpconf set-server-prop -h host -p port allow-cert-based-auth:require |
The client provides a certificate that contains a DN.
Enable the authentication of clients by SASL external bind.
$ dpconf set-server-prop -h host -p port allow-sasl-external-authentication:true |
Configure the identity used by Directory Proxy Server to map a client certificate on a back-end LDAP server.
$ dpconf set-server-prop -h host -p port cert-search-bind-dn:bind-DN \ cert-search-bind-pwd-file:filename |
Configure the base DN of the subtree that Directory Proxy Server searches.
Directory Proxy Server searches the subtree to find a user entry that is mapped to a client certificate.
$ dpconf set-server-prop -h host -p port cert-search-base-dn:base-DN |
Map information in the client certificate to certificates on the LDAP server.
Name the attribute on the LDAP server that contains certificates.
$ dpconf set-server-prop cert-search-user-attribute:attribute |
Map an attribute on the client certificate to the DN of the entry on the LDAP server that contains certificates.
$ dpconf set-server-prop -h host -p port \ cert-search-attr-mappings:client-side-attribute-name:server-side-attribute-name |
For example, to map a client certificate with the DN cn=user1,o=sun,c=us to an LDAP entry with the DN uid=user1,o=sun, run the following command:
$ dpconf set-server-prop -h host1 -p 1389 cert-search-attr-mappings:cn:uid \ cert-search-attr-mappings:o:o |
(Optional) Route requests for SASL external bind operations to all data views or to a custom list of data views.
To route requests to all data views, run this command:
$ dpconf set-server-prop -h host -p port cert-data-view-routing-policy:all-routable |
To route requests to a list of data views, run this command:
$ dpconf set-server-prop -h host -p port cert-data-view-routing-policy:custom \ cert-data-view-routing-custom-list:view-name [view-name...] |
Directory Proxy Server logs information in access logs and error logs. Unlike Directory Server, Directory Proxy Server does not have an audit log. For a description of the logs in Directory Proxy Server, see Chapter 23, Directory Proxy Server Logging, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
This chapter covers the following topics:
You can view Directory Proxy Server logs directly through the log files or by using Directory Service Control Center (DSCC).
By default, the logs are stored in this directory:
instance-path/logs |
The following figure shows a screen capture of the error log for Directory Proxy Server on DSCC.
Directory Proxy Server error logs and access logs can be configured by using the dpconf command or DSCC. For information about how to configure the logs by using DSCC, see the Directory Proxy Server online help. This section describes how to configure Directory Proxy Server logs by using the dpconf command.
You can retrieve a complete list of the configuration options along with the allowed values and default values by running these commands:
$ dpconf help-properties error-log
$ dpconf help-properties access-log
This procedure configures the Directory Proxy Server access log. To configure the Directory Proxy Server error log, perform the same procedure but replace access with error.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the properties of the access log.
$ dpconf get-access-log-prop -h host -p port |
The default properties of an access log are as follows:
default-log-level : info enable-log-rotation : true log-buffer-size : 9.8k log-file-name : logs/access log-file-perm : 600 log-level-client-connections : - log-level-client-disconnections : - log-level-client-operations : - log-level-connection-handlers : - log-level-data-sources : - log-level-data-sources-detailed : - log-min-size : 100M log-rotation-frequency : 1h log-rotation-policy : size log-rotation-size : 100M log-rotation-start-day : 1 log-rotation-start-time : 0000 log-search-filters : false max-age : unlimited max-log-files : 10 max-size : unlimited min-free-disk-space-size : 1M |
Change one or more of the properties that are listed in Step 1.
$ dpconf set-access-log-prop -h host -p port property:value \ [property:value ...] |
For example, to set the default log level for all message categories to warning, set the value of the default-log-level property to warning.
$ dpconf set-access-log-prop -h host1 -p 1389 default-log-level:warning |
To disable all logs, irrespective of the log level for each message category, set the value of the default-log-level property to none.
$ dpconf set-access-log-prop -h host1 -p 1389 default-log-level:none |
To reset a specific log level to the default log level, set that log level property to inherited. For example, to reset the log level for client connections, run the following command:
$ dpconf set-access-log-prop -h host1 -p 1389 log-level-client-connections:inherited |
For information about properties that can be set by the set-access-log-prop subcommand, type:
$ dpconf help-properties access-log |
By default, log files are rotated when the log file size reaches 100 Mbytes. Ten log files are retained by default, after which the rotation procedure begins to overwrite the oldest log file. This section describes how to configure Directory Proxy Server logs for scheduled rotation, how to rotate logs manually, and how to disable log rotation. For example configurations, see Example Configurations for Log Rotation.
This procedure configures the Directory Proxy Server access log. To configure the Directory Proxy Server error log, perform the same procedure but replace access with error.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
(Optional) View the properties of the access log.
$ dpconf get-access-log-prop -h host -p port |
(Optional) View valid values for the properties of the access log.
$ dpconf help-properties access-log
To rotate logs when they reach a certain size, set the following properties:
$ dpconf set-access-log-prop -h host -p port \ log-rotation-policy:size log-rotation-size:maximum file size |
If the unit of the maximum file size is not specified, the default unit of bytes is used. When the log file reaches the defined size, the log is rotated. The file size must be at least 1 Mbyte and no more than 2 Gbytes.
For an example of how to rotate logs by size, see Rotating the Log Based on Log Size.
To rotate logs periodically, irrespective of the log size, set the following properties:
$ dpconf set-access-log-prop -h host -p port \ log-rotation-frequency:interval in months, weeks, hours, or minutes \ log-rotation-policy:periodic \ log-rotation-start-day:day in week (1-7) or day in the month (1-31) \ log-rotation-start-time:time of day (hhmm) |
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.
For examples of how to rotate logs periodically, see Rotating the Log Based on Time.
To rotate logs periodically if the log file is big enough, set the log-rotation-frequency and log-min-size properties.
$ dpconf set-access-log-prop -h host -p port \ log-rotation-frequency:interval in months, weeks, hours, or minutes \ log-rotation-policy:periodic log-min-size:minimum file size log-rotation-start-day:day in week (1-7) or day in the month (1-31) \ log-rotation-start-time:time of day (hhmm) |
The log-min-size property represents the minimum size of the log. The rotation takes place at the scheduled time only if the log file is bigger than the specified size.
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.
For an example of how to rotate logs periodically if the file size is big enough, see Rotating the Log Based on Time and Log Size.
This procedure rotates the Directory Proxy Server access log. To rotate the Directory Proxy Server error log, perform the same procedure but replace access with error.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
This procedure disables rotation of the Directory Proxy Server access log. To disable rotation of the Directory Proxy Server error log, perform the same procedure but replace access with error.
Examples of how to configure log rotation by log size, time, or both follow.
This section example shows how to configure a log rotation according to log size only. This configuration rotates the log when it reaches 10 Mbytes, irrespective of the time since the log was last rotated.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-policy:size \ log-rotation-size:10M |
The examples in this section show how to configure log rotation according to the time since the last rotation, irrespective of log size.
This configuration rotates the log at 3:00 today and then every 8 hours, irrespective of the size of the log file.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:8h \ log-rotation-policy:periodic log-rotation-start-time:0300 |
This configuration rotates the log at 3:00, 13:00 and 23:00 every day, irrespective of the size of the log file. Because the log-rotation-start-time parameter takes precedence over the log-rotation-frequency parameter, the log is rotated at 23:00 and then 4 hours later. The log is not rotated at 23:00 and then 10 hours later.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:10h \ log-rotation-policy:periodic log-rotation-start-time:0300 |
This configuration rotates the log at noon on Monday, and then at the same time every week, irrespective of the size of the log file.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:1w \ log-rotation-policy:periodic log-rotation-start-day:2 log-rotation-start-time:1200 |
This configuration rotates the log at noon on Monday, and then every 3 days, irrespective of the size of the log file.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:3d \ log-rotation-policy:periodic log-rotation-start-day:2 log-rotation-start-time:1200 |
The log is rotated on the following days: Monday, Thursday, Sunday, Wednesday, and so on. Notice that the log-rotation-start-day parameter applies to the first week only. The log is not rotated on the Monday of the second week.
This configuration rotates the log at noon on the 22nd day of the month, and then at the same time every month, irrespective of log size.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:1m \ log-rotation-policy:periodic log-rotation-start-day:22 \ log-rotation-start-time:1200 |
If the log-rotation-start-day is set to 31 and the month has only 30 days, the log is rotated on the first day of the following month. If the log-rotation-start-day is set to 31 and the month has only 28 days (February), the log is rotated on the 3rd.
This example shows how to configure a log rotation for a specified interval if the file size is big enough.
This configuration rotates the log at 3:00, 11:00, and 19:00 every day, if the size of the log file exceeds 1 Mbyte. If the size of the log file does not exceed 1 Mbyte, the log file is not rotated.
$ dpconf set-access-log-prop -h host1 -p 1389 log-rotation-frequency:8h \ log-rotation-policy:periodic log-min-size:1M log-rotation-start-time:0300 |
Directory Proxy Server enables you to configure log deletion based on time, size, or free disk space (the default). For more information about these deletion policies, see Log File Deletion in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
The following procedures configure log deletion for the access log. To configure log deletion for the error log, use the same commands, but replace access with error.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Specify the maximum age for log files.
$ dpconf set-access-log-prop -h host -p port max-age:duration |
where duration includes a unit of days (d), weeks (w), or months (M). For example, to delete backup log files older than five days, use this command:
$ dpconf set-access-log-prop -h host1 -p 1389 max-age:5d |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Specify the maximum size for log files.
$ dpconf set-access-log-prop -h host -p port max-size:memory-size |
For example, to delete backup log files greater than 1 Mbyte, use this command:
$ dpconf set-access-log-prop -h host1 -p 1389 max-size:1M |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Specify the minimum available disk space.
$ dpconf set-access-log-prop -h host -p port min-free-disk-space-size:memory-size |
For example, to delete backup log files when the available disk space is less than 2 Mbytes, use this command:
$ dpconf set-access-log-prop -h host1 -p 1389 min-free-disk-space-size:2M |
This section describes how to configure the logging of alert messages to the syslogd daemon and how to configure the operating system to accept syslog alerts.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
(Optional) View the current values of the properties for the system log alerts.
$ dpconf get-server-prop -h host -p port syslog-alerts-enabled \ syslog-alerts-facility syslog-alerts-host |
The default properties for the system log alerts are as follows:
syslog-alerts-enabled : false syslog-alerts-facility : USER syslog-alerts-host : localhost |
The syslog-alerts-host property defines the host name of the syslogd daemon to which the messages are sent. The syslog-alerts-facility property is read-only and causes messages to be sent to the user category in the system log.
Enable alert messages to be logged to the syslogd daemon.
$ dpconf set-server-prop -h host -p port syslog-alerts-enabled:true |
(Optional) Send alert messages to the syslogd daemon on a different host.
$ dpconf set-server-prop -h host -p port syslog-alerts-host:hostname |
This section provides instructions on configuring the SolarisTM, Linux, and HP-UX operating systems to accept syslog alerts.
Add the appropriate facility to the syslog configuration file.
For example, to store all alerts using the USER facility, add the following line to /etc/syslog.conf:
user.info /var/adm/info
Here /var/adm/info is an example local directory in which messages will be stored. Ensure that /var/adm/info exists before continuing.
Restart the syslogd daemon.
Verify that messages are logged in syslog.
$ logger -p user.info "Test message" $ cat /var/adm/info Jun 19 17:18:38 host user: [ID 12345 user.info] Test message
Add the appropriate facility to the syslog configuration file.
For example, to store all alerts using the USER facility, add the following line to /etc/syslog.conf:
user.info /var/adm/info
Here /var/adm/info is an example local directory in which messages will be stored. Ensure that /var/adm/info exists before continuing.
Configure the syslogd daemon to run with the -r option.
This option allows syslogd to accept connections from the network. By default, the -r option is not set.
To set the -r option, add the following line to /etc/sysconfig/syslog:
SYSLOGD_OPTIONS="-m 0 -r"
If /etc/sysconfig/syslog does not exist, add the same line to /etc/init.d/syslog.
Restart the syslogd daemon.
$ /etc/init.d/syslog stop | start
Verify that messages are logged in syslog.
$ logger -p user.info "Test message" $ cat /var/adm/info Jun 19 17:18:38 host user: [ID 12345 user.info] Test message
Add the appropriate facility to the syslog configuration file.
For example, to store all alerts using the USER facility, add the following line to /etc/syslog.conf:
user.info /var/adm/info
Here /var/adm/info is an example local directory in which messages will be stored. Ensure that /var/adm/info exists before continuing.
Restart the syslogd daemon.
$ /sbin/init.d/syslogd stop | start
Verify that messages are logged in syslog.
$ logger -p user.info "Test message" $ cat /var/adm/info Jun 19 17:18:38 host user: [ID 12345 user.info] Test message
To track the path of a client request, you must understand how requests are logged in the Directory Proxy Server access log and in the Directory Server access log. To understand this section, first read Tracking Client Requests Through Directory Proxy Server and Directory Server Access Logs in Sun Java System Directory Server Enterprise Edition 6.2 Reference.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
Locate the connection number for the operation that you want to track in the Directory Server access log.
For example, the following line in the access log shows an operation, op=2 with connection number conn=12839.
[20/Jul/2006:18:01:49 -0500] conn=12839 op=2 msgId=4 - SRCH base="dc=example,dc=com" scope=2 filter="(objectClass=organizationalunit)" attrs=ALL |
Obtain the Directory Proxy Server connection information for that connection.
To obtain this information, search the Directory Server access log to locate all operations with the corresponding connection number. For example, on UNIX systems, run the following grep command to locate all lines in the Directory Server access log that correspond to connection conn=12839:
$ grep conn=12839 access |
The line showing the initial LDAP connection is what you are looking for and will be similar to this:
[19/Jul/2006:16:32:51 -0500] conn=12839 op=-1 msgId=-1 - fd=27 slot=27 LDAP connection from 129.153.160.175:57153 to 129.153.160.175 |
The previous line shows that there is an LDAP connection from 129.153.160.175:57153 to Directory Server. The port number (57153) is the information that is required to link the connection back to the Directory Proxy Server access log. The port number enables you to find the corresponding connection in the Directory Proxy Server log, and to locate the client information from this connection.
If the log files have been rotated since the connection was first established, you need to search the archived log files as well as the current access log file.
Locate the corresponding connection in the Directory Proxy Server access log.
To obtain this information, search the Directory Proxy Server access log to locate all operations with the corresponding port number.
You might find multiple entries in the log file with the same port number. To ensure that you locate the correct entry, include the timestamp from the Directory Server log entry in your search.
For example, on UNIX systems, run the following grep command to locate the connection entry that corresponds to the timestamp and port number found in the Directory Server log:
$ grep 19/Jul/2006:16:32 access | grep 57153 |
Note that the seconds value is excluded from the timestamp to take into account slight differences in server times.
The corresponding line in the Directory Proxy Server log will be similar to this:
[19/Jul/2006:16:32:51 -0500] - SERVER_OP - INFO - Created BIND LDAP connection s_conn=sunds-d1m1-9389:34 client=0.0.0.0:57153 server=idm160.central.sun.com:9389 main |
This line shows that Directory Proxy Server created a BIND connection to s_conn=sunds-d1m1-9389:34. Directory Proxy Server identifies itself as the client client=0.0.0.0 on TCP port 57153.
The important information to extract from this line of the log is the server ID and port number (s_conn=sunds-d1m1-9389:34).
Locate all operations that correspond to the server ID and port number identified in the previous step.
To obtain this information, search the Directory Proxy Server access log for all operations with the corresponding server ID and port number.
For example, on UNIX systems, run the following grep command to locate the operation that corresponds to the server ID found in the previous step:
$ grep s_conn=sunds-d1m1-9389:34 access |
In this case, it is not useful to search for the timestamp because these operations might span several days. However, you must determine that the operations returned by the search are the correct ones. If there are multiple Create connection statements, ensure that you locate the one that corresponds to the original search statement. To do this, match the timestamp to the timestamp found in Step 1.
The following extract of the Directory Proxy Server access log shows all operations returned for s_conn=sunds-d1m1-9389:34.
[19/Jul/2006:16:32:51 -0500] - SERVER_OP - INFO - Created BIND LDAP connection s_conn=sunds-d1m1-9389:34 client=0.0.0.0:57153 server=idm160.central.sun.com:9389 main [20/Jul/2006:18:01:49 -0500] - SERVER_OP - INFO - conn=31 op=0 BIND dn="cn=directory manager" method="SIMPLE" s_msgid=3 s_conn=sunds-d1m1-9389:34 [20/Jul/2006:18:01:49 -0500] - SERVER_OP - INFO - conn=31 op=0 BIND RESPONSE err=0 msg="" s_conn=sunds-d1m1-9389:34 [20/Jul/2006:18:01:49 -0500] - SERVER_OP - INFO - conn=31 op=1 SEARCH base="dc=example,dc=com" scope=2 s_msgid=4 s_conn=sunds-d1m1-9389:34 [20/Jul/2006:18:01:49 -0500] - SERVER_OP - INFO - conn=31 op=1 SEARCH RESPONSE err=0 msg="" nentries=1 s_conn=sunds-d1m1-9389:34 |
With this information, you can see that the connection ID for this search operation on Directory Proxy Server is 31 (conn=31).
Locate the client connection IP address that corresponds to the connection ID found in the previous step.
To obtain this information, search the Directory Proxy Server access log for all operations with the correct connection ID and timestamp. The timestamp to use is the one in the original search statement in Step 1.
For example, on UNIX systems, run the following grep command to locate the client connection IP address:
$ grep "20/Jul/2006:18:01" access | grep conn=31 |
The line you are interested in is similar to this:
[20/Jul/2006:18:01:49 -0500] - CONNECT - INFO - conn=31 client=129.150.64.156:2031 server=0.0.0.0:11389 protocol=LDAP |
Determine who owns the IP address found in the previous step.
With this information, you can establish precisely who was responsible for the operation performed on Directory Server.
Monitoring detects failure of Directory Proxy Server and of data sources.
For a description of the monitoring framework for Directory Proxy Server, and for a detailed layout of the cn=monitor entry, see Monitoring Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This chapter covers the following topics:
Configuring Administrative Alerts for Directory Proxy Server
Retrieving Monitored Data About Directory Proxy Server by Using the JVM
To retrieve monitored data about Directory Proxy Server, use the cn=monitor entry. This entry is managed by Directory Proxy Server in a local, in-memory database. You can retrieve attributes under cn=monitor by performing an LDAP search on the cn=monitor entry. You must bind as the Proxy Manager to search this entry.
For information about using the JVM to retrieve monitored data, see Retrieving Monitored Data About Directory Proxy Server by Using the JVM.
For a description of how Directory Proxy Server monitors the health of data sources, see Monitoring Data Sources in Sun Java System Directory Server Enterprise Edition 6.2 Reference. This section describes how to configure the monitoring of data sources.
In this type of monitoring, Directory Proxy Server listens for errors on the traffic between Directory Proxy Server and the data sources. This type of monitoring is called reactive monitoring because Directory Proxy Server reacts if an error is detected, but does not actively test data sources.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Set the monitoring mode for the data source to reactive.
$ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-mode:reactive |
Configure an alert to be sent when an error is detected or when a data source goes offline or online, as described in Configuring Administrative Alerts for Directory Proxy Server.
Directory Proxy Server creates a dedicated connection to a data source if there have been no requests to or responses from the data source for a specified interval.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Set the monitoring mode for the data source to proactive.
$ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-mode:proactive |
Set the maximum time for which Directory Proxy Server detects no activity from a data source before establishing a dedicated connection.
$ dpconf set-ldap-data-source-prop -h host -p port datasource \ monitoring-inactivity-timeout:time |
By default, the inactivity timeout is 120 seconds.
Configure an alert to be sent when a data source is detected as offline or online, as described in Configuring Administrative Alerts for Directory Proxy Server.
In this type of monitoring, Directory Proxy Server performs a search on each connection to each data source at a regular interval. In this way, Directory Proxy Server detects closed connections and prevents connections from being dropped because of inactivity.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Set the monitoring mode for the data source to proactive.
$ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-mode:proactive |
Configure the monitoring search request that is performed by Directory Proxy Server.
$ dpconf set-ldap-data-source-prop -h host -p port datasource \ monitoring-bind-timeout:timeout monitoring-entry-dn:dn \ monitoring-search-filter:filter monitoring-entry-timeout:timeout |
The following properties are used in the search request:
The length of time that Directory Proxy Server waits to establish a connection to the data source. By default, the value of this property is 5 seconds.
The DN of the target entry in the search request. By default, this property is the root DSE entry ("").
The search filter.
The length of time that Directory Proxy Server waits for the search response. By default, the value of this property is 5 seconds.
Set the polling interval.
$ dpconf set-ldap-data-source-prop -h host -p port datasource monitoring-interval:interval |
If a connection is down, Directory Proxy Server polls the connection at this interval to detect its recovery. By default, the monitoring interval is 30 seconds.
Configure an alert to be sent when a data source is detected as offline or online, as described in Configuring Administrative Alerts for Directory Proxy Server.
For information about how to configure administrative alerts, see the following procedures.
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
View the enabled alerts.
% dpconf get-server-prop -h host -p port enabled-admin-alerts |
Enable one or more administrative alerts.
% dpconf set-server-prop -h host -p port enabled-admin-alerts:alert1 \ [enabled-admin-alerts:alert2 ...] |
For example, to enable all available alerts, run this command:
% dpconf set-server-prop -h host -p port \ enabled-admin-alerts:error-configuration-reload-failure-with-impact \ enabled-admin-alerts:error-server-shutdown-abrupt \ enabled-admin-alerts:info-configuration-reload \ enabled-admin-alerts:info-data-source-available \ enabled-admin-alerts:info-server-shutdown-clean \ enabled-admin-alerts:info-server-startup \ enabled-admin-alerts:warning-configuration-reload-failure-no-impact \ enabled-admin-alerts:warning-data-source-unavailable \ enabled-admin-alerts:warning-data-sources-inconsistent \ enabled-admin-alerts:warning-listener-unavailable |
To disable all alerts, run this command:
% dpconf set-server-prop -h host -p port enabled-admin-alerts:none |
To add an alert to an existing list of enabled alerts, run this command:
% dpconf set-server-prop -h host -p port enabled-admin-alerts+:alert-name |
To remove an alert from an existing list of enabled alerts, run this command:
% dpconf set-server-prop -h host -p port enabled-admin-alerts-:alert-name |
By default, no alerts are enabled.
For more information, see enabled-admin-alerts(5dpconf).
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Select the alerts that will be sent to the syslog daemon, as described in To Enable Administrative Alerts.
Enable alerts to be sent to the syslog daemon.
$ dpconf set-server-prop -h host -p port syslog-alerts-enabled:true |
All alerts are sent to the syslog with the facility of USER.
Set the host name of the syslog daemon to which alerts are to be sent.
$ dpconf set-server-prop -h host -p port syslog_hostname:hostname |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Select the alerts that will be sent to the syslog, as described in To Enable Administrative Alerts.
Configure the address and characteristics of the email.
$ dpconf set-server-prop -h host -p port email-alerts-smtp-host:host-name \ email-alerts-smtp-port:port-number \ email-alerts-message-from-address:sender-email-address \ email-alerts-message-to-address:receiver-email-address \ [email-alerts-message-to-address:receiver-email-address ...] \ email-alerts-message-subject:email-subject |
Enable alerts to be sent to email.
$ dpconf set-server-prop -h host -p port email-alerts-enabled:true |
(Optional) Set a flag to include the alert code in the email
$ dpconf set-server-prop -h host -p port \ email-alerts-message-subject-includes-alert-code:true |
You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.
Select the alerts that will be sent to the syslog, as described in To Enable Administrative Alerts.
Enable alerts to run a script.
$ dpconf set-server-prop -h host -p port scriptable-alerts-enabled:true |
Set the name of the script that will be run.
$ dpconf set-server-prop -h host -p port scriptable-alerts-command:script-name |
Directory Proxy Server runs inside a Java Virtual Machine (JVM) and depends on the memory of the JVM machine. To ensure that Directory Proxy Server is running correctly, you must monitor the memory consumption of the JVM machine.
For information about how to tune parameters for the JVM machine, see Hardware Sizing For Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.
By default, the heap size of the JVM machine is 250 Mbytes. If Directory Proxy Server does not have enough physical memory, the heap size might be less than 250 Mbytes.
When Directory Proxy Server is running, you can monitor the heap size of the JVM machine to ensure that it is not running out of memory. To do this, use the standard tools delivered with the Java Development Kit (JDK). These tools are located in these directories: $JAVA_HOME/bin/jps and $JAVA_HOME/bin/jstat.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
You cannot use DSCC to perform this task. Use the command line, as described in this procedure.
View the PID of your instance of Directory Proxy Server.
$ jps |
View the memory used by the JVM machine.
$ jstat -gcutil PID |
If the zero column is near to 100%, the JVM machine does not have enough memory.
FGC is the number of full garbage collection (GC) events. Garbage collection is expansive.
GCT (garbage collection time) is the amount of time spent by the GC.