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(1), 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-4.0.0 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 if none is installed yet:

   $ 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 if none is installed yet:

   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 OpenDJ software.

   Before using OpenDJ 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 OpenDJ 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 OpenDJ 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 OpenDJ uses to provide directory services.

   Make sure that your software does not block the ports that OpenDJ 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 OpenDJ servers.

   Running antivirus software can therefore have a significant negative impact on OpenDJ server performance. Make sure that you test and account for the performance impact of running antivirus software before deploying OpenDJ 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-5.0.0.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-4.0.0, writing an installation log file, install.log, in the current folder:

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

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.

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 or with the sample content in Example.ldif. 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 holding data from Example.ldif. 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(1), 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. 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.

5. (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. 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 delivered with the 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.

Although the dsconfig command does not provide a way to change a database backend type, it is possible to make the change. The high-level steps are as follows:

1. Stop the directory server.

2. Export the data in the PDB backend to LDIF.

3. Update the configuration to change the backend type.

   See the LDIF modifications shown in "Example Script for Changing a PDB Backend to a JE Backend".

4. Import the data from LDIF into the new JE backend.

5. Start the directory server.

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(1), 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 ForgeRock OpenDJ in the list and uninstall it.

   • Use the msiexec command.

     The following command quietly removes installed files:

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

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