The following sections discuss Directory Proxy Server 6.3.1 update 1:
Installation Notes for Directory Proxy Server 6.3.1 Update 1
Known Problems and Limitations in Directory Proxy Server 6.3.1 Update 1
This patch corrects issues only in the Directory Proxy Server component of the Directory Server Enterprise Edition product. It is designed to be applied on top of Directory Server Enterprise Edition 6.3.1. The Directory Server component of Directory Server Enterprise Edition 6.3.1 remains unchanged.
This update cannot be applied to versions of Directory Server Enterprise Edition earlier than 6.3.1. For directions to upgrade to version 6.3.1, see Table 2–1, “Upgrade Paths to Directory Server Enterprise Edition 6.3.1.”
This section discusses the following subjects:
This update is a minor release that primarily fixes the bugs described in Bugs Fixed in Directory Proxy Server 6.3.1 Update 1.
Directory Proxy Server 6.3.1 update 1 also introduces new behavior in persistent search operations. If a client application is very slow in reading the persistent search responses from the directory proxy server, the proxy server response queue becomes overloaded. In this case, the server can close the connection with the following client notification:
LDAP_NOTICE_OF_DISCONNECTION [ 1.3.6.1.4.1.1466.20036 ] |
An informative message similar to the following is also logged:
[11/Aug/2009:18:13:51 +0200] - DISCONNECT - INFO - conn=19 \ reason="admin limit exceeded" \ msg="client didn't read any data during 160 milliseconds." |
Directory Proxy Server 6.3.1 update 1 provides the following enhancements:
A pathname can be set for JAVA_HOME and take precedence over the value of JAVA_HOME defined in the environment, as shown in the following example:
$ dpadm set-flags instance-path jvm-path=/usr/jdk/latest/ |
The dpadm command changes the umask value, and at the next restart of the DPS instance, the configuration file's permissions are modified according with the new umask value. The log file's permission is also set similarly at the next file rotation. The following example shows a typical use:
$ dpadm set-flags instance-path umask=22 |
An administrator is now allowed to define different virtual transformations on the same MODEL, ACTION, ATTR_NAME.
Directory Proxy Server 6.3.1 update 1 also adds new properties and updates existing properties, as described in the following list. New properties are noted as “New.” Properties that are changed from their specification in DSEE 6.3.1 are noted as “Updated.”
Dynamic (no restart required)
Level: connection-handler
Type: boolean
Default: false
Description: Indicates whether the connection handler should close the client connection when no data source is available.
Dynamic (no restart required)
Level: connection-handler
Type: boolean
Default: false
Description: Indicates the need to not always use incoming client identity at binding to a remote LDAP server.
Documentation: This property is a flag indicating the need to not always use incoming client identity at binding to a remote LDAP server.
Dynamic (no restart required)
Level: jdbc-data-source
Type: enumeration
RDBMS back-end is MySQL.
RDBMS back-end is Apache Derby/Java DB.
RDBMS back-end is DB2.
RDBMS back-end is Oracle.
RDBMS back-end is Microsoft SQL Server.
RDBMS back-end is not defined. If possible, Directory Proxy Server determines the vendor name from the db-url defined in jdbc-data-source.
Default: generic
Description: Vendor name of the JDBC data source
Documentation: This property specifies the vendor name of the JDBC data source. This should be set if a third party IDBC driver other than the one provided by the database vendor is used to connect to the RDBMS back-end. This data is used to construct vendor-specific SQL statements when possible that might improve performance.
Dynamic (no restart required)
Level: jdbc-data-view, join-data-view, ldap-data-view, and ldif-data-view
New type: long
Old type (for DPS 6.0 to 6.3.1): integer
The other attributes remain the same as before.
Dynamic (no restart required)
Level: jdbc-data-view, join-data-view, ldap-data-view, and ldif-data-view
New type: long
Old type (for DPS 6.0 to 6.3.1): integer
The other attributes remain the same as before.
Static (restart required)
Level: ldap-data-source
Type: duration in seconds (lower bound: 1)
Default: inherited (value of monitoring-interval)
Description: Interval at which availability monitor polls failed connections to detect their recovery
Documentation: This property specifies the polling interval. When a connection is found to be down, the availability monitor polls the connection at this interval to detect its recovery. If not specified, the value of the monitoring-interval property is used.
Static (restart required)
Level: ldap-data-source
Type: integer (lower limit: 1)
Default: 3
Description: Number of retries to perform before flagging the connection as down
Documentation: This property specifies the number of times that the availability monitor polls the connection when it is first detected as down. This allows the connection to be flagged as up faster. If the connection still fails after the specified number of retries, the value of the down-monitor-interval property is then used as the polling interval.
Dynamic (no restart required)
Level: ldap-data-source
Type: boolean
Default: true
Description: Specifies whether SO_KEEPALIVE is enabled for connections between the server and the data source
Documentation: This property is a flag indicating whether or not SO_KEEPALIVE should be enabled for connections between the server and the data source.
Dynamic (no restart required)
Level: ldap-listener and ldaps-listener
Type: boolean
Default: true
Description: Specifies whether SO_KEEPALIVE is enabled for connections between clients and listener
Documentation: This property is a flag indicating whether or not SO_KEEPALIVE should be enabled for connections between clients and listener.
Dynamic (no restart required)
Level: server
Type: boolean
Default: true
New description: Indicates whether the server accepts unauthenticated operations
Old description (for DPS 6.0 to DPS 6.3.1): Indicates whether the server accepts operations from anonymous clients
New documentation: This property is a flag indicating whether or not Directory Proxy Server accepts unauthenticated operations. The mode used to tread the bind operation is specified by allow-unauthenticated-operations-mode
Old documentation (for DPS 6.0 to DPS 6.3.1): This property is a flag indicating whether or not Directory Proxy Server allows anonymous clients to perform operations.
Dynamic (no restart required)
Level: server
Type: enumeration
When no password is specified, only anonymous binds are allowed
When no password is specified, only binds with a DN specified are allowed
When no password is specified, anonymous binds and binds with a DN specified are allowed
Default: anonymous-and-dn-identified
Description: Mode to treat bind operations without password
Documentation: This property indicates how to Directory Proxy Server treats operations without bind password when allow-unauthenticated-operations is set to true.
Static (restart required)
Level: server
Type: duration in milliseconds
New default: 250
Old default (for DPS 6.0 to 6.3.1): 500
New documentation: This property specifies the time interval between consecutive system calls that retrieve time from the OS. For details about operations that take less than 250 milliseconds, reduce the time-resolution period or change the value of the time-resolution-mode property. If set to 0 milliseconds, the proxy behaves as if the value of the time-resolution-mode property was set to system-milli. This property is ignored when the value of the time-resolution-mode property is set to system-milli or system-micro.
Old documentation (for DPS 6.0 to 6.3.1): This property specifies the time interval between consecutive system calls that retrieve time from the OS. For details about operations that take less than 500 milliseconds, reduce the time-resolution period. If set to 0 milliseconds, the proxy systematically performs a system call to retrieve the current time. Otherwise the time is cached and retrieved only every time-resolution period. This time is displayed in the logs.
The description remains the same as before.
Static (restart required)
Level: server
Type: enumeration
Use a thread performing a system call every time-resolution milliseconds
Use a system call retrieving time in milliseconds
Use a system call retrieving time in microseconds
Default: custom-resolution
Description: Mode used to retrieve system time
Documentation: This property specifies the mode used to retrieve time from the OS.
Directory Proxy Server 6.3.1 update 1 is available for all supported Directory Server Enterprise Edition 6.3.1 platforms. For more information, see Hardware Requirements and Operating System Requirements.
This section lists the bugs fixed in Directory Proxy Server 6.3.1 update 1.
Directory Proxy Server constructs illegal database requests.
Setting connectionIdleTimeOutInSec for LDAP listener can disable DSCC.
A search operation can return entries that contain attributes that are not present in viewable-attr.
The max-client-connections property is not enforced if no operation is performed on the connection.
Memory monitoring is disabled by default.
The numeric distribution algorithm should use long instead of int to set numeric bounds.
The Directory Proxy Server default size limit for resource properties uses the incorrect integer for unlimited.
DN transformations fail.
The setting of add-attr-value can cause DN transformations to produce incorrect output.
The bindDN should be mapped when binding to a LDAP server. (using DN mapping rule of the DV of the bindDN).
It is not possible to add a new virtual transformation with same "MODEL, ACTION, ATTR_NAME".
The requires-bind-password property set on a back-end directory server is not enforced.
Virtual DN mapping fails when depending on a virtual attribute.
Bind DN is rejected when transformation fails, even when it falls into the view.
Wrong DN mapping for the from server direction.
Upper/lowercase characters in attribute names are being transformed by 6.3 Directory Proxy Server.
A customer requested for Directory Proxy Server to set group permissions for config and log files (umask 117, chmod 660).
The dpadm start command dumps a core when using the MaxTenuringThreshold java argument.
DN mapping can drop renamed entries.
The dpadm does not generate a DPS.pid file.
Directory Proxy Server configuration schema are inconsistent with the SystemMonitorThread.java feature.
The server and console are inconsistent for searchMode parameter.
Directory Proxy Server fails when configured to use proxied authentication.
Allow for JAVA HOME to be set using dpadm set-flags.
DN mapping cannot be used on rootDSE.
Directory Proxy Server requires virtual DN transformation with multi-valued naming attributes.
Microseconds time granularity should be provided for etimes.
The splitldif command ignores virtual transformations.
Under heavy load, sockets can remain in the close wait state.
The SO_KEEPALIVE option is not set in Directory Proxy Server 6.3 (that is, setKeepAlive() != True) when a socket is created.
The fix for CR 6513526 can introduce regressions because of null values in ConfigAttribute objects.
The acceptBacklog property is ignored for channel-based listeners.
Inactivity heartbeats are not send often enough because of last activity on a backend connection.
Inactivity heartbeats are not sent for bound backend connections.
Backend server checks might not occur often enough because of last server activity.
The ldapsearch run on monitor entries can give inconsistent output.
An availability check should make sure that the backend server is down before cutting all connections.
A connection can become blocked in case of abandon request.
Better accuracy is required in the backend heart-beat.
A file descriptor leak occurs in server socket.
A null pointer exception can occur when searching on cn=monitor if a failover pool is defined with no source.
Directory Proxy Server continues opening connections to the directory server after an attempt to bind... fails.
Persistent search clients may not receive entry change notifications.
Two connections can share the same identifier.
Persistent searches are not cleaned up after client disconnect.
The proactive monitoring interval should be set to 1 second when a datasource is detected as down.
Directory Proxy Server associates different client operations with the same backend connection.
Backend connections are not closed but reused if idle is more than inactivity-timeout, causing a connection leak.
Connection pool housekeeping and health-check processing should be DEBUG.
Two simultaneous long binds assign the same backend connection to two clients connections.
Setting an incorrect jvm-path hangs the restart without any warning.
Directory Proxy Server returns the wrong error code when no back-end servers are available
An option should be provided to close client connection in case of "cannot retrieve backend connection".
Client affinity should not be enabled when useAffinity=false and affinityPolicy is explicitely set.
Directory Proxy Server cannot be started if one of the data source host is unreachable.
The dpconf command should support new attributes introduced in Directory Proxy Server 6.3.1_update 1.
The dpconf command should support bind DN mapping.
More simple versioning should be provided for management of Directory Proxy Server properties.
The dpconf should support monitorRetryCount.
Client affinity ignores the data source's read-only flag.
Implementation of fixes for CR 6714425 and 6714448 should be completed.
A lowercase join expression can cause SQL requests to fail.
Directory Proxy Server 6.3.1 performance is inadequate when more than 100 clients are performing persistent searches.
Persistent search thread looping and the Directory Proxy Server can no longer handle persistent searches
The performance of the persistent search is inadequate.
Creating 20 persistent searches and then stopping them causes persistent search functionality to fail.
Directory Proxy Server returns StringIndexOutOfBoundsException in certain cases of attribute mapping and virtual transformation.
The transformation and mapping rules do not perform as expected.
Threads can be released prematurely, producing an ASN.1 exception.
The Directory Proxy Server returns an incorrect error when the back end goes down.
An unexpected null pointer exception can be raised.
Under some circumstances, the password storage scheme can be ignored by the JDBC data view.
The Directory Proxy Server can return identical results when different users bind on a client connection.
Under some circumstances, the Directory Proxy Server can fail to start when using JDBC.
An unexpected ASN1 exception can occur and not be handled.
This discusses the following topics:
Directory Proxy Server 6.3.1 update 1 is a patch that is applied to an existing installation of Directory Server Enterprise Edition 6.3.1. If you are running Directory Server Enterprise Edition version earlier than 6.3.1, you must first upgrade to version 6.3.1 as described in Chapter 2, Installation Notes before applying the patch for Directory Proxy Server 6.3.1 update 1.
You can download the Directory Proxy Server 6.3.1 update 1 patch from http://www.sun.com/software/products/directory_srvr_ee/get.jsp.
Directory Proxy Server 6.3.1 update 1 is a unique patch for all the DSEE platforms:
Solaris SPARC
Solaris 9 x86
Solaris 10 x86 and AMD x64
Red Hat Linux
SuSe Linux
HP-UX
Windows
For each platform, the following distributions are available:
Native package distribution (except for HP-UX)
Zip distribution
Directory Proxy Server 6.3.1 update 1 patch 141958-01 is available through SunSolve and applies to both of the following kinds of installation:
Directory Server Enterprise Edition 6.3.1 native packages installed using the Java ES installer
Directory Server Enterprise Edition 6.3.1 zip installations
This section describes how to install the Directory Proxy Server 6.3.1 update 1.
Back up the Directory Server Enterprise Edition installation directory before applying the Directory Proxy Server 6.3.1 update 1 patch, because you cannot restore an earlier Directory Proxy Server configuration later. This advice applies to both Zip and Native Packages installations.
Download Patch 141958-01 from Sunsolve to a downloaded-patch-path directory.
Stop the Directory Proxy Server instances associated with the installation that you intend to patch.
On Windows systems, open a Command Prompt window. On UNIX systems, open a terminal window.
Change the current directory to the directory with installation software for the platform and distribution (zip or native) that you want to update:
The following example shows a typical command for this purpose:
$ cd downloaded-patch-path/SunOS_x64/zip/delivery |
The following table shows the locations of installation software under the downloaded-patch-path directory.
Operating System |
Directory Containing the Zip Delivery |
Directory Containing the Native Package Delivery |
---|---|---|
Solaris SPARC |
SunOS/zip/delivery |
SunOS/native/delivery |
Solaris 9 x86 |
SunOS_x86/zip/delivery |
SunOS_x86/native/delivery |
Solaris 10 x86 and AMD x64 |
SunOS_x64/zip/delivery |
SunOS_x64/native/delivery |
Red Hat Linux |
Linux/zip/delivery |
Linux/native/delivery |
SuSE Linux |
Linux/zip/delivery |
Linux/native/delivery |
HP-UX |
Hpux/zip/delivery |
N/A |
Windows |
Windows/zip/delivery |
Windows/native/delivery |
On UNIX systems, launch the installation script.
Run the following command:
$ Install dsee631-install-path |
where dsee631-install-path is the path to the directory where Directory Server Enterprise Edition 6.3.1 is installed.
The following messages appear:
-------------------------------------------------------------------- IMPORTANT : Make sure all the DPS instances associated with the Directory Proxy Server installation being patched are shutdown prior to apply the Directory Proxy Server 6.3.1 Update 1 Patch -------------------------------------------------------------------- Do you want to proceed with the installation (y/Y to proceed, n/N to abort) [n] ? |
Enter y for yes. The installation program applies the patch on the Directory Server Enterprise Edition 6.3.1 installation that you specified.
On Windows installations, run the following command in the Command Prompt window:
Install.exe |
A wizard opens and requests that you browse and select the correct installation path for installing the Directory Proxy Server 6.3.1 update 1 patch. To patch a 6.3.1 ZIP installation, select the directory where you installed Directory Server Enterprise Edition 6.3.1. To patch a Native Package installation, select C:\Program Files\Sun\JavaES5\DSEE.
The wizard applies the patch on Directory Server Enterprise Edition 6.3.1.
Confirm that the installation is successful by running these two commands and verifying that the response is the same as shown here:
$ dpadm -V [dpadm] dpadm : 6.3.1.1 B2009.1106.0156 ZIP [DPS] Sun Microsystems, Inc. Sun-Java(tm)-System-Directory-Proxy-Server/6.3.1.1 B2009.1106.0259 $ dpconf -V [dpconf] clip.jar : 6.3.1 B2008.1121.0155 dpcfg.jar : 6.3.1.1 B2009.1106.0155 dpcfgcli.jar : 6.3.1.1 B2009.1106.0155 common.jar : 6.3.1 B2008.1121.0155 common_cfg.jar : 6.3.1 B2008.1121.0155 |
This step is required if the Directory Server Enterprise Edition 6.3.1 that you are patching includes hot fix for CR 6722222.
If the hot fix for CR 6722222 (Map bindDN when binding to a LDAP server (using DN mapping rule of the DV of the bindDN)) has been applied, run the following command in all the instances for every connection handler:
$ dpconf set-connection-handler-prop -p port -h host connection handler \ data-view-use-internal-client-identity:true |
This property is a flag that indicates that it is not always required to use incoming client identity at binding to a remote LDAP server. After CR 6722222 is applied, the default behavior can now be configured with a connection handler property, as shown in the example.
Restart all proxy server instances.
This section lists the known problems and limitations that are found at the time of the Directory Proxy Server 6.3.1 update 1 release.
Known issues and limitations in Directory Proxy Server 6.3.1 persist even after the patch for Directory Proxy Server 6.3.1 update 1 is applied. Refer to Known Problems and Limitations in Directory Proxy Server for information about these issues.
This section lists the known limitation that is found at the time of the Directory Proxy Server 6.3.1 update 1 release.
As described in JDBC Object Classes in Sun Java System Directory Server Enterprise Edition 6.3 Reference, defining JDBC tables uses primary and secondary tables. Directory Proxy Server does not allow a secondary table to be the primary table of a third table. That is, Directory Proxy Server does not support more than one level of join-rule.
This section lists the known problems that are found at the time of the Directory Proxy Server 6.3.1 update 1 release.
In release 6.3, if an entry has more than two object classes, adding an entry through a join view (LDAP and JDBC) fails because of the fix for CR 6636463. To add such an entry, these object classes must be defined as a super-class in the jdbc-object-class configuration entry by the following ldapmodify, because dpconf set-jdbc-object-class-prop can add only one super-class.
This example adds the following entry:
dn: uid=test,ou=people,o=join sn: User cn: Test User objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson uid: test userpassword: password givenname: Test mail: test@example.com telephonenumber: 8888-8888 roomnumber: 8000
The JDBC view is defined as shown in the following example, which was functional before release 6.3.
dn: cn=person,cn=example-view,cn=data views,cn=config secondaryTable: country1 secondaryTable: phone1 primaryTable: employee1 objectClass: top objectClass: configEntry objectClass: jdbcObjectClassMapping dnPattern: uid cn: person superclass: top
Because objectClass:organizationalPerson and objectClass:inetOrgPerson both exist in the entry being added, it is necessary to specify both object classes as super classes, as demonstrated by following ldapmodify command.
$ ldapmodify -p dpsPort -D "cn=Proxy manager" -w password dn: cn=person,cn=example-view,cn=data views,cn=config changetype: modify add: superClass superClass: inetOrgPerson - add: superClass superClass: organizationalPerson |
After this ldapmodify example runs, jdbc-object-class is defined as shown in the following example.
dn: cn=person,cn=example-view,cn=data views,cn=config secondaryTable: country1 secondaryTable: phone1 primaryTable: employee1 objectClass: top objectClass: configEntry objectClass: jdbcObjectClassMapping dnPattern: uid cn: person superclass: top superclass: inetOrgPerson Added superclass: organizationalPerson Added
Although the default setting for the log-level-data-sources-detailed property is documented as being none, the actual default value is all. However, setting log-level-data-sources-detailedto any value other than none impacts server performance and makes the access file grow quickly. For that reason, the value of the log-level-data-sources-detailed setting is automatically set to none when a DPS server instances is created. It is recommended that you not set this setting to some other value.
Because of a problem described in Vulnerability Note VU#836068, MD5 vulnerable to collision attacks, Directory Proxy Server should avoid using the MD5 algorithm in signed certificates.
Use the following steps to determine the signature algorithm of a certificate.
Run the following command to display the list of certificates defined in a specific Directory Proxy Server instance:
$ dpadm list-certs instance-path |
Run the following commands on each defined certificate to determine whether the certificate is signed with the MD5 algorithm:
$ dpadm show-cert -F ascii -o cert-output-file \ dps-instance-path cert-alias $ dsadm add-cert ds-instance-path cert-alias \ cert-output-file $ dsadm show-cert ds-instance-path cert-alias |
The following example shows typical output from the dsadm show-cert command for a certificate signed with the MD5 signature algorithm:
Certificate: Data: ... Signature Algorithm: PKCS #1 MD5 With RSA Encryption ... |
Run the following command to remove any MD5–signed certificates from the database:
$ dsadm remove-cert instance-path cert-alias |
Use the following steps to update the certificate database password. (The dpadm command generates a default certificate database password when creating a directory proxy server instance.)
Stop the Directory Proxy Server instance.
Run the following command:
$ dpadm set-flags instance-path cert-pwd-prompt=on |
A message appears, prompting you for a password.
Enter a password that is at least eight characters long.
Restart the Directory Proxy Server instance and provide the Internal (Software) Token when prompted for it.
Replace any certificates using the MD5 function with certificates that use the SHA-1 signature algorithm. Use one of the following procedures, depending on whether your installation uses a self-signed certificate or a certificate acquired from a Certificate Authority.
Use the following steps to generate and store a self-signed certificate:
Run the following command:
$ dpadm add-selfsign-cert --sigalg SHA1withRSA \ dps-instance-path cert-alias |
The default signature algorithm is MD5withRSA.
The following prompt appears:
[Password or Pin for "NSS Certificate DB"] |
Enter the new certificate database password.
Use the following steps to generate and store a certificate acquired from a Certificate Authority (CA):
Run the following command to issue a CA-Signed Server Certificate request:
$ dpadm request-cert --sigalg SHA1withRSA instance-path cert-alias |
Make sure that your Certificate Authority is no longer using the MD5 signature algorithm, and then send the certificate request to the Certificate Authority (either internal to your company or external, depending on your rules) to receive a CA-signed server certificate as described in To Request a CA-Signed Server Certificate in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.
When the Certificate Authority sends you the new certificate, run the following command to add the certificate to the certificates database:
$ dpadm add-cert instance-path cert-alias |
This step is described in Creating, Requesting and Installing Certificates for Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.
If the trusted Certificate Authority certificate is not already stored in the certificate database, run the following command to add it:
$ dpadm add-cert --ca instance-path trusted-cert-alias |
This step is described in Creating, Requesting and Installing Certificates for Directory Proxy Server in Sun Java System Directory Server Enterprise Edition 6.3 Administration Guide.
Run the following commands to verify that the new certificate is being used.
$ dpadm show-cert -F ascii -o cert-output-file \ dps-instance-path cert-alias $ dsadm add-cert ds-instance-path cert-alias \ cert-output-file $ dsadm show-cert ds-instance-path cert-alias |
With a Microsoft SQL Server back end, when using smalldate fields, only the long version of dates are supported, or else a conversion error occurs, as shown in the following example.
ldap_modify: Operations error ldap_modify: additional info: java.lang.Exception: \ com.microsoft.sqlserver.jdbc.SQLServerException: \ Conversion failed when converting datetime from character string. |
The long version of a date uses the form YYYY-MM-DD HH:MM.