Guide to installing ForgeRock® Directory Services software.

You can use the .zip delivery on any supported operating system.

Installation is a multi-stage process. You unpack the server software with the unzip command. You set up the server with the setup command:

1. Prepare for installation as described in "Before You Install".

2. Unpack the cross-platform .zip file in the file system directory where you want to install the server.

   The setup command, described in "setup — install OpenDJ server", uses the directory where you unzipped the files as the installation directory, and does not ask you where to install the server. If you want to install elsewhere on the file system, unzip the files in that location.

   Unzipping the .zip file creates a top-level opendj directory in the directory where you unzipped the file. On Windows systems if you unzip the file with Right-Click > Extract All, remove the trailing opendj-6.5.6 directory from the folder you specify.

3. Run the setup command to set up the server.

On Debian and related Linux distributions such as Ubuntu, you can install server software from the Debian package.

Installation is a multi-stage process. You install the software using the system package manager. You set up the server with the setup command:

1. Prepare for installation as described in "Before You Install".

   In particular, install a Java runtime environment (JRE) if none is installed yet.

   DS software requires a supported Java environment listed in "Preparing the Java Environment". The following example uses the default JRE on a system where the default version is recent enough:

   $ sudo apt-get install default-jre
     

2. Install the server package:

   $ sudo dpkg -i DS*.deb
     

   The Debian package installs server files in the /opt/opendj directory, generates service management scripts, adds documentation files under /usr/share/doc/opendj, and adds man pages under /opt/opendj/share/man.

   The files are owned by root by default, making it easier to have the server listen on ports such as 389 and 636.

3. Set up the server with the setup command, sudo /opt/opendj/setup.

On Red Hat and related Linux distributions such as Fedora and CentOS, you can install server software from the RPM package.

Installation is a multi-stage process. You install the software using the system package manager. You set up the server with the setup command:

1. Prepare for installation as described in "Before You Install".

   In particular, install a Java runtime environment (JRE) if none is installed yet.

   DS software requires a supported Java environment listed in "Preparing the Java Environment". You might need to download an RPM to install the Java runtime environment, and then install the RPM by using the rpm command:

   $ su
   Password:
   # rpm -ivh jre-*.rpm
     

2. Install the server package:

   # rpm -i DS*.rpm
     

   The RPM package installs server files in the /opt/opendj directory, generates service management scripts, and adds man pages under /opt/opendj/share/man.

   The files are owned by root by default, making it easier to have the server listen on ports such as 389 and 636.

3. Set up the server with the setup command, /opt/opendj/setup.

   By default, the server starts in run levels 2, 3, 4, and 5.

You can install server software on Windows using the .msi installer package.

Installation is a multi-stage process. You install the software with the Windows installer package wizard. You set up the server with the setup command:

1. Prepare for installation as described in "Before You Install".

   Prevent antivirus and intrusion detection systems from interfering with DS software.

   Before using DS software with antivirus or intrusion detection software, consider the following potential problems:

   Interference with normal file access

   Antivirus and intrusion detection systems that perform virus scanning, sweep scanning, or deep file inspection are not compatible with DS file access, particularly database file access.

   Antivirus and intrusion detection software can interfere with the normal process of opening and closing database working files. They may incorrectly mark such files as suspect to infection due to normal database processing, which involves opening and closing files in line with the database's internal logic.

   Prevent antivirus and intrusion detection systems from scanning database and changelog database files.

   At minimum, configure antivirus software to whitelist the DS server database files. By default, exclude the following file system directories from virus scanning:

   • /path/to/opendj/changelogDb/ (if replication is enabled)

     Prevent the antivirus software from scanning these changelog database files.

   • /path/to/opendj/db/

     Prevent the antivirus software from scanning database files, especially *.jdb files.

   Port blocking

   Antivirus and intrusion detection software can block ports that DS uses to provide directory services.

   Make sure that your software does not block the ports that DS software uses. For details, see "Limiting System and Administrative Access" in the Security Guide.

   Negative performance impact

   Antivirus software consumes system resources, reducing resources available to other services including DS servers.

   Running antivirus software can therefore have a significant negative impact on DS server performance. Make sure that you test and account for the performance impact of running antivirus software before deploying DS software on the same systems.

