How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I install a DS patch (All versions) supplied by ForgeRock support?

Last updated Jan 6, 2022

The purpose of this article is to provide information on installing a DS patch that has been supplied by ForgeRock support. The instructions differ depending on whether you are using a standalone DS or an embedded DS (in AM or IDM 6 and later).


3 readers recommend this article

Overview

This article covers installing DS patches in the following setups:

Requirements 

  • Patches should be applied to all external and embedded DS instances regardless of their use or type, that is:
    • Use: CTS, Configuration, Identities, IDM repository and so on.
    • Type: standalone Directory or Replication servers, DS+RS, embedded.
  • Ensure you test the patch in a lower environment before applying it to production servers.
  • Apply the patch as instructed to each instance in a rolling update fashion (stop, apply, start, move to the next instance).

Installing a patch for standalone DS or RS, or DS+RS

The following process to install a DS patch includes steps to create a Backout file. Having a Backout file means you can reverse the patch changes if needed and restore the previous /classes directory. 

Note

If you have installed the instance files separately to the install files (How do I install DS (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 the patch is installed in the instance.loc's classes directory. 

You can install a DS patch as follows:

  1. Create a Backout file as follows: $ cd /path/to/ds $ tar -cf backout-patch.tar classes  $ rm -fr classes
  2. Copy the supplied patch zip to the /tmp directory.
  3. Extract the patch zip: $ cd /path/to/ds $ unzip /tmp/OpenDJ-x.x.x-OPENDJ-xxxx.zip
  4. Stop and restart the DS server: $ ./stop-ds $ ./start-ds

Verify the patch installation

You can verify the patch has been installed correctly as follows:

$ ./status -V

Example response, where DS version and patch ID corresponds to the patch you just installed:

ForgeRock Directory Services 6.5.2+OPENDJ-1234 Build 20200519141638

Back out the patch

You can back out a patch as follows:

$ cd /path/to/ds $ rm -fr classes  $ tar -xf backout-patch.tar  $ ./stop-ds  $ ./start-ds

Installing a patch on the REST2LDAP Gateway

  1. Back up the /path/to/tomcat/webapps/opendj/WEB-INF/classes directory where the REST2LDAP Gateway is deployed.
  2. Check the /path/to/tomcat/webapps/opendj/WEB-INF/classes directory where the REST2LDAP Gateway is deployed to ensure that the classes contained in the patch do not already exist in the directory. If one or more classes do already exist, it may mean you have a conflicting patch installed. If this is the case, you should seek advice from ForgeRock support prior to applying the patch.
  3. Stop the web application container in which the REST2LDAP Gateway runs.
  4. Go to the /path/to/tomcat/webapps/opendj/WEB-INF directory where the REST2LDAP Gateway is deployed: $ cd /path/to/tomcat/webapps/opendj/WEB-INF
  5. Extract the patch zip: $ unzip /path/to/patch/X.zip
  6. Restart the web application container in which the REST2LDAP Gateway runs.
Note

You can remove the patch by replacing the /classes directory with your backup.

Installing a patch for embedded DS in AM

Apache Tomcat™

If you use the dsconfig tool with your embedded DS, you must apply the patch in two places in order that the dsconfig tool continues to work after installing the patch.

  1. Back up the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where AM is deployed. If you use the dsconfig tool, you should also back up the /path/to/openam/opends/classes directory.
  2. Check the /path/to/tomcat/webapps/openam/WEB-INF/classes directory where AM is deployed to ensure that the classes contained in the patch do not already exist in the directory. If one or more classes do already exist, it may mean you have a conflicting patch installed. If this is the case, you should seek advice from ForgeRock support prior to applying the patch.
  3. Stop the web application container in which AM runs.
  4. Go to the /path/to/tomcat/webapps/openam/WEB-INF directory where AM is deployed: $ cd /path/to/tomcat/webapps/openam/WEB-INF
  5. Extract the patch zip: $ unzip /path/to/patch/X.zip
  6. If you use the dsconfig tool, you should go to the /path/to/openam/opends directory and extract the patch zip: $ cd /path/to/openam/opends $ unzip /path/to/patch/X.zip
  7. Restart the web application container in which AM runs.
Note

You can remove the patch by replacing the /classes directory with your backup.

Oracle® WebLogic Server

 The patch must be applied to both the AM war file on the WebLogic web application container and the embedded DS directory (/path/to/openam/opends). The same steps apply regardless of whether AM has been deployed on a Weblogic admin server or a Weblogic managed server.

  1. Stop the web application container in which AM runs.
  2. Copy the supplied patch zip to the /tmp directory.
  3. Make a backup of the original openam.war file: $ cp /path/to/weblogic/openam.war /path/to/weblogic/openam.war.original
  4. Create a working directory called ToBePatched$ mkdir /path/to/weblogic/ToBePatched
  5. Copy the openam.war file to the ToBePatched directory: $ cp openam.war /path/to/weblogic/ToBePatched/openam.war
  6. Go to the ToBePatched directory: $ cd /path/to/weblogic/ToBePatched
  7. Expand the openam.war file: $ JAVA_HOME/bin/jar xvf openam.war This creates a directory structure with the contents of the openam.war file.
  8. Delete the openam.war file from the ToBePatched directory: $ rm /path/to/weblogic/ToBePatched/openam.war
  9. Extract the patch zip into the expanded war file directory: $ cd /path/to/weblogic/ToBePatched/WEB-INF/ $ unzip /tmp/OpenDJ-x.x.x-OPENDJ-xxxx.zip
  10. Delete the original openam.war file: $ rm /path/to/weblogic/openam.war
  11. Go to the ToBePatched directory and repack the new openam.war file with the patch included: $ cd /path/to/weblogic/ToBePatched/ $ $JAVA_HOME/bin/jar cvf /path/to/weblogic/openam.war * 
  12. Go to the embedded DS directory (/path/to/openam/opends) and extract the patch zip: $ cd /path/to/openam/opends $ unzip /tmp/OpenDJ-x.x.x-OPENDJ-xxxx.zip
  13. Restart the web application container in which AM runs.
  14. Verify the patch installation using the status command: $ /path/to/openam/opends/bin/status -V Example response, where DS version and patch ID corresponds to the patch you just installed: ForgeRock Directory Services 6.5.2+OPENDJ-1234 Build 20200519141638

Installing a patch for embedded DS in IDM 6 and later

The following process to install a patch for embedded DS includes steps to create a Backout file. Having a Backout file means you can reverse the patch changes if needed and restore the previous /classes directory. 

You can install a patch as follows:

  1. Create a Backout file as follows: $ cd ./db/openidm/opendj $ tar -cf backout-patch.tar classes  $ rm -fr classes
  2. Copy the supplied patch zip to the /tmp directory.
  3. Extract the patch zip: $ cd ./db/openidm/opendj $ unzip /tmp/OpenDJ-x.x.x-OPENDJ-xxxx.zip
  4. Shutdown and restart the IDM instance. $ cd /path/to/idm $ ./shutdown.sh  $ ./startup.sh 

Verify the patch installation

You can verify the patch has been installed correctly as follows:

$ cd ./db/openidm/opendj/bin $ ./status -V

Example response, where DS version and patch ID corresponds to the patch you just installed:

ForgeRock Directory Services 6.5.2+OPENDJ-1234 Build 20200519141638

Back out the patch

You can back out a patch as follows:

$ cd ./db/openidm/opendj $ rm -fr classes  $ tar -xf backout-patch.tar  $ cd /path/to/idm  $ ./shutdown.sh  $ ./startup.sh

See Also

ForgeRock Maintenance Release Policy

How do I install an AM patch (All versions) supplied by ForgeRock support?

How do I check what patches are installed for ForgeRock products?

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.