Upgrading DS/OpenDJ

This book provides information on upgrading DS/OpenDJ including recommended procedures for upgrading and known issues.


Recommended Processes


How do I convert a PDB backend to a JE backend in DS 5.x or OpenDJ 3.x?

The purpose of this article is to provide information on converting a PDB backend to a JE backend in DS/OpenDJ. You must convert your PDB backend before upgrading to DS 6.

Overview

The PDB backend was introduced in OpenDJ 3, deprecated in DS 5 and removed in DS 6. Before upgrading to DS 6, you must convert your PDB backend to a JE backend. See Release Notes › What's New for further information.

This does not affect the embedded DS/OpenDJ in AM/OpenAM as that uses the JE backend by default.

Converting a PDB backend to a JE backend

Note

We strongly recommend testing this conversion in your own staging environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues.

The steps needed to convert your backend vary according to which version you are currently on:

See Also

Upgrading DS/OpenDJ

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I avoid common pitfalls when upgrading DS/OpenDJ (All versions)?

The purpose of this article is to provide information on common pitfalls you should be aware of before upgrading DS/OpenDJ.

Upgrading DS/OpenDJ

To ensure your upgrade goes smoothly, this article provides pre-upgrade advice, including advice common to all versions and version specific known issues.

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the release notes relating to the new version of DS/OpenDJ so that you are fully aware of all the changes.

Upgrade advice for all versions

Newer versions of DS/OpenDJ will install and work seamlessly with older versions in a cluster to allow for a rolling upgrade. Replication will also work between different versions of DS/OpenDJ. 

This advice includes, but is not limited to:

Known issues in DS 6.x

Note

Before upgrading to DS 6.x, you must convert the PDB backend to a JE backend since this backend is removed in DS 6. See How do I convert a PDB backend to a JE backend in DS 5.x or OpenDJ 3.x? for further information.

The following known issue may affect you post-upgrade - workarounds are included where applicable:

Known issues in OpenDJ 3.x

The following known issues may affect you during the upgrade process - workarounds are included where applicable:

See Also

FAQ: Backup and restore in DS/OpenDJ

FAQ: Upgrading DS/OpenDJ

FAQ: Installing and configuring DS/OpenDJ

DS (All versions) and OpenDJ 3.x fail to start after upgrade if you use the Password Sync Plugin for IDM/OpenIDM

Upgrading DS/OpenDJ

Installation Guide › Before You Upgrade

Related Training

ForgeRock Directory Services Core Concepts

Related Issue Tracker IDs

N/A


How do I upgrade DS/OpenDJ if I have support patches installed (All versions)?

The purpose of this article is to provide assistance on upgrading DS/OpenDJ if you have any support patches installed. Support patches are installed in the classes directory and previous support patches are incompatible with the upgrade process.

Upgrading DS/OpenDJ

Before running the upgrade, you must remove old support patches from the /path/to/ds/classes/ directory where DS/OpenDJ is installed. Patches are built for the version they are intended for and are not backward compatible. These patches cannot be used again and since you cannot revert the upgrade, it is safe to remove them completely.

Note

If you have installed the instance files separately to the install files (How do I install DS/OpenDJ (All versions) so that the instance files are separate to the install files?), the instance.loc file indicates where the instance files are stored.​ You should follow these instructions but substitute the directory specified in the instance.loc file for the /path/to/ds directory to ensure you remove the old support patches from the instance.loc's classes directory. 

You can do this using the following commands:

$ cd /path/to/ds/classes/
$ rm -rf *

See Also

How do I avoid common pitfalls when upgrading DS/OpenDJ (All versions)?

How do I perform a rolling upgrade of DS/OpenDJ (All versions)?

FAQ: Upgrading DS/OpenDJ

Upgrading DS/OpenDJ

How do I upgrade DS/OpenDJ (All versions) if I have the DS/OpenDJ Password Sync Plugin for IDM/OpenIDM installed?

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-1098 (Upgrading must disable old patches)


How do I perform a rolling upgrade of DS/OpenDJ (All versions)?

The purpose of this article is to provide information on performing a rolling upgrade of DS/OpenDJ.

Performing a rolling upgrade

A rolling upgrade is the recommended approach to upgrading; new versions of DS/OpenDJ will install and work seamlessly with older versions of DS/OpenDJ in a cluster. On connection, each DS/OpenDJ node negotiates the protocol with the connected node, which allows a newer node to speak to an older node as necessary. Replication will also work between different versions of DS/OpenDJ, however, you should be aware that replication improvements in OpenDJ 2.6.0 will only manifest between 2.6.x nodes.

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the release notes relating to the new version of DS/OpenDJ so that you are fully aware of all the changes.

A rolling upgrade (sometimes called a sequential upgrade) involves the following steps:

  1. Disable DS/OpenDJ server 1 node from the load balancer.
  2. Stop DS/OpenDJ server 1.
  3. Upgrade DS/OpenDJ server 1 as described in the Installation guide (see See Also below for links).
  4. Check that DS/OpenDJ server 1 is operating correctly after the upgrade.
  5. Re-enable the successfully upgraded DS/OpenDJ server 1 node in the load balancer.
  6. Repeat steps 1 to 5 for each node until they are all upgraded.

See Also

How do I design and implement my backup and restore strategies for DS/OpenDJ (All versions)?

FAQ: Backup and restore in DS/OpenDJ

FAQ: Upgrading DS/OpenDJ

Starting DS/OpenDJ (All versions) server fails after upgrade

Administration Guide › Backing Up and Restoring Data

Installation Guide › Upgrading a Directory Server

Related Training