2. Install the server files in one of the following ways:

   • Install using the MSI package:

     1. Double-click the Windows installer package, DS-6.5.6.msi, to start the install wizard.

     2. In the Destination Folder screen, set the folder where the wizard installs the server files.

        The default location is under Program Files on the system drive. For example, if the system drive is C:, the default location is C:\Program Files (x86)\opendj\, as the native executable is a 32-bit application, though you can run the server in a 64-bit Java environment.

   • Use the Microsoft msiexec.exe command to install the files.

     The following example installs the server files under C:\opendj-6.5.6, writing an installation log file, install.log, in the current folder:

     C:\>msiexec /i DS-6.5.6.msi /l* install.log /q OPENDJ=C:\opendj-6.5.6
         

3. Start the installation.

   When installation is finished, the server files are found in the location you specified as Destination Folder. You must still run the setup command before you can use the server.

4. Run the setup command to set up the server.

Follow these steps for each DS directory server replica before enabling replication:

1. Download DS server software as described in "Downloading Directory Services Software".

2. Install the server files as described in "Installing Server Software Files".

3. Run the setup directory-server command with the --profile am-cts option.

   The following example prepares a first directory server replica for AM CTS data. With this configuration, the AM reaper manages token expiration and deletion. The base DN for CTS tokens is ou=famrecords,ou=openam-session,ou=tokens:

   $ /path/to/opendj/setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPasswordFile /tmp/rootuser.pwd \
    --monitorUserPasswordFile /tmp/monitor.pwd \
    --hostname opendj.example.com \
    --ldapPort 1389 \
    --ldapsPort 1636 \
    --httpsPort 8443 \
    --adminConnectorPort 4444 \
    --productionMode \
    --profile am-cts \
    --set am-cts/amCtsAdminPassword:str0ngEx4mplePa55word \
    --acceptLicense

   Notice that the profile configures appropriate access rights when you use the --productionMode option.

   AM does not require change number indexing. Disable it after setting up replication, as described in "To Disable Change Number Indexing" in the Administration Guide.

   For example configurations where DS manages token expiration and deletion, see "DS for AM CTS With Token Expiration" and "DS for AM CTS With Token Expiration (Session Capabilities Required)".

   The am-cts profile has the following parameters:

   amCtsAdminPassword (required)

   Password for the administrative account that AM uses to bind to the DS server.

   The bind DN for the account is uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,baseDn.

   Default: uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens

   backendName (optional)

   CTS backend database name.

   Default: amCts

   baseDn (optional)

   Base DN for CTS data.

   Default: ou=tokens

   tokenExpirationPolicy (optional)

   How CTS manages token expiration and deletion.

   Set this parameter to one of the following values:

   • am: AM CTS reaper manages token expiration and deletion.

   • am-sessions-only: AM CTS reaper manages SESSION token expiration and deletion. DS manages expiration and deletion for all other token types.

     AM continues to send notifications about session expiration and timeouts to agents.

   • ds: DS manages token expiration and deletion.

     AM session-related functionality is impacted and notifications are not sent.

   Default: am

Follow these steps for each DS directory server replica before enabling replication:

1. Download DS server software as described in "Downloading Directory Services Software".

2. Install the server files as described in "Installing Server Software Files".

