How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I migrate from an embedded to external DS in AM 5.x or 6.x?

Last updated Feb 24, 2021

The purpose of this article is to provide information on migrating from an embedded to external DS for the configuration data store in AM. If you plan on using an external configuration store, it is recommended that you start with the external configuration store rather than migrating to it after you have gone live. This information can also be used to migrate from one external instance to another to change the location of the configuration store. Both the old and new configuration stores must have been set up with the same base DN and have the same password.


5 readers recommend this article

Migrating configuration data stores

Note

Please note the following:

You can migrate configuration data stores as follows:

  1. Pre-AM 6.5 only: Navigate to Deployment > Servers > [Server Name] > Advanced and update the value of the com.sun.identity.sm.sms_object_class_name advanced property to:com.sun.identity.sm.ldap.SMSLdapObjectThis change allows multiple AM servers to communicate with the external DS configuration store for all types of LDAP operations. In AM 6.5 and later, this property defaults to com.sun.identity.sm.SmsWrapperObject, which does not need changing when you migrate.
  2. Add a new external configuration server by navigating to Deployment > Servers > [Server Name] > Directory Configuration > Server. Enter details for the new external configuration server, click + to add followed by Save Changes. The bootstrap file is automatically updated with the new directory configuration details.
Note

Port number 1389 is typically used for Simple connections and 1636 for SSL connections. Attempting to use 1636 for non-SSL connections can cause errors. 

  1. Delete the old configuration server from the console; this step only removes the configuration store from AM; it does not actually delete it. Again, the bootstrap file is automatically updated to remove the deleted directory configuration details.
  2. Stop the web application container in which AM runs.
  3. Stop the DS server that hosts the old configuration store if it is external; if it is embedded, it will have stopped when you stopped AM.
  4. Export data from the old configuration store server to an LDIF file using the following command (needs the --offline option when the server is stopped):$ ./export-ldif --offline --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/exportfile.ldif
  5. Stop the DS server that hosts the new configuration store.
  6. Take a backup of the config.ldif file for the new configuration store server (located in the /path/to/ds/config directory).
  7. Edit two properties within this file so they are set as follows to prepare for importing LDIF data: ds-cfg-single-structural-objectclass-behavior: warn  ds-cfg-allow-pre-encoded-passwords: true 
  8. Copy the 99-user.ldif file from the old configuration store server to the new one. This file contains custom schema definitions and is located in /config/schema; as of DS 6 and later, located in /db/schema for new installs.
  9. Import data into the new configuration store server from the LDIF file you created in step 6 using the following command (needs the --offline option when the server is stopped):$ ./import-ldif --offline --includeBranch dc=example,dc=com --backendID userRoot --ldifFile /path/to/exportfile.ldif
Note

Both the old and new configuration stores must have the same base DN, otherwise the import will fail. 

  1. Start the DS server that hosts the new configuration store.
  2. Start the web application container in which AM runs.
  3. Take a backup of the config.ldif file for the new configuration store server (located in the /path/to/ds/config directory).
  4. Edit one of the properties within this file that you changed previously so it is set as follows for improved security: ds-cfg-allow-pre-encoded-passwords: false
  5. If you have also migrated your CTS to an external DS instance, ensure you have followed the advice in Best practice for configuring an external DS instance for the Core Token Service (CTS) in AM 5.x and 6, including the steps in the CTS index import and rebuild section.

See Also

How do I remove the embedded DS 5.x or 6.x after migrating to an external instance?

How do I add a second configuration store or edit an existing configuration store in AM (All versions)?

Data stores in AM

Reference › Directory Configuration Properties

Administration Guide › Importing and Exporting Data

Related Training

N/A

Related Issue Tracker IDs

N/A


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