ForgeRock Directory Services Core Concepts

Related Issue Tracker IDs

N/A


How do I upgrade DS/OpenDJ (All versions) if I have the DS/OpenDJ Password Sync Plugin for IDM/OpenIDM installed?

The purpose of this article is to provide information on upgrading DS/OpenDJ if you have the DS/OpenDJ Password Sync Plugin for IDM/OpenIDM installed.

Background Information

The password plugin configuration is specified in one of the following files depending on the plugin version:

  • Plugin version 3.5.0 and later - openidm-accountchange-plugin-sample-config
  • Plugin versions 1.0.3 and 1.1.1 - openidm-pwsync-plugin-config.ldif
Note

You must use the plugin version that corresponds to your DS/OpenDJ version. See Release Notes › Supported Connectors, Connector Servers, and Plugins for further information.

Upgrading DS/OpenDJ

You can upgrade DS/OpenDJ as follows:

  1. Back up the password plugin configuration file (openidm-pwsync-plugin-config.ldif or openidm-accountchange-plugin-sample-config, which is located in the /path/to/ds/config directory) as this contains your current configuration details.
  2. Update the Default Password Policy to remove the account-status-notification-handler attribute using a dsconfig command such as the following:
    $ ./dsconfig set-password-policy-prop --policy-name "Default Password Policy" --reset account-status-notification-handler --hostname localhost --port 4444 --bindDn "cn=Directory Manager" --bindPassword password --trustAll --no-prompt
  3. Remove the changes made to the cn=config backend when the plugin was installed using a ldapdelete command such as the following:
    $ ./ldapdelete --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password "cn=OpenIDM Notification Handler,cn=Account Status Notification Handlers,cn=config"
  4. Stop the DS/OpenDJ instance.
  5. Delete the following files that apply to the existing plugin:
    • openidm-pwsync-plugin-config.ldif or openidm-accountchange-plugin-sample-config in the /path/to/ds/config directory.
    • 90-openidm-pwsync-plugin.ldif file in the /path/to/ds/config/schema directory; as of DS 6 and later, located in /path/to/ds/db/schema for new installs.
    • opendj-accountchange-handler-x.x.x.jar in the /path/to/ds/lib/extensions directory.
  6. Restart the DS/OpenDJ instance.
  7. Upgrade to the new version of DS/OpenDJ. See Installation Guide and Upgrading DS/OpenDJ for further information.
  8. Install the new plugin per the instructions in Password Synchronization Plugin Guide › Installing the DS Password Synchronization Plugin.
  9. Update the configuration file (openidm-pwsync-plugin-config.ldif or openidm-accountchange-plugin-sample-config depending on which version of the plugin you installed) with the details contained in the configuration file you backed up if you want to retain the same behavior you had previously.

See Also

DS (All versions) and OpenDJ 3.x fail to start after upgrade if you use the Password Sync Plugin for IDM/OpenIDM

OpenDJ Password Synchronization Plugin 1.0.3 install fails on OpenDJ 3.x

How do I troubleshoot the DS/OpenDJ Password Synchronization plugin in IDM/OpenIDM (All versions)?

Password Synchronization Plugin Guide › Synchronizing Passwords With ForgeRock Directory Services (DS)

Related Training

N/A

Related Issue Tracker IDs

N/A


Frequently Asked Questions


FAQ: Upgrading DS/OpenDJ

The purpose of this FAQ is to provide answers to commonly asked questions regarding upgrading DS/OpenDJ.

Frequently asked questions

Q. How can I find everything that has been fixed in a release?

A. You can look in the DS/OpenDJ Issue Tracker to see what has been fixed against a given release. Links for recent releases are included below:

Note

The release notes also list all the key fixes that have been included as well as any known issues that are still outstanding at the time of the release: DS 6.5 Release Notes, DS 6 Release Notes, DS 5.5 Release NotesDS 5 Release Notes, OpenDJ 3.5 Release Notes and OpenDJ 3 Release Notes.

Q. Where can I find end of support life (EOSL) dates for DS/OpenDJ?

A. The release dates and end of support life dates for DS/OpenDJ are available from: Checking your product versions are supported

Q. Can I upgrade an embedded DS/OpenDJ (in AM/OpenAM)?

A. No. Embedded DS/OpenDJ is automatically upgraded when you upgrade AM/OpenAM. If you have a need to upgrade DS/OpenDJ separately, you will need to use DS/OpenDJ as an external repository rather than the embedded DS/OpenDJ.

See What versions of DS/OpenDJ are compatible with AM/OpenAM? for further information on which versions of DS/OpenDJ can be used with AM/OpenAM.

Q. Is replication between two different versions of DS/OpenDJ supported when I am upgrading?

A. Yes. Replication between different versions of DS/OpenDJ is fully supported; we recommend doing a rolling upgrade of servers, which by its nature means you will have different versions of DS/OpenDJ running for a period of time while performing the upgrade process.

See Installation Guide › Upgrading a Directory Server and How do I perform a rolling upgrade of DS/OpenDJ (All versions)? for further information.

Q. Are there any known issues when upgrading to a later version?

A. The known issues and changes to existing functionality which may affect you are detailed in the release notes, for example: Release Notes. You should also review How do I avoid common pitfalls when upgrading DS/OpenDJ (All versions)? for further pre-upgrade advice.

As with all upgrades, you should ensure you take good backups prior to upgrading and read the release notes to understand all the changes.

Caution

Binary backups taken in one version cannot be restored in a different version.

Q. Do I need to change any parameters after upgrading to OpenDJ 3.x?

A. No, there are no parameters that need changing when running OpenDJ 3.x compared to running OpenDJ 2.6.x.