3. Run the setup directory-server command with the --profile am-config option.

   The following example prepares a first directory server replica for AM configuration data. The base DN for configuration data in this example is ou=am-config. The bind DN for the AM configuration administrator is uid=am-config,ou=admins,ou=am-config:

   $ /path/to/opendj/setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPasswordFile /tmp/rootuser.pwd \
    --monitorUserPasswordFile /tmp/monitor.pwd \
    --hostname opendj.example.com \
    --ldapPort 1389 \
    --ldapsPort 1636 \
    --httpsPort 8443 \
    --adminConnectorPort 4444 \
    --productionMode \
    --profile am-config \
    --set am-config/amConfigAdminPassword:str0ngEx4mplePa55word \
    --acceptLicense

   The am-config profile has the following parameters:

   amConfigAdminPassword (required)

   Password for the administrative account that AM uses to bind to the DS server.

   The bind DN for the account is uid=am-config,ou=admins,baseDn.

   backendName (optional)

   Configuration store backend database name.

   Default: cfgStore

   baseDn (optional)

   Configuration store base DN.

   Default: ou=am-config

Follow these steps for each DS directory server replica before enabling replication:

1. Download DS server software as described in "Downloading Directory Services Software".

2. Install the server files as described in "Installing Server Software Files".

3. Run the setup directory-server command with the --profile am-identity-store option.

   The following example prepares a first directory server replica for AM identity data:

   $ /path/to/opendj/setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPasswordFile /tmp/rootuser.pwd \
    --monitorUserPasswordFile /tmp/monitor.pwd \
    --hostname opendj.example.com \
    --ldapPort 1389 \
    --ldapsPort 1636 \
    --httpsPort 8443 \
    --adminConnectorPort 4444 \
    --productionMode \
    --profile am-identity-store \
    --set am-identity-store/amIdentityStoreAdminPassword:str0ngEx4mplePa55word \
    --acceptLicense

   The am-identity-store profile has the following parameters:

   amIdentityStoreAdminPassword (required)

   Password for the administrative account that AM uses to bind to the DS server.

   The default bind DN for the account is uid=am-identity-bind-account,ou=admins,baseDn.

   Default: uid=am-identity-bind-account,ou=admins,ou=identities

   backendName (optional)

   User store backend database name.

   Default: amIdentityStore

   baseDn (optional)

   Base DN for identity data.

   Default: ou=identities

Follow these steps:

1. Download DS server software as described in "Downloading Directory Services Software".

2. Install the server files as described in "Installing Server Software Files".

3. Run the setup directory-server command with the --profile idm-repo option.

   The following example prepares a directory server for IDM repository data:

   $ /path/to/opendj/setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --hostname localhost \
    --ldapPort 31389 \
    --adminConnectorPort 34444 \
    --profile idm-repo \
    --set idm-repo/domain:forgerock.com \
    --acceptLicense

   The idm-repo profile has the following parameters:

   backendName (optional)

   IDM repository backend database name.

   Default: idmRepo

   domain (optional)

   Domain name translated to the base DN for IDM repository data.

   When you provide a domain name, the setup command translates it to a domain base DN. Each domain component becomes a dc=component RDN of the base DN. This profile then prefixes dc=openidm to the result. For example, the domain example.com translates to the domain base DN dc=openidm,dc=example,dc=com.

   Default: example.com

Follow these steps for each DS directory server replica before enabling replication:

1. Download DS server software as described in "Downloading Directory Services Software".

2. Install the server files as described in "Installing Server Software Files".

3. Run the setup directory-server command with the --profile ds-evaluation option:

   $ /path/to/opendj/setup \
    directory-server \
    --rootUserDN "cn=Directory Manager" \
    --rootUserPassword password \
    --monitorUserPassword password \
    --hostname opendj.example.com \
    --ldapPort 1389 \
    --enableStartTLS \
    --ldapsPort 1636 \
    --httpPort 8080 \
    --httpsPort 8443 \
    --adminConnectorPort 4444 \
    --profile ds-evaluation \
    --acceptLicense

   The ds-evaluation profile has the following parameters:

   backendName (optional)

   Example data backend database name.

   Default: dsEvaluation

   domain (optional)

   Domain name translated to the base DN for example data.

   When you provide a domain name, the setup command translates it to a domain base DN. Each domain component becomes a dc=component RDN of the base DN. For example, the default domain example.com translates to the domain base DN dc=example,dc=com.

   Default: example.com

