Notes covering OpenDJ hardware & software requirements, fixes, known issues. The OpenDJ project offers open source LDAP directory services in Java.
OpenDJ is an LDAPv3 compliant directory service, developed for the Java platform, providing a high performance, highly available, and secure store for the identities managed by your organization. Its easy installation process, combined with the power of the Java platform makes OpenDJ the simplest, fastest directory to deploy and manage. OpenDJ directory server comes with plenty of tools and a full-featured LDAP SDK for Java. OpenDJ directory server also offers REST access to directory data over HTTP.
OpenDJ is free to download, evaluate, and use in developing your applications and solutions. You can also check out and modify the source code to build your own version if you prefer. ForgeRock offers training and support subscriptions to help you get the most out of your deployment.
These release notes are written for everyone working with the OpenDJ 4.8.1-SNAPSHOT release. Read these notes before you install or upgrade OpenDJ software. These notes cover hardware and software prerequisites for installing and upgrading OpenDJ software. These notes list key features added and changed in this release. They also cover compatibility with previous releases and alert you to potential changes coming up that could affect your scripts and applications. Finally, these notes list both issues fixed since the previous release and known issues open at the time of release.
See the Installation Guide for more after you read these release notes. The installation guide covers installation and upgrade for OpenDJ directory server, OpenDJ REST LDAP gateway, and OpenDJ DSML gateway.
OpenDJ 4.8.1-SNAPSHOT is a maintenance release that resolves a number of issues, including security issues in OpenDJ directory server. It is strongly recommended that you update to this release to make your deployment more secure, and to take advantage of important functional fixes. ForgeRock customers can contact support for help and further information.
Before you install OpenDJ or update your existing OpenDJ installation, read these release notes. Then update or install OpenDJ.
A security vulnerability has been discovered in OpenDJ. This issue is present in all versions of OpenDJ including 2.6.x, 2.5.0-Xpress1, 2.4.x, and possibly previous versions.
A security advisory has been issued to provide guidance on how to ensure your deployments can be secured. Workarounds or patches are available for the issue, with fixes included in OpenDJ 2.6.3.
The severity of the issue in the advisory is High. Deployers should take immediate steps as outlined in the advisory and apply the relevant update at the earliest opportunity.
The recommendation is to deploy the relevant patch or to upgrade to OpenDJ 2.6.3.
Customers without existing patches can obtain the relevant patch from BackStage. Customers with deployed patches should contact the support organization to obtain a combo patch. The fix is also present in the community "trunk" nightly builds.
The following security fix has been included in this release:
Issue #201504-01: Proxied Authorization may allow unexpected escalation of privileges and access. When someone has been granted the privileges to Proxy requests and use the Proxied Authorization control, it is not possible to control who that user can impersonate. It is thus possible to impersonate "cn=Directory Manager" and bypass all access controls.
Severity: High
For more information, see OpenDJ Security Advisory #201504.
Compared to the OpenDJ ${stableServerVersion} release, OpenDJ 4.8.1-SNAPSHOT provides these important enhancements.
OpenDJ 4.8.1-SNAPSHOT includes no new enhancements beyond those included in OpenDJ 2.6.2.
The following improvement is new in OpenDJ 2.6.2.
OpenDJ server can now bind to a local address when making outgoing connections (OPENDJ-1565).
This improvement introduces a new configuration attribute,
source-address,
that you can set for Replication Domains, Replication Servers,
and LDAP Pass Through Authentication Policies.
If the source-address property is set to an IP address,
OpenDJ binds to the address before connecting to the remote server.
The address must be one assigned to an existing network interface.
The following improvements are new in OpenDJ 2.6.1.
OpenDJ directory server ships with updated Commons REST, OpenDJ LDAP SDK, and Berkeley DB Java Edition components (OPENDJ-1323).
OpenDJ directory server now makes it possible to specify password validators in subentry based password policies (OPENDJ-1295).
To configure password validators for a subentry password policy,
add the auxiliary object class pwdValidatorPolicy
and setting the multi-valued attribute,
ds-cfg-password-validator,
to the DNs of the password validator configuration entries.
OpenDJ directory server now orders attributes according to search request attribute list order (OPENDJ-1082).
OpenDJ directory server logs information to help you more effectively determine why a directory server replica switches its connection to a different replication server (OPENDJ-1053).
The REST LDAP Gateway now supports LDAPS connections and StartTLS (OPENDJ-1033).
For information on configuring the gateway to use LDAPS or StartTLS,
see the comments in the configuration file,
opendj-rest2ldap-servlet.json.
Find the settings to change in the configuration for
"ldapConnectionFactories".
You can read the following additional product documentation for OpenDJ 2.6 online at ForgeRock BackStage.
This chapter has not changed since the release of OpenDJ 2.6.2.
This chapter covers requirements to consider before you run OpenDJ, especially before you run OpenDJ in your production environment.
OpenDJ 2.6.2 adds support for Java 8.
If you have a special request to support a combination not listed here, contact ForgeRock at info@forgerock.com.
OpenDJ software consists of pure Java applications. OpenDJ servers and clients therefore should run on any system with full Java support. OpenDJ is tested on a variety of operating systems, including Solaris SPARC and x86, various Linux distributions, Microsoft Windows, and Apple Mac OS X.
OpenDJ software requires Java 6, 7 or 8, specifically at least the Java Standard Edition runtime environment. ForgeRock has tested most with Oracle Java Platform, Standard Edition.
ForgeRock recommends that you keep your Java installation up to date with the latest security fixes.
To build applications with the OpenDJ LDAP SDK, you need the corresponding Java SDK.
OpenDJ needs to be able to open many files, especially when handling many client connections. Linux systems in particular often set a limit of 1024 per user, which is too low for OpenDJ.
When setting up OpenDJ for production use, make sure OpenDJ can use
at least use at least 64K (65536) file descriptors. For example when running
OpenDJ as user opendj on a Linux system that uses
/etc/security/limits.conf to set user level limits,
you can set soft and hard limits by adding these lines to the file.
opendj soft nofile 65536 opendj hard nofile 131072
The example above assumes the system has enough file descriptors available overall. You can check the Linux system overall maximum as follows.
$ cat /proc/sys/fs/file-max 204252
OpenDJ software depends on the Java environment more than it depends on the underlying operating system. That said, OpenDJ 4.8.1-SNAPSHOT has been validated on the following operating systems.
Apple Mac OS X 10.7, 10.8
Linux 2.6 and later
Microsoft Windows Server 2008 R2 and Windows Server 2012
Oracle Solaris 11 x86
In order to avoid directory database file corruption after crashes or power failures on Linux systems, enable file system write barriers and make sure that the file system journaling mode is ordered. For details on how to enable write barriers and how to set the journaling mode for data, see the options for your file system in the mount command manual page.
ForgeRock has tested OpenDJ software on systems running atop VMware vSphere Hypervisor (ESXi) 5.1.
OpenDJ directory server runs as a standalone Java service, and does not depend on an application server.
OpenDJ DSML gateway has been validated on Apache Tomcat 6 and 7.
OpenDJ REST LDAP gateway has been validated on Apache Tomcat 6 and Jetty 8. Using Jetty 8 is not supported with Java 8.
OpenDJ replication requires that you use fully qualified domain names,
such as opendj.example.com.
Although you can use host names like my-laptop.local
for evaluation, in production and even in your lab, you must either ensure
DNS is set up correctly to provide fully qualified domain names, or set up
/etc/hosts (or
C:\Windows\System32\drivers\etc\hosts) to provide
fully qualified domain names.
Thanks to the underlying Java platform, OpenDJ software runs well on a variety of processor architectures. Many directory service deployments meet their service-level agreements without the very latest or very fastest hardware.
For a server evaluation installation, you need 256 MB memory (32-bit) or 1 GB memory (64-bit) available to OpenDJ, with 100 MB free disk space for the software and a small set of sample data. For installation in production, read the rest of this section. You need at least 2 GB memory for OpenDJ and 4 times the disk space needed to house initial production data in LDIF format.[1] To get a more accurate estimate of the disk space needed, import a known fraction of the initial LDIF with OpenDJ configured as for production, run tests based on the estimated rates of change and growth in directory data, and then use the actual space used in the test environment to estimate how much disk space you need in production.
OpenDJ directory servers almost always benefit from having enough system memory to cache all directory database files used. The reason is that reading from and writing to memory is typically much faster than reading from and writing to disk storage. For small data sets, you might not need extra memory. For large directories with millions of user directory entries, the system might not have enough slots to house sufficient memory to cache everything. To improve performance in such cases, one approach is to add solid state drives as an intermediate cache between memory and disk storage.
Processor architectures that provide fast single thread execution tend to help OpenDJ software deliver the lowest response times. For top end performance in terms both of sub-millisecond response times and also of throughput ranging from tens of thousands to hundreds of thousands of operations per second, the latest x86/x64 architecture chips tend to perform better than others tested. Chip multi-threading (CMT) processors can do very well on directory servers providing pure search throughput, even though response times can be higher. Yet, CMT processors can be slow to absorb hundreds or thousands of write operations per second. Their slower threads get blocked waiting on resources, and thus are not optimal for topologies with high write throughput requirements.
On systems with fast processors and enough memory to cache directory data completely, the network can become a bottleneck. Even if a single 1 Gbit Ethernet interface offers plenty of bandwidth to handle your average traffic load, it can be too small for peak traffic loads. Furthermore, you might choose to use separate interfaces for administrative traffic and application traffic. To estimate what network hardware you need, calculate the size of the data you return to applications during peak load. For example, if you expect to have a peak load of 100,000 searches per second, each returning a full 8 KB entry, you need a network that can handle 800 MB/sec (3.2 Gbit/sec) throughput, not counting any other operations such as writes that result in replication traffic.
The storage hardware you choose must allow you to house not only directory data including historical data for replication, but also logs. If you choose to retain access logs for auditing purposes on a heavily used directory, dedicate storage for the log archives as well. Furthermore, your storage must also keep pace with the write throughput. Write throughput can arise from modify, modify DN, add, and delete operations, but it can also result from bind operations. Such is the case when the last successful bind is recorded, and when account lockout is configured, for example. In a replicated topology, not only does a directory service write entries to disk when they are changed, but a directory service also writes changelog data and historical information in order to resolve potential replication conflicts. You base your network throughput needs on peak loads. Also base your storage throughput needs on peak loads.
OpenDJ servers do not currently support network file systems such as NFS for database storage. Provide sufficient disk space on local storage such as internal disk or an attached disk array.
[1] OpenDJ stores data in Berkeley DB Java Edition, which is implemented as a rolling log. Berkeley DB appends updates to the end of the last log file, and marks old pages as deleted. Berkeley DB cleaner threads monitor the log file occupancy ratio, moving the data to get rid of old log files. Yet, with the default occupancy ratio of 50%, log files are cleaned only when they have less than 50% valid pages. As a result, the database can reach twice its initial size in the worst case.
Furthermore, when you import data from LDIF, OpenDJ stores not only the data, but also builds indexes for many of the attributes, resulting in some growth. Replication historical data and other operational attributes can also take up space.
Finally, it makes sense to leave space for growth in the database size as you modify and add entries over time.
ForgeRock recommends that you update OpenDJ ${stableServerVersion} installations to this release. If you are installing OpenDJ for the first time, you can use the same installation instructions as for ${stableServerVersion}.
Download and unpack OpenDJ 4.8.1-SNAPSHOT software.
Find a link to the OpenDJ download page from backstage.forgerock.com.
Follow the instructions in the chapter on Upgrading to OpenDJ ${stableServerVersion} in the Installation Guide.
When upgrading from OpenDJ 2.5.0-Xpress1,
you no longer need to rebuild the ds-sync-hist index
as a separate step.
Download and unpack OpenDJ 4.8.1-SNAPSHOT software.
Find a link to the OpenDJ download page from backstage.forgerock.com.
Follow the instructions in the OpenDJ ${stableServerVersion} Installation Guide.
This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.
No incompatible changes have been made since OpenDJ ${stableServerVersion}. This chapter reflects changes made in version ${stableServerVersion}.
OpenDJ improves on earlier releases introducing many new features. Also take the following into account.
The upgrade process and upgrade command have changed to facilitate native packaging on more platforms. See Upgrading to OpenDJ ${stableServerVersion} for instructions.
The default DB cache size is now 50%, rather than 10%.
If you have multiple backends, configure cache sizes accordingly.
The number of LDAP request handlers now defaults to half the CPU count.
The replication purge delay default has increased from one day to three days.
Syntax checking has been added for certificate and country attribute
values. This affects applications updating those attribute values.
Applications updating country attribute values must now use Country String
syntax for example, which uses two-character codes from ISO
3166 such as US instead of full names such as
United States.
The following global ACI settings have changed.
OpenDJ directory server now allows any client to use the LDAP
Permissive Modify Request control, 1.2.840.113556.1.4.1413,
by default for newly installed servers.
The "Anonymous read access" global ACI has changed. The list of
attributes that are not allowed has been changed to add
includedAttributes and to remove
targetUniqueID.
When you upgrade from earlier versions of OpenDJ, however, the
previous global-aci settings are not updated. To apply
the changes manually, change the relevant global-aci
settings by using the dsconfig command. An example of
how to change a global-aci property can be found in the
Administration Guide, ACI: Disable Anonymous Access.
For the SNMP Connection Handler, the default
security-agent-file has changed to
opendj-snmp.security (OPENDJ-982), and the upgrade process changes the file name. The
community has also changed to OpenDJ.
If the SNMP Connection Handler fails to start after upgrade, use the
dsconfig command to make sure that the
security-agent-file property is correctly set for your
installation.
Support for Java 6 is deprecated and likely to be removed in a future release.
OpenDJ ${stableServerVersion} makes use of new environment
variables aligned with the project name to use OPENDJ.
Use of the old variables is Deprecated. The old variables are likely to be
removed in a future release.
The dsframework command is Deprecated and likely to be removed in a future release.
The next major version of OpenDJ LDAP SDK includes improvements and changes that are not compatible with the 2.x SDK.
Native packages in SVR4 format for Solaris are not provided at this time.
This chapter covers the status of key issues and limitations for OpenDJ 4.8.1-SNAPSHOT and OpenDJ SDK 4.8.1-SNAPSHOT. For details and information on other issues, see the OpenDJ issue tracker.
OpenDJ 2.6.0 and later maintenance releases include important improvements to replication. Replication remains fully compatible with earlier versions. However, some operations that work fine with the current OpenDJ release, such as replicating large groups and replicating high volumes of adds and deletes, can cause issues for earlier versions. Make sure you upgrade all servers to this version before allowing clients to take advantage of write operations that could cause trouble for older servers.
The following important bugs were fixed in this release.
OPENDJ-2157: Backport OPENDJ-2152: ldapsearch ignores ldapsearch.useSSL=true in a tools.properties
OPENDJ-1951: Backport OPENDJ-1915 DSMLServlet is not thread-safe
OPENDJ-1947: Backport OPENDJ-1605: Schema is incorrect for ds-base-dn-entry-count attribute used in monitor backend
OPENDJ-1892: Backport OPENDJ-1842: Using SSL with JMX doesn't work
OPENDJ-1890: Backport OPENDJ-1882: currentConnections from cn=monitor is not decremented when JMX connections close
OPENDJ-1764: admin-backend.ldif can end up empty
OPENDJ-1665: performBackendInitializationProcessing takes a very long time when backup.info contains lots of entries
OPENDJ-1610: original password is not put into the password history when reset the password without specify the new password
OPENDJ-1375: Subtree delete control can wait forever for an id2subtree lock
Release 4.8.1-SNAPSHOT has the following limitations, none of which are new since .
OpenDJ directory server provides full LDAP v3 support, except for alias dereferencing, and limited support for LDAPv2.
When you configure account lockout as part of password policy, OpenDJ locks an account after the specified number of consecutive authentication failures. Account lockout is not transactional across a replication topology, however. Global account lockout occurs as soon as the authentication failure times have been replicated.
OpenDJ is not fully integrated with Microsoft Windows, yet OpenDJ directory server can be run as a service, and thus displayed in the Windows Services Control Panel.
OpenDJ replication is designed to permit an unlimited number of replication servers in your topology. Project testing has, however, focused only on topologies of up to eight replication servers.
OpenDJ plugin extensions must follow the guidelines set forth in
the README file delivered in
opendj/example-plugin.zip. When developing your
extension, aim to remain loosely coupled with any particular version of
OpenDJ. Libraries used must be installed in
opendj/lib/extensions/ (or bundle them in your
.jar). Keep your configuration separate from the server configuration.
Also, unless you are reusing standard schema definitions, keep your
schema definitions separate as well.
This can affect how your extension works after upgrade. In
particular opendj-accountchange-handler-1.0.0 does
not work with OpenDJ 2.6.0 after upgrade (OPENDJ-991). See that issue for notes on how make that version
of the extension work with OpenDJ 2.6.0.
When deploying for production, make sure that you follow the installation instructions on allowing OpenDJ to use at least 64K (65536) file descriptors, and on tuning the JVM appropriately.
The following important issues remained open at the time this release became available.
OPENDJ-1969: IdleTimeLimitThread fails with null ConnectionHandlers or null ClientConnections
OPENDJ-1968: NPE in GoverningStructureRuleVirtualAttributeProvider if entry has no structural object classes
OPENDJ-1829: JMX connector listens on a random port number
OPENDJ-1586: Nested Groups fail to return indirect members with db's larger than 10 entries
OPENDJ-1431: Trimming of draftcndb gets stuck, changelog keeps growing in size
OPENDJ-1366: Arguments logged in wrong order for ERROR_REPLAYING_OPERATION
OPENDJ-1325: An error occurred while attempting to perform index rebuild: The database environment could not be opened: (JE 5.0.73)
OPENDJ-1309: First dsreplication enable could warn before replicating schema
OPENDJ-1294: ldappasswordmodify -D <DN> -w - fails without prompting password from stdin
OPENDJ-1290: Nested backends handles hasSubordinates attribute incorrectly
OPENDJ-1239: dsreplication logs warnings for each replication server under cn=monitor
OPENDJ-1213: LDIFReader should reject LDIF that contains trailing space
OPENDJ-1189: Integer overflow while sizing scratch files building indexes
OPENDJ-1172: Deadlock between replication threads during shutdown.
OPENDJ-1169: Exception/error lost when logging ERR_LOOP_REPLAYING_OPERATION
OPENDJ-1158: rebuild-index leaves backend offline if a backup is running
OPENDJ-1151: OpenDJ unable to initialize the SSL context an doesn't start
OPENDJ-1138: searchrate throws java.lang.IndexOutOfBoundsException
OPENDJ-1131: Rest2LDAP fails to start with GlassFish3.1
OPENDJ-1094: ECL virtual lastChangeNumber attribute can decrement
OPENDJ-1087: OpenDJ Console: Validation checks missing
OPENDJ-1056: secure listener should not be created if proper keying material is not available for some reason
OPENDJ-1051: Upgrade: add task to update lastChangeNumber/firstChangeNumber attributes definition when upgrading from 2.4.x
OPENDJ-1043: Worker Thread was interrupted while waiting for new work while shutting down
OPENDJ-1016: Control panel does not follow static group recommendation from documentation
OPENDJ-1007: InstallHelper: endless loop, etc.
OPENDJ-948: unauthorized disclosure of directory contents
OPENDJ-934: Changes to RS window-size property require a server restart
OPENDJ-862: Strange ds-privilege-name behavior
OPENDJ-810: Non-atomic password state updates
OPENDJ-737: OpenDJ Administration Connector KeyStore Pin File must be defined and non empty
OPENDJ-640: Text Query Against indexed telephoneNumber Attribute Very Slow
OPENDJ-573: mustChangePassword function makes-up password change state
OPENDJ-557: Identical changes recorded in duplicate changelog records
OPENDJ-527: rebuild-index --rebuildAll corrupts the indexes for certain data sets
OPENDJ-518: Cannot log into the administrative control panel with FIPS-140 enabled in certain cases
OPENDJ-505: dsreplication enable fails when hostname contains an underscore
OPENDJ-431: Server side sort control only works on result sets of less than 100000 entries
OPENDJ-412: Blocked persistent searches may block all worker threads
OPENDJ-365: Potential deadlock in JE backend while performing a mix of update operations
OPENDJ-270: dsreplication disable takes a long time
OPENDJ-49: Replication replay does not take into consideration the server/backend's writability mode.
If you have questions regarding OpenDJ which are not answered by the documentation, there is a mailing list which can be found at https://lists.forgerock.org/mailman/listinfo/opendj where you are likely to find an answer.
The content of this chapter has not changed in this release.
If you have found issues or reproducible bugs within OpenDJ 4.8.1-SNAPSHOT, report them in the OpenDJ issue tracker.
When requesting help with a problem, please include the following information:
Description of the problem, including when the problem occurs and its impact on your operation
Description of the environment, including the following information:
Machine type
Operating system & version
Storage type & version
Java version
Web container & version (if applicable)
OpenDJ release version
Any patches or other software that might be affecting the problem
Steps to reproduce the problem
Any relevant access and error logs, stack traces, or core dumps
You can purchase OpenDJ support subscriptions and training courses from ForgeRock and from consulting partners around the world and in your area. To contact ForgeRock, send mail to info@forgerock.com. To find a partner in your area, see http://forgerock.com/partners/.