See Also

FAQ: Source code in DS/OpenDJ

FAQ: Backup and restore in DS/OpenDJ

FAQ: DS/OpenDJ compatibility with third-party products

FAQ: Installing and configuring DS/OpenDJ

FAQ: General DS/OpenDJ

Upgrading DS/OpenDJ

Installing and Administering DS/OpenDJ

Installation Guide › Before You Upgrade

Related Training

ForgeRock Directory Services Core Concepts


FAQ: Installing and configuring DS/OpenDJ

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing and configuring DS/OpenDJ.

Frequently asked questions

Q. Is DS/OpenDJ compatible with Oracle Java Development Kit (JDK) 9 or later?

A. Yes, Oracle JDK 9 is supported as of DS 6. You should only use supported versions to prevent compatibility issues. Future versions of DS will be targeting compatibility with Java 11: OPENDJ-5207 (Support running OpenDJ on Java 11).

Q. Where can I download the latest Enterprise or maintenance release of DS/OpenDJ?

A. The current supported releases of DS/OpenDJ are available for download from BackStage.

Q. Where can I find the DS/OpenDJ installation requirements?

A. The Release Notes provide the Hardware and Software requirements for installing DS/OpenDJ.

See the release notes for the latest version of DS: Release Notes › Before You Install.

Q. Can I install DS/OpenDJ so that the instance files are separate to the install files?

A. Yes you can. This setup allows you to separate all your backend database files and configuration in a separate file system to your binaries.

See How do I install DS/OpenDJ (All versions) so that the instance files are separate to the install files? for further details.

Q. How do I integrate IDM, AM and DS?

A. You should refer to Integrating IDM, AM, and DS, which collects the information you need to set up integration in one place. For additional features, refer to the following chapters from IDM documentation: Samples Guide › Integrating IDM With the ForgeRock Identity Platform and the Integrator's Guide › Setting Up User-Managed Access (UMA), Trusted Devices, and Privacy.

Q. Is it possible to clone a copy of an existing DS/OpenDJ between servers?

A. You can move DS/OpenDJ data between servers and operating systems. Most of the configuration is portable.

The following two aspects of the configuration are not portable:

  • Server certificates - they contain the host name of the system.
  • Replication configuration - this includes the host name and administrative port numbers.

The procedure and considerations are discussed in detail Moving Servers and Changing Server Certificates.

Q. What application servers are compatible for installing DS/OpenDJ DSML gateway or DS/OpenDJ REST LDAP gateway?

A. If you are planning to install the DS/OpenDJ DSML gateway or the DS/OpenDJ REST LDAP gateway, you need to have the appropriate compatible Application Servers installed.

DS/OpenDJ REST to LDAP gateway, and DS/OpenDJ DSML gateway run on Apache Tomcat™ and Jetty®. ForgeRock supports only stable container releases. See the Tomcat and Jetty documentation for details on which container version supports the Java version used in your deployment.

Note

DS/OpenDJ directory server runs as a standalone JVM service and does not depend on an application server.

Q. Where can I find available options to install or remove DS/OpenDJ?

A. You can install or remove the DS/OpenDJ software using the Install Wizard or through the command line. Detailed steps can be found in the Installation Guide:

Q. Where can I find an example DS/OpenDJ installation script?

A. The Installation Guide › Installing a Directory Server provides examples of the available install options including scripted (Silent) Install.

Q. Can I create a new base DN using the command line?

A. Yes you can. It is a two stage process because creating the backend using the command line only creates the backend database and adds its configuration to the instance. It does not create the base entry for you. The backend is only created with the base entry if you do it via the control panel; the control panel is removed in DS 6.

To create a base DN:

  1. Create the backend configuration and database using the dsconfig command. See Administration Guide › Creating a New Database Backend for further information.
  2. Add the base DN entry to the backend using the ldapmodify command or import the base DN entry into the backend using the import-ldif command. See Administration Guide › Importing and Exporting Data for further information.

Q. Is there a configuration reference for DS/OpenDJ?

A. Yes, the Configuration Reference is provided, which details the configuration components available in DS/OpenDJ.

Q. How can I configure my local system to make administering DS/OpenDJ server easier?

A. You can eliminate the need to provide defined arguments when using command line utilities by creating a personal tools.properties file to store commonly entered parameters such as bind DN, host name, and port number.

See Developer's Guide › Configuring Default Settings for a tools.properties example.

After saving the changes to your new tools.properties file, perform a query of your suffix as follows:

$ ./ldapsearch "(objectclass=*)" 

Which gives an output similar to this (where the example suffix is dc=example,dc=com):

dn: dc=example,dc=com 
dc: example 
objectclass: domain 
objectclass: top
Note

The tools.properties file found in the user’s .opendj directory takes the highest precedence for the executing user. If you need different parameters for different DS/OpenDJ instances installed on the same system, create a tools.properties file in the config directory for each individual instance rather than in the user’s directory. 

See Also

FAQ: Passwords in DS/OpenDJ

FAQ: DS/OpenDJ compatibility with third-party products

FAQ: General DS/OpenDJ

FAQ: Upgrading DS/OpenDJ

Installing and Administering DS/OpenDJ

Deployment Guide

Installation Guide

Administration Guide

Related Training

ForgeRock Directory Services Core Concepts 


What versions of DS/OpenDJ are compatible with AM/OpenAM?

The purpose of this article is to provide compatibility information between DS/OpenDJ and AM/OpenAM versions. This includes the embedded DS/OpenDJ versions shipped with AM/OpenAM and, the supported Java® versions for each combination.