The REST to LDAP gateway functions as a web application in a web application container. The REST to LDAP gateway runs independently of the LDAPv3 directory service. As an alternative to the gateway, you can configure HTTP access to a directory server as described in "To Set Up REST Access to User Data" in the Administration Guide.

Follow these steps to install the REST to LDAP gateway:

1. Prepare for installation as described in "Before You Install".

2. Deploy the .war file according to the instructions for your application server.

3. Edit the configuration files in the deployed gateway web application.

   At minimum adjust the following configuration settings in WEB-INF/classes/config.json:

   • primaryLDAPServers: Set the correct directory server host names and port numbers.

   • authentication: Set the correct simple bind credentials.

     The LDAP account used to authenticate needs to perform proxied authorization as described in "Configuring Proxied Authorization" in the Developer's Guide.

   The default sample configuration works with generated example data, and with the sample data imported when you set up the directory server for evaluation as shown in "To Set Up a Directory Server for Evaluation". If your data is different, then you must also change the JSON resource to LDAP entry mapping settings, described in "Mapping Configuration File" in the Reference.

   For details regarding the configuration, see "REST to LDAP Configuration" in the Reference.

   When connecting to a directory service over LDAPS or LDAP and StartTLS, you can configure the trust manager to use a file-based truststore for server certificates that the gateway should trust. This allows the gateway to validate server certificates signed, for example, by a certificate authority that is not recognized by the Java environment when setting up LDAPS or StartTLS connections. See "Preparing For Secure Communications" in the Administration Guide for an example of how to use the Java keytool command to import a server certificate into a truststore file.

4. (Optional) If necessary, adjust the log level.

   Log levels are defined in java.util.logging.Level .

   By default, the log level is set to INFO, and the gateway logs HTTP request-related messages. To have the gateway log LDAP request-related messages, set the log level to FINEST in one of the following ways:

   • If the REST to LDAP gateway runs in Apache Tomcat, edit WEB-INF/classes/logging.properties to set org.forgerock.opendj.rest2ldap.level = FINEST. For details on Tomcat's implementation of the logging API, see Logging in Tomcat.

     Messages are written to CATALINA_BASE/logs/rest2ldap.yyyy-MM-dd.log.

   • If the REST to LDAP gateway runs in Jetty, make sure you set the log level system property when starting Jetty: -Dorg.forgerock.opendj.rest2ldap.level=FINEST.

     Messages are written to the Jetty log.

5. Restart the REST to LDAP gateway or the application server to make sure the configuration changes are taken into account.

6. Make sure that the directory service is up, and then check that the gateway is connecting correctly.

   The following command reads Babs Jensen's entry through the gateway to a directory server set up for evaluation as shown in "To Set Up a Directory Server for Evaluation". In this example, the gateway is deployed under /rest2ldap:

   $ curl \
    --user bjensen:hifalutin \
    http://opendj.example.com:8080/rest2ldap/api/users/bjensen?_prettyPrint=true
   {
     "_id" : "bjensen",
     "_rev" : "<revision>",
     "_schema" : "frapi:opendj:rest2ldap:posixUser:1.0",
     "_meta" : { },
     "userName" : "bjensen@example.com",
     "displayName" : [ "Barbara Jensen", "Babs Jensen" ],
     "name" : {
       "givenName" : "Barbara",
       "familyName" : "Jensen"
     },
     "description" : "Original description",
     "contactInformation" : {
       "telephoneNumber" : "+1 408 555 1862",
       "emailAddress" : "bjensen@example.com"
     },
     "uidNumber" : "1076",
     "gidNumber" : "1000",
     "homeDirectory" : "/home/bjensen",
     "manager" : {
       "_id" : "trigden",
       "displayName" : "Torrey Rigden"
     }
   }
      

   If you generated example data, Babs Jensen's entry is not included. Instead, try a generated user such as http://user.0:password@opendj.example.com:8080/rest2ldap/api/users/user.0.