DS/OpenDJ and AM/OpenAM compatibility

Embedded DS/OpenDJ

Embedded DS/OpenDJ versions are shipped with AM/OpenAM and cannot be upgraded; however, when you upgrade to a newer version of AM/OpenAM, the embedded DS/OpenDJ instance is also upgraded. The following embedded DS/OpenDJ versions are included with AM/OpenAM:

AM/OpenAM versions Embedded DS/OpenDJ version
AM 6.5 DS 6.5
AM 6 DS 6
AM 5.5 and 5.5.1 DS 5.5
AM 5 and 5.1.x DS 5
OpenAM 13.5.2 OpenDJ 3.5.3
OpenAM 13.5.1 OpenDJ 3.5.2
OpenAM 13.5 OpenDJ 3.5
OpenAM 13.0 OpenDJ 3.0
OpenAM 12.0.4 OpenDJ 2.6.4
OpenAM 12.0.0 to 12.0.3 OpenDJ 2.6.2

External DS/OpenDJ

The following matrix indicates compatibility between AM/OpenAM and external DS/OpenDJ versions:

  DS 6.x DS 5.x OpenDJ 3.x OpenDJ 2.6.x
AM 6.x Yes Yes Yes --
AM 5.5 -- Yes Yes --
AM 5 and 5.1.x -- Yes Yes Partly (User Store only)
OpenAM 13.x -- -- Yes Yes
OpenAM 12.x -- -- -- Yes
Note

It is strongly recommended that you always upgrade to the latest maintenance releases for whichever versions of AM/OpenAM and DS/OpenDJ you have deployed.

Java Compatability

Java 11

  • AM 6.5 and later.
  • DS 6.5 and later.

Java 9

  • DS 6 only.

Java 8

  • AM 5 and later; OpenAM 12.0.0 and later
  • DS 5 and later; OpenDJ 2.6.2 and later

Java 7

  • AM 5 and 5.1.x; OpenAM 12.x and 13.x
  • OpenDJ 2.6.x and 3.x. Java 7 can be used in DS 5 but support for it is deprecated.

Java 6

  • OpenAM 12.x
  • OpenDJ 2.6.x

Software and Hardware requirements

AM/OpenAM

DS/OpenDJ

See Also

What operating systems are ForgeRock products supported on?

Checking your product versions are supported

FAQ: Installing AM/OpenAM

FAQ: Upgrading AM/OpenAM

FAQ: Installing and configuring DS/OpenDJ

Installing and configuring AM/OpenAM

Installing and Administering DS/OpenDJ

Related Training

N/A

Related Issue Tracker IDs

N/A


Known Issues


Insufficient Access Rights error for dsreplication status after upgrading a replicated server to DS 6.x

The purpose of this article is to provide assistance if the dsreplication status command returns "Insufficient Access Rights: You do not have sufficient privileges to read directory server monitoring information" after upgrading to DS 6.x

Symptoms

Using a dsreplication status command such as the following returns partial or no information: 

$ ./dsreplication status --hostname localhost.localdomain --port 4444 --adminUID admin --adminPassword password --trustAll --no-prompt

Responses:

  • An error similar to the following is shown when you run dsreplication status non-interactively:
    The displayed information might not be complete because the following errors 
    were encountered reading the configuration of the existing servers:
    
    Error on ds1.example.com: An error occurred connecting to the server. 
    Details: Insufficient Access Rights: You do not have sufficient privileges to 
    read directory server monitoring information 
    
  • The following output is shown when you run the command interactively:
    No replication information found.
    

Recent Changes

Upgraded to DS 6.x.

Causes

The required permissions for monitoring dsreplication have changed in DS 6 and need to be updated manually as noted in the Installation Guide › To Upgrade Replicated Servers.

Solution

This issue can be resolved by adding the following required permissions:

  • bypass-lockdown
  • monitor-read
  • server-lockdown

Example

The following example grants the privileges to the default global administrator account, which has DN cn=admin,cn=Administrators,cn=admin data:

$ ./ldapmodify --port 1389 --hostname ds1.example.com --bindDN "cn=admin,cn=Administrators,cn=admin data" --bindPassword password
dn: cn=admin,cn=Administrators,cn=admin data
changetype: modify
add: ds-privilege-name
ds-privilege-name: bypass-lockdown
ds-privilege-name: monitor-read
ds-privilege-name: server-lockdown
-

See Also

Upgrading DS/OpenDJ

Installation Guide › Upgrading a Directory Server

Related Training

N/A

Related Issue Tracker IDs

N/A


Starting DS/OpenDJ (All versions) server fails after upgrade

The purpose of this article is to provide assistance if the DS/OpenDJ server fails to start after upgrade with an error that refers to the config.ldif file.

Symptoms

An error similar to the following is shown when starting the DS/OpenDJ server: 

The Directory Server has sent an alert notification generated by class 
org.opends.server.core.DirectoryServer (alert type org.opends.server.DirectoryServerShutdown, 
alert ID 458893): The Directory Server has started the shutdown process. The shutdown was initiated by an 
instance of class org.opends.server.core.DirectoryServer and the reason provided for the shutdown was 
An error occurred while trying to start the Directory Server: Configuration entry 
ds-cfg-attribute=[attribute],cn=Index,ds-cfg-backend-id=[backend-id],cn=Backends,cn=config starting at or 
near line nnn in the configuration LDIF file /path/to/ds/config/config.ldif does not appear to have a 
parent entry (expected parent DN was cn=Index,ds-cfg-backend-id=[backend-id],cn=Backends,cn=config) 

Followed by:

The Directory Server is now stopped.

Recent Changes

Upgraded DS/OpenDJ.

Causes

The case used for the ds-cfg-backend-id value must be consistent throughout the config.ldif file, otherwise the server will fail to start. This change was introduced in OpenDJ 2.6.0 to ensure our schema definitions comply with LDAP RFC 4512.

Solution

Edit the config.ldif file (located in the /path/to/ds/config/ directory where DS/OpenDJ is installed) and ensure the case of all ds-cfg-backend-id values match.

See Also

RFC 4512

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-1468 (Case sensitivity changes cause problems upgrading cn=config)


Upgrading DS/OpenDJ (All versions) fails with UnsupportedClassVersion error

The purpose of this article is to provide assistance if the DS/OpenDJ server fails to upgrade to a later version with "Exception in thread "main" java.lang.UnsupportedClassVersionError".

Symptoms

An error similar to the following is shown when the upgrade fails:

Exception in thread "main" java.lang.UnsupportedClassVersionError: org/opends/server/tools/upgrade/UpgradeCli : Unsupported major.minor version 52.0  
   at java.lang.ClassLoader.defineClass1(Native Method)  
   at java.lang.ClassLoader.defineClass(ClassLoader.java:800)  
   at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)  
   at java.net.URLClassLoader.defineClass(URLClassLoader.java:449)  
   at java.net.URLClassLoader.access$100(URLClassLoader.java:71)  
   at java.net.URLClassLoader$1.run(URLClassLoader.java:361)  
   at java.net.URLClassLoader$1.run(URLClassLoader.java:355)  
   at java.security.AccessController.doPrivileged(Native Method)  
   at java.net.URLClassLoader.findClass(URLClassLoader.java:354)  
   at java.lang.ClassLoader.loadClass(ClassLoader.java:425)  
   at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)  
   at java.lang.ClassLoader.loadClass(ClassLoader.java:358)  
   at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:482)

The same error is shown in the Upgrade.log file.

Recent Changes

N/A

Causes

The version of DS/OpenDJ you are upgrading to requires a different version of Java® than the one running on your server. The Java versions required are as follows:

  • DS 6.5 - Java 8 or 11
  • DS 6 - Java 8 or 9
  • DS 5.5.x - Java 8
  • DS 5 - Java 7 or 8
  • OpenDJ 3.x - Java 7 or 8

See the release notes applicable to your version for further information, for example: DS 6.5 Release Notes › Preparing the Java Environment.

Solution

This issue can be resolved by installing the required version of Java and then enabling the server to use the newer version as detailed in How do I change DS/OpenDJ (All versions) to use a different JDK version?

Once Java is successfully updated, you can then upgrade the DS/OpenDJ server.

See Also

How do I ensure DS/OpenDJ (All versions) uses the Java settings from java.properties file when DS/OpenDJ is started?

Upgrading DS/OpenDJ

Installation Guide › Upgrading a Directory Server

Related Training

N/A

Related Issue Tracker IDs

N/A


DS (All versions) and OpenDJ 3.x fail to start after upgrade if you use the Password Sync Plugin for IDM/OpenIDM

The purpose of this article is to provide assistance if DS/OpenDJ fails to start after upgrading to a later version. This issue occurs when you use the Password Sync Plugin for IDM/OpenIDM. You will see one of the following exceptions: "java.lang.ClassNotFoundException: org.forgerock.opendj.config.DNPropertyDefinition" or "org.forgerock.openidm.agent.accountchange.OpenidmAccountStatusNotificationHandler".

Symptoms