The DSML gateway functions as a web application in a web application container. The DSML gateway runs independently of the directory service. You configure the gateway to access a directory service by editing parameters in the gateway configuration file, WEB-INF/web.xml:

1. Prepare for installation as described in "Before You Install".

2. Deploy the .war file according to the instructions for your application server.

3. Edit WEB-INF/web.xml to ensure the parameters are correct.

   At minimum, make sure the correct values are set for ldap.host and ldap.port.

4. Restart the web application according to the instructions for your application server.

Follow these steps to upgrade a directory server:

1. Prepare for upgrade as described in "Before You Upgrade".

2. Stop the server.

3. Proceed to upgrade the server:

   • When upgrading a server installed from the cross-platform .zip:

     1. Unpack the new files over the old files as described in "Installing Server Software Files".

     2. Run the upgrade command, described in "upgrade — upgrade OpenDJ configuration and application data", to bring the server configuration and, if possible, user data up to date with the new software delivery.

        By default, the upgrade command runs interactively, requesting confirmation before making important configuration changes. For some potentially long-duration tasks, such as rebuilding indexes, the default choice is to defer the tasks until after upgrade.

        You can use the --no-prompt option to run the command non-interactively. In this case, the --acceptLicense option lets you accept the license terms non-interactively.

        When using the --no-prompt option, if the upgrade command cannot complete because it requires confirmation for a potentially long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.

   • When upgrading a server installed from native packages, use the system package management tools.

4. (Optional) When the mutable data mounted at runtime differs from that of the instance where you first run the upgrade command, upgrade only mutable data by running the command again with the --dataOnly option at runtime.

   The --dataOnly option can be useful when running the server in a Docker container, for example.

   This improvement is available when upgrading from DS 6.0.0 or later releases.

5. Start the upgraded server.

   At this point the upgrade process is complete. See the resulting upgrade.log file for a full list of operations performed.

   Replication updates the upgraded server with changes that occurred during the upgrade process.

   When you upgrade from version 3.0 or earlier, the upgrade process leaves the HTTP connection handler disabled.

   The newer configuration is not compatible with the previous configuration. You must rewrite your configuration according to "REST to LDAP Configuration" in the Reference, and then configure the server to use the new configuration. For details, see "RESTful Client Access Over HTTP" in the Administration Guide.

6. (Optional) If you disabled the server as a Windows service in order to upgrade, enable the server as a Windows service again as in the following example:

   C:\path\to\opendj\bat> windows-service.bat --enableService
      

For each server in the replication topology, follow these steps:

1. Direct client application traffic away from the server to upgrade.

2. Upgrade the server.

3. After upgrading DS 5.5 and earlier, grant the global administrator account the following privileges:

   bypass-lockdown

   monitor-read

   server-lockdown

   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 opendj.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
   -
      

4. Direct client application traffic back to the upgraded server.

Newer directory servers have updates to LDAP schemas that enable support for new features. The newer schemas are not all compatible with older servers.

When adding a new server to a replication topology with older servers and following the instructions in "Configuring Replication Settings" in the Administration Guide, also follow these recommendations:

1. Configure replication using the dsreplication command:

   • When adding a new server to a replication topology with 2.6.x servers, use the dsreplication command installed with a 2.6 server.

   • When adding a new server to a replication topology with 3.x and later servers, use the dsreplication command installed with a new server.

2. Use the --noSchemaReplication or the --useSecondServerAsSchemaSource option to avoid copying the newer schema to the older server.

   It is acceptable to copy the older schema to the newer server, though it prevents use of new features that depend on newer schema.