One of the following errors are shown when the server fails to start: 

  • Exception in thread "main" java.lang.NoClassDefFoundError: org.forgerock.opendj.config.DNPropertyDefinition
    Exception in thread "main" java.lang.NoClassDefFoundError: org/forgerock/opendj/config/DNPropertyDefinition
       at java.lang.Class.forName0(Native Method)
       at java.lang.Class.forName(Class.java:348)
       at org.forgerock.opendj.config.ConfigurationFramework.loadDefinitionClasses(ConfigurationFramework.java:640)
       at org.forgerock.opendj.config.ConfigurationFramework.initializeExtension(ConfigurationFramework.java:583)
       at org.forgerock.opendj.config.ConfigurationFramework.addExtension(ConfigurationFramework.java:471)
       at org.forgerock.opendj.config.ConfigurationFramework.initializeAllExtensions(ConfigurationFramework.java:524)
       at org.forgerock.opendj.config.ConfigurationFramework.initialize0(ConfigurationFramework.java:492)
       at org.forgerock.opendj.config.ConfigurationFramework.initialize(ConfigurationFramework.java:404)
       at org.forgerock.opendj.config.ConfigurationFramework.initialize(ConfigurationFramework.java:372)
       at org.opends.server.config.ConfigurationHandler.bootstrapConfiguration(ConfigurationHandler.java:183)
       at org.opends.server.core.DirectoryServer.initializeConfiguration(DirectoryServer.java:1144)
       at org.opends.server.core.DirectoryServer.main(DirectoryServer.java:4066)
    Caused by: java.lang.ClassNotFoundException: org.forgerock.opendj.config.DNPropertyDefinition
       at java.net.URLClassLoader.findClass(URLClassLoader.java:381)
       at java.lang.ClassLoader.loadClass(ClassLoader.java:424)
       at java.lang.ClassLoader.loadClass(ClassLoader.java:357)
    	... 12 more
    [] category=CORE severity=NOTICE msgID=139 msg=The Directory Server has sent an alert notification generated by class org.opends.server.core.DirectoryServer (alert type org.opends.server.DirectoryServerShutdown, alert ID org.opends.messages.core-141): The Directory Server has started the shutdown process. The shutdown was initiated by an instance of class org.opends.server.core.DirectoryServerShutdownHook and the reason provided for the shutdown was The Directory Server shutdown hook detected that the JVM is shutting down. This generally indicates that JVM received an external request to stop (e.g., through a kill signal)
    [] category=CORE severity=NOTICE msgID=203 msg=The Directory Server is now stopped
    
  • "org.forgerock.openidm.agent.accountchange.OpenidmAccountStatusNotificationHandler" is not a valid value for the "java-class" property, which must have the following syntax: CLASS <= org.opends.server.api.AccountStatusNotificationHandler:
    category=CORE severity=NOTICE msgID=139 msg=The Directory Server has sent an alert notification generated by class org.opends.server.core.DirectoryServer (alert type org.opends.server.DirectoryServerShutdown, alert ID org.opends.messages.core-141): The Directory Server has started the shutdown process. The shutdown was initiated by an instance of class org.opends.server.core.DirectoryServer and the reason provided for the shutdown was An error occurred while trying to start the Directory Server: ConfigException: An error occurred while trying to decode the managed object configuration entry cn=config: The following constraint violation occurred: A configuration exception occurred while evaluating a constraint: An error occurred while trying to decode the managed object configuration entry cn=Default Password Policy,cn=Password Policies,cn=config: The following constraint violation occurred: A configuration exception occurred while evaluating a constraint: An error occurred while trying to decode the managed object configuration entry cn=OpenIDM Notification Handler,cn=Account Status Notification Handlers,cn=config: The Account Status Notification Handler could not be decoded due to the following reason: The value "org.forgerock.openidm.agent.accountchange.OpenidmAccountStatusNotificationHandler" is not a valid value for the "java-class" property, which must have the following syntax: CLASS <= org.opends.server.api.AccountStatusNotificationHandler (ConfigExceptionFactory.java:85 ServerManagementContext.java:356 ServerManagedObject.java:483 RootCfgDefn.java:1952 CoreConfigManager.java:156 DirectoryServer.java:1247 DirectoryServer.java:4210)
    
  • "org.forgerock.openidm.agent.accountchange.OpenidmAccountStatusNotificationHandler" is not a valid value for the "java-class" property, which must have the following syntax: CLASS <= org.opends.server.api.AccountStatusNotificationHandler:
    category=CORE severity=NOTICE msgID=139 msg=The Directory Server has sent an alert notification generated by class org.opends.server.core.DirectoryServer (alert type org.opends.server.DirectoryServerShutdown, alert ID org.opends.messages.core-141): The Directory Server has started the shutdown process. The shutdown was initiated by an instance of class org.opends.server.core.DirectoryServer and the reason provided for the shutdown was An error occurred while trying to start the Directory Server: InitializationException: An error occurred while trying to initialize an instance of class org.forgerock.openidm.agent.accountchange.OpenidmAccountStatusNotificationHandler as an account status notification handler as defined in configuration entry cn=OpenIDM Notification Handler,cn=Account Status Notification Handlers,cn=config: PropertyException: The value "org.forgerock.openidm.agent.accountchange.OpenidmAccountStatusNotificationHandler" is not a valid value for the "java-class" property, which must have the following syntax: CLASS <= org.opends.server.api.AccountStatusNotificationHandler (PropertyException.java:78 ClassPropertyDefinition.java:226 ClassPropertyDefinition.java:211 ClassPropertyDefinition.java:172 AccountStatusNotificationHandlerConfigManager.java:347 AccountStatusNotificationHandlerConfigManager.java:309 AccountStatusNotificationHandlerConfigManager.java:110 DirectoryServer.java:2074 DirectoryServer.java:1561 DirectoryServer.java:6265) (AccountStatusNotificationHandlerConfigManager.java:375 AccountStatusNotificationHandlerConfigManager.java:309 AccountStatusNotificationHandlerConfigManager.java:110 DirectoryServer.java:2074 DirectoryServer.java:1561 DirectoryServer.java:6265) 
    

Recent Changes

Upgraded to a later version of DS/OpenDJ.

Causes

The Password Synchronization Plugin used with the previous version of DS/OpenDJ is not compatible with later versions. You must upgrade the Password Sync Plugin after upgrading DS/OpenDJ.

Solution

This issue can be resolved by rolling back the upgrade and then upgrading DS/OpenDJ as detailed in How do I upgrade DS/OpenDJ (All versions) if I have the DS/OpenDJ Password Sync Plugin for IDM/OpenIDM installed?

See Also

OpenDJ Password Synchronization Plugin 1.0.3 install fails on OpenDJ 3.x

How do I troubleshoot the DS/OpenDJ Password Synchronization plugin in IDM/OpenIDM (All versions)?

Passwords in DS/OpenDJ

Release Notes › Supported Connectors

Related Training

N/A

Related Issue Tracker IDs

N/A


Insufficient free memory error when installing OpenDJ 3.5

The purpose of this article is to provide assistance if you encounter the following error when installing or upgrading to OpenDJ 3.5 using the setup command: "An error occurred while attempting to process the LDIF import: Insufficient free memory".

Symptoms

The following error is shown when running the ./setup command to install or upgrade to OpenDJ 3.5:

[22/09/2016:12:11:57 +0000] category=BACKEND seq=21 severity=INFO msg=Import LDIF environment close took 0 seconds 
[22/09/2016:12:11:57 +0000] category=QUICKSETUP seq=72 severity=INFO msg=import-ldif out log: [22/09/2016:12:11:57 +0000] category=BACKEND seq=22 severity=INFO msg=Flushing data to disk 
[22/09/2016:12:11:57 +0000] category=QUICKSETUP seq=73 severity=WARNING msg=import-ldif error log: 
[22/09/2016:12:11:57 +0000] category=TOOLS seq=23 severity=SEVERE msg=An error occurred while attempting to process the LDIF import: Insufficient free memory (86113843 bytes) to perform import. At least 87293952 bytes of free memory is required 
[22/09/2016:12:11:57 +0000] category=QUICKSETUP seq=74 severity=SEVERE msg=Error: Error Creating Base Entry. 
[22/09/2016:12:11:57 +0000] category=QUICKSETUP seq=75 severity=SEVERE msg=Caught exception: Error Creating Base Entry. 
[22/09/2016:12:11:57 +0000] category=QUICKSETUP seq=76 severity=SEVERE msg=Error installing.

Recent Changes

N/A

Causes

The setup process launches a separate import-ldif process to create the baseDN and uses the default JVM parameters for this.

The JVM heap value being used is too small for the import-ldif process to complete. This can also happen if the server you are using has low memory (for example, a VM with only 1GB RAM) as the JVM automatically assigns a heap value based on the total memory available on the server.

Solution

This issue can be resolved as follows:

  1. Run ./setup without creating the baseDN entry (that is, exclude the --addBaseEntry or -a option) and include the --doNotStart option to prevent the server from starting once setup is complete, for example:
    $ ./setup --cli --acceptLicense --doNotStart --propertiesFilePath /tmp/properties --no-prompt
    An example properties file that works successfully on a low memory VM is:
    ldapPort=1389
    generateSelfSignedCertificate=true
    enableStartTLS=true
    ldapsPort=3636
    jmxPort=1689
    adminConnectorPort=4444
    rootUserDN=cn=Directory Manager
    rootUserPassword=password
    baseDN=dc=example,dc=com
  2. Run the import-ldif command offline to create the baseDN entry. You should use a command such as the following, which excludes the connection details and increases the JVM heap available to the command:
    $ export OPENDJ_JAVA_OPTS="-Xms512m -Xmx512m" && ./import-ldif --backendID userRoot --ldifFile /tmp/basedn.ldif

You should also look to increase the JVM heap size on your server. See How do I tune DS/OpenDJ (All versions) process sizes: JVM heap and database cache? for further information. 

See Also

How do I tune DS/OpenDJ (All versions) process sizes: JVM heap and database cache?

Best practice for JVM Tuning

Related Training

N/A

Related Issue Tracker IDs

N/A


Out Of Memory Error when installing OpenDJ 3, or using import-ldif, rebuild-index or dsreplication commands

The purpose of this article is to provide assistance if you encounter an "Exception in thread "main" java.lang.OutOfMemoryError at sun.misc.Unsafe.allocateMemory(Native Method)" error. This error can occur when you use the setup command to install or upgrade, or you use the import-ldif or rebuild-index commands. Similarly, you might see an "OutOfMemoryError (Unsafe.java" error when using the dsreplication command.

Symptoms