3. If applications depend on Internet-Draft change numbers, see "To Align Draft Change Numbers" in the Administration Guide.

Follow these steps:

1. Prepare for upgrade as described in "Before You Upgrade".

2. Stop the server.

3. Unpack the new files over the old files as described in "Installing Server Software Files".

4. Run the upgrade command, described in "upgrade — upgrade OpenDJ configuration and application data", to bring the server configuration data up to date with the new software delivery.

   By default, the upgrade command runs interactively, requesting confirmation before making important configuration changes.

   You can use the --no-prompt option to run the command non-interactively. In this case, the --acceptLicense option lets you accept the license terms non-interactively.

   When using the --no-prompt option, if the upgrade command cannot complete because it requires confirmation for a potentially long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.

5. Start the upgraded server.

   At this point the upgrade process is complete. See the resulting upgrade.log file for a full list of operations performed.

6. (Optional) If you disabled the server as a Windows service in order to upgrade, enable the server as a Windows service again as in the following example:

   C:\path\to\opendj\bat> windows-service.bat --enableService
      

If the server holds user data, consider it a directory server and see "Upgrading a Directory Server" instead.

1. Prepare for upgrade as described in "Before You Upgrade".

2. Stop the server.

3. Unpack the new files over the old files as described in "Installing Server Software Files".

4. Run the upgrade command, described in "upgrade — upgrade OpenDJ configuration and application data", to bring the server configuration data up to date with the new software delivery.

   By default, the upgrade command runs interactively, requesting confirmation before making important configuration changes.

   You can use the --no-prompt option to run the command non-interactively. In this case, the --acceptLicense option lets you accept the license terms non-interactively.

   When using the --no-prompt option, if the upgrade command cannot complete because it requires confirmation for a potentially long or critical task, then it exits with an error and a message about how to finish making the changes. You can add the --force option to force a non-interactive upgrade to continue in this case, also performing long running and critical tasks.

5. Start the upgraded server.

   At this point the upgrade process is complete. See the resulting upgrade.log file for a full list of operations performed.

6. (Optional) If you disabled the server as a Windows service in order to upgrade, enable the server as a Windows service again as in the following example:

   C:\path\to\opendj\bat> windows-service.bat --enableService
      

Follow these steps to remove software installed from the cross-platform .zip:

1. Log in as the user who installed and runs the server.

2. Stop replication as described in "To Stop Replication Permanently For a Replica" in the Administration Guide.

3. Stop the server.

   $ /path/to/opendj/bin/stop-ds --quiet
      

4. Delete the files manually:

   $ rm -rf /path/to/opendj
      

When you uninstall the Debian package from the command-line, the server is stopped if it is running:

1. Stop replication as described in "To Stop Replication Permanently For a Replica" in the Administration Guide.

2. Purge the package from your system:

   $ sudo dpkg --purge opendj
      

3. (Optional) Remove any remaining server configuration files and directory data:

   $ sudo rm -rf /opt/opendj
      

When you uninstall the RPM package from the command-line, the server is stopped if it is running:

1. Stop replication as described in "To Stop Replication Permanently For a Replica" in the Administration Guide.

2. Remove the package from your system:

   # rpm -e opendj
      

3. (Optional) Remove the server configuration files and any directory data:

   $ sudo rm -rf /opt/opendj
      

When you uninstall the files installed from the Windows installer package, only the installed files are removed:

1. Stop replication as described in "To Stop Replication Permanently For a Replica" in the Administration Guide.

2. Remove installed files in one of the following ways:

   • Use Windows Control Panel.

     1. Open Windows Control Panel and browse to the page to uninstall a program.

     2. Find the ForgeRock directory service in the list and uninstall it.

   • Use the msiexec command.

     The following command quietly removes installed files:

     C:\>msiexec /x DS-6.5.6.msi /q
          

3. (Optional) Manually remove the server configuration files and any directory data.