You will see one of the following errors in your errors log depending on which command you are using:

  • setup (this includes an import-ldif command that's used during the setup process):
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=73 severity=INFO msg=import-ldif out log: [12/09/2016:08:39:51 +0100] category=PLUGGABLE seq=11 severity=INFO msg=Import LDIF environment close took 0 seconds
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=74 severity=INFO msg=import-ldif out log: [12/09/2016:08:39:51 +0100] category=PLUGGABLE seq=12 severity=INFO msg=Flushing data to disk
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=75 severity=WARNING msg=import-ldif error log: Exception in thread "main" java.lang.OutOfMemoryError
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=76 severity=WARNING msg=import-ldif error log:  at sun.misc.Unsafe.allocateMemory(Native Method)
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=77 severity=WARNING msg=import-ldif error log:  at org.opends.server.backends.pluggable.OnDiskMergeImporter$BufferPool$OffHeapBuffer.<init>(OnDiskMergeImporter.java:2858)
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=78 severity=WARNING msg=import-ldif error log:  at org.opends.server.backends.pluggable.OnDiskMergeImporter$BufferPool.<init>(OnDiskMergeImporter.java:2780)
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=79 severity=WARNING msg=import-ldif error log:  at org.opends.server.backends.pluggable.OnDiskMergeImporter$StrategyImpl.importLDIF(OnDiskMergeImporter.java:203)
    [12/09/2016:08:39:51 +0100] category=QUICKSETUP seq=80 severity=WARNING msg=import-ldif error log:  at org.opends.server.backends.pluggable.BackendImpl.importLDIF(BackendImpl.java:689)
    ...
    
  • import-ldif:
    Exception in thread "main" java.lang.OutOfMemoryError 
       at sun.misc.Unsafe.allocateMemory(Native Method) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$BufferPool$OffHeapBuffer.<init>(OnDiskMergeImporter.java:2858) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$BufferPool.<init>(OnDiskMergeImporter.java:2780) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$StrategyImpl.importLDIF(OnDiskMergeImporter.java:203) 
       at org.opends.server.backends.pluggable.BackendImpl.importLDIF(BackendImpl.java:689) 
       at org.opends.server.tools.ImportLDIF.processLocal(ImportLDIF.java:1092) 
       at org.opends.server.tools.tasks.TaskTool.process(TaskTool.java:362) 
       at org.opends.server.tools.ImportLDIF.process(ImportLDIF.java:292) 
       at org.opends.server.tools.ImportLDIF.mainImportLDIF(ImportLDIF.java:147) 
       at org.opends.server.tools.ImportLDIF.main(ImportLDIF.java:110)
    ...
    
  • rebuild-index:
    Exception in thread "main" java.lang.OutOfMemoryError 
       at sun.misc.Unsafe.allocateMemory(Native Method) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$BufferPool$OffHeapBuffer.<init>(OnDiskMergeImporter.java:2858) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$BufferPool.<init>(OnDiskMergeImporter.java:2780) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$StrategyImpl.rebuildIndex(OnDiskMergeImporter.java:312) 
       at org.opends.server.backends.pluggable.OnDiskMergeImporter$StrategyImpl.rebuildIndex(OnDiskMergeImporter.java:275) 
       at org.opends.server.backends.pluggable.BackendImpl.rebuildBackend(BackendImpl.java:806) 
       at org.opends.server.tools.RebuildIndex.rebuildIndex(RebuildIndex.java:559) 
       at org.opends.server.tools.RebuildIndex.processLocal(RebuildIndex.java:321) 
       at org.opends.server.tools.tasks.TaskTool.process(TaskTool.java:362) 
       at org.opends.server.tools.RebuildIndex.process(RebuildIndex.java:228) 
       at org.opends.server.tools.RebuildIndex.mainRebuildIndex(RebuildIndex.java:138) 
       at org.opends.server.tools.RebuildIndex.main(RebuildIndex.java:110) 
    ...
    
  • dsreplication:
    [17/Sep/2016:08:39:51 +0100] category=org.opends.server.api.DirectoryThread severity=ERROR msgID=org.opends.messages.core.140 msg=An uncaught exception during processing for thread Replica DS(18687) listener for domain "dc=forgerock,dc=com" has caused it to terminate abnormally. The stack trace for that exception is: OutOfMemoryError (Unsafe.java:-2 OnDiskMergeImporter.java:2858 OnDiskMergeImporter.java:2780 OnDiskMergeImporter.java:203 BackendImpl.java:689 LDAPReplicationDomain.java:3565 ReplicationDomain.java:2275 ReplicationDomain.java:778 ReplicationDomain.java:106 ReplicationDomain.java:2965 Thread.java:744)
    [17/Sep/2016:08:39:51 +0100] category=CORE severity=NOTICE msgID=org.opends.messages.core.139 msg=The Directory Server has sent an alert notification generated by class org.opends.server.api.DirectoryThread (alert type org.opends.server.UncaughtException, alert ID org.opends.messages.core-140): An uncaught exception during processing for thread Replica DS(18687) listener for domain "dc=forgerock,dc=com" has caused it to terminate abnormally. The stack trace for that exception is: OutOfMemoryError (Unsafe.java:-2 OnDiskMergeImporter.java:2858 OnDiskMergeImporter.java:2780 OnDiskMergeImporter.java:203 BackendImpl.java:689 LDAPReplicationDomain.java:3565 ReplicationDomain.java:2275 ReplicationDomain.java:778 ReplicationDomain.java:106 ReplicationDomain.java:2965 Thread.java:744)
    ...
    

Recent Changes

Upgraded to, or installed OpenDJ 3.0.

Causes

Changes were made in OpenDJ 3.0.0 tools that introduced a new off-heap memory management mechanism, which mean that certain commands now request memory outside of the Java® heap using the sun.misc.Unsafe.allocateMemory() method. 

The number of allocations depend on the number of threads and the number of attribute indexes. OpenDJ calculates how many threads it uses based on the number of CPUs available to the system. It is likely this error occurs because the number of allocations being done when you are using the default number of threads exceeds the amount of memory a 32-bit JVM can allocate.

Solution

This issue can be resolved by upgrading to OpenDJ 3.5 or later which has improved/fixed memory management for imports; you can download this from BackStage.

Workaround

You can workaround this issue by switching to a 64-bit JVM as follows to allow more memory to be allocated:

  1. Add the -d64 option to the start-ds.java-args property in the java.properties file (located in the /path/to/opendj/config directory), for example:
    start-ds.java-args=-server -Xms2g -Xmx2g -d64
    
  2. Run the bin/dsjavaproperties command to apply the changes you have made to the java.properties file:
    $ ./dsjavaproperties
  3. Restart the OpenDJ server.
Note

If your heap size is less than 32GB, you should also specify CompressedOops as detailed in How do I tune DS/OpenDJ (All versions) process sizes: JVM heap and database cache?

If your JVM does not support 64-bit, you can try one of the following approaches instead:

  • Limit the number of CPUs being used by these commands as this will reduce the amount of memory required. This is a server level change, but for import-ldif you can limit the number of threads being used by adding the --threadCount option to your command. For example, add the following to use 8 threads:
    --threadCount 8
  • Increase the JVM heap size. See How do I tune DS/OpenDJ (All versions) process sizes: JVM heap and database cache? for further information.
  • Run ./setup without creating the baseDN entry (that is, exclude the --addBaseEntry or -a option) and then run an import-ldif command afterwards to create it.

See Also

OpenDJ Release Notes › OpenDJ Fixes, Limitations, and Known Issues › Key Fixes in 3.5.0

How do I tune DS/OpenDJ (All versions) process sizes: JVM heap and database cache?

How do I ensure DS/OpenDJ (All versions) uses the Java settings from java.properties file when DS/OpenDJ is started?

Best practice for JVM Tuning

OpenDJ Administration Guide › Managing Directory Data › Importing and Exporting Data

How do I collect JVM data for troubleshooting DS/OpenDJ (All versions)?

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-3212 (When we are upgrading Opendj from 2.4.4 to 3.0.0 version, java.lang.OutOfMemoryError occured)

OPENDJ-2721 (JE is using all the available heap memory during import.)


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...