Child pages
  • OpenDJ Installation Guide
Skip to end of metadata
Go to start of metadata

Important

This documentation is not applicable to OpenDJ 2.6.0 or later releases. You must read the installation guide specific to the release you are upgrading to or installing, for example:

OpenDJ 2.6 Installation Guide, OpenDJ 3 Installation Guide

If you are working with the latest OpenDJ builds, see the OpenDJ draft documentation for the latest updates.

Unless you are planning a throwaway evaluation or test installation, read the appropriate Release Notes before you get started.

QuickSetup With Java WebStart

If you want only to try OpenDJ server software, and you do not plan to store any real or important data that you want to keep, then read only this section, or just try out installation without reading any further. Visit the project page, and click the first link on the left for the latest release to start the Java WebStart installer wizard directly from your browser. (Note: This option is not available at this time.)

Java WebStart lets you perform an installation of OpenDJ directory server starting with a click in your web browser, which can be a great way to try OpenDJ directory server for the first time, or to do a quick test installation. You can also upgrade an OpenDJ directory server through the WebStart installer.


Note - OpenDJ directory server relies on Java 6, so if your browser picks up an old installation of Java 5 for example, installation can fail. Currently also if you are on a Linux system, you need to get Sun Java 6 before you use OpenDJ directory server.

If the WebStart installation does not work in your browser, copy the WebStart URL, ending in QuickSetup.jnlp, from the OpenDJ download page. This is the first link in the list of links for a version of OpenDJ. Next, pass the link as an argument to the javaws command in a terminal window to start the installer.

$ cd /path/to/sun-java6/bin
$ ./javaws http://download.forgerock.org/downloads/opendj/2.4.5/install/QuickSetup.jnlp


Java WebStart launches the the QuickSetup wizard, and soon the Welcome screen appears.

Notice in the Server Settings screen that the default ports are 389 or 1389 for LDAP, 4444 for administrative access.

You can replicate data for high availability through the Topology Options screen.

Generate test data as part of server setup in the Directory Data screen.

For a real installation, adjust JVM options for your server, for example to allow the server to use more memory.

Opt to start your server when setup completes.

Finally, click Launch Control Panel to check your newly installed server. You can run OpenDJ-version/bin/control-panel (UNIX) or double-click OpenDJ-version\bat\control-panel.bat (Windows) if you want to launch OpenDJ Control Panel later.

Before You Install OpenDJ Software

This section covers what you need to consider before you run OpenDJ in production.

Java environment

OpenDJ software consists of pure Java applications. OpenDJ servers and clients therefore should run on any system with full Java support. OpenDJ is tested on a variety of operating systems, including Solaris SPARC and x86, various Linux distributions, Microsoft Windows, and Apple Mac OS X.

OpenDJ software requires Java 6, specifically at least the Java Standard Edition 6.0 (Sun version 1.6.0_10) runtime environment. ForgeRock recommends that you use at least version 1.6.0_27 due to security fixes.

System, network, and storage hardware

Thanks to the underlying Java platform, OpenDJ software runs well on a variety of processor architectures. Many directory service deployments meet their service-level agreements without the very latest or very fastest hardware.

For a server evaluation installation, you need 256 MB memory available to OpenDJ, with 100 MB free disk space for the software and a small set of sample data. For installation in production, read the rest of this section. You need at least 2 GB memory for OpenDJ and 4 times the disk space needed to house your initial production data.

OpenDJ directory servers almost always benefit from having enough system memory to cache all directory database files used. The reason is that reading from and writing to memory is typically must faster than reading from and writing to disk storage. For small data sets, you might not need extra memory. For large directories with millions of user directory entries, the system might not have enough slots to house sufficient memory to cache everything. To improve performance in such cases, one approach is to add solid state drives as an intermediate cache between memory and disk storage.

Processor architectures that provide fast single thread execution tend to help OpenDJ software deliver the lowest response times. For top end performance in terms both of sub-millisecond response times and also of throughput ranging from tens of thousands to hundreds of thousands of operations per second, the latest x86 architecture chips tend to perform better than others tested. Chip multi-threading (CMT) processors can do very well on directory servers providing pure search throughput, even though response times can be higher. Yet, CMT processors can be slow to absorb hundreds or thousands of write operations per second. Their slower threads get blocked waiting on resources, and thus are not optimal for topologies with high write throughput requirements.

On systems with fast processors and enough memory to cache directory data completely, the network can become a bottleneck. Even if a single 1 Gbit Ethernet interface offers plenty of bandwidth to handle your average traffic load, it can be too small for peak traffic loads. Furthermore, you might choose to use separate interfaces for administrative traffic and application traffic. To estimate what network hardware you need, calculate the size of the data you return to applications during peak load. For example, if you expect to have a peak load of 100,000 searches per second, each returning a full 8 KB entry, you need a network that can handle 800 MB/sec (3.2 Gbit/sec) throughput, not counting any other operations such as writes that result in replication traffic.

The storage hardware you choose must allow you to house not only directory data including historical data for replication, but also logs. If you choose to retain access logs for auditing purposes on a heavily used directory, dedicate storage for the log archives as well. Furthermore, your storage must also keep pace with the write throughput. Write throughput can arise from modify, modify DN, add, and delete operations, but it can also result from bind operations. Such is the case when the last successful bind is recorded, and when account lockout is configured, for example. In a replicated topology, not only does a directory service write entries to disk when they are changed, but a directory service also writes changelog data and historical information in order to resolve potential replication conflicts. In the same way that you consider your network throughput needs based on peak loads, also evaluate your peak storage throughput needs in order to select the storage hardware.


Note - OpenDJ servers do not currently support network file systems such as NFS for database storage. Provide sufficient disk space on local storage such as internal disk or an attached disk array.


Installing OpenDJ Directory Server On UNIX & Linux

This section covers command-line installation with additional information on setup options.

To prepare for installation

Make sure you have the correct Java environment installed. For example:

$ java -version
java version "1.6.0_29"
Java(TM) SE Runtime Environment (build 1.6.0_29-b11-402-11D50)
Java HotSpot(TM) 64-Bit Server VM (build 20.4-b02-402, mixed mode)

If your default Java environment is not appropriate, set OPENDS_JAVA_HOME to the path to the correct Java environment, or set OPENDS_JAVA_BIN to the absolute path of the java command. The latter environment variable is useful for example if you have both 32-bit and 64-bit versions of the Java environment installed, and want to make sure you use the 64-bit version.

Get the appropriate installation packages from the OpenDJ download page.

  • OpenDJ-version.zip contains the cross-platform OpenDJ directory server installation files
  • OpenDJ-version-DSML.war contains the cross-platform OpenDJ DSML gateway web archive

Allow OpenDJ software to use at least 64K (65536) file descriptors to operate properly.

How you set the maximum number of file descriptors per process depends on your system. Read your system documentation for information. Usually the ulimit -a command can be used to list current settings.

If you plan to install OpenDJ DSML gateway, make sure you have an appropriate application server installed.

If you plan to configure SSL or TLS to secure network communications between the server and client applications, get a properly signed digital certificate that your client applications recognize, such as one that fits with your organization's PKI or one provided by a recognized certificate authority.

To use the certificate during installation, the certificate must be located in a key store provided with Java (JKS, JCEKS, PKCS#12), or on a PKCS#11 token. To import a signed certificate into a key store, you can use the Java keytool command.

To install an OpenDJ directory server

Unzip OpenDJ-version.zip in the file system directory where you want to install the server.

Note - Unlike the web-based Quick Setup install, the setup command uses the directory where you unzipped the files as the installation directory, and does not ask you where to install OpenDJ. Therefore, if you want to install elsewhere on the file system, unzip the files in that location.

Run the setup --cli command found in the OpenDJ-version/ file system directory.

This command starts the setup program in interactive mode on the command line, prompting you for each option. Alternatively, use additional setup options to specify values for the options you choose during interactive mode, thus scripting the installation process. See setup --help and the notes below.

The setup command without the --cli option runs the Quick Start GUI installer with your local version of software, as does Java WebStart with a remote version of the software.

$ /path/to/OpenDJ-version/setup --cli

OpenDJ version
Please wait while the setup program initializes...

What would you like to use as the initial root user DN for the Directory
Server? [cn=Directory Manager]:
Please provide the password to use for the initial root user:
Please re-enter the password for confirmation:

On which port would you like the Directory Server to accept connections from
LDAP clients? [1389]:

On which port would you like the Administration Connector to accept
connections? [4444]:
Do you want to create base DNs in the server? (yes / no) [yes]:

Provide the base DN for the directory data: [dc=example,dc=com]:
Options for populating the database:

    1)  Only create the base entry
    2)  Leave the database empty
    3)  Import data from an LDIF file
    4)  Load automatically-generated sample data

Enter choice [1]: 3

Please specify the path to the LDIF file containing the data to import: \
/path/to/Example.ldif

Do you want to enable SSL? (yes / no) [no]:

Do you want to enable Start TLS? (yes / no) [no]:

Do you want to start the server when the configuration is completed? (yes /
no) [yes]:


Setup Summary
=============
LDAP Listener Port:            1389
Administration Connector Port: 4444
LDAP Secure Access:            disabled
Root User DN:                  cn=Directory Manager
Directory Data:                Create New Base DN dc=example,dc=com.
Base DN Data: Import Data from LDIF File (/path/to/Example.ldif)

Start Server when the configuration is completed


What would you like to do?

    1)  Set up the server with the parameters above
    2)  Provide the setup parameters again
    3)  Print equivalent non-interactive command-line
    4)  Cancel and exit

Enter choice [1]:

See /var/....log for a detailed log of this operation.

Configuring Directory Server ..... Done.
Importing LDIF file /path/to/Example.ldif ........... Done.
Starting Directory Server ........... Done.

To see basic server configuration status and configuration you can launch \
/path/to/OpenDJ-version/bin/status

Some notes on the options follow.

  • Initial root user DN: The root user Distinguished Name identifies a user who can perform all administrative and other operations allowed for the server, called root user due to the similarity to the UNIX root. The default, cn=Directory Manager, is a well-known name. If you have reason to be paranoid, you might opt for a different name.
  • Initial root user password: The root user will use simple, password-based authentication. Later you can limit cleartext access to avoid snooping, but for now use a strong password here unless this is a throwaway server.
  • LDAP port: The default for LDAP is 389. If you are working as a user who cannot open port 389, setup suggests 1389 as a default.
  • Administration port: This is the service entrance used to configure the server, run tasks, and so forth. The default is 4444.
  • Create base DNs: You need a base Distinguished Name, such as the default dc=example,dc=com, to add directory data. If you already have LDIF, the base DN you want is the distinguished name suffix common to all entries in your LDIF. You can provide more than one base DN if your data belongs in more than one suffix.
  • Import LDIF: LDAP data interchange format is the standard text format for expressing LDAP data. If you have LDIF already, one reason you might not want to import the data at the same time you install is because your data uses attributes not defined in the default schema, and so you will need to add those before you import.
    If you have a huge data set to import, you no doubt should also increase the import cache size, which you can do by passing a Java properties file. You might also prefer to perform data import offline.
  • Enable SSL and TLS: Enabling Secure Sockets Layer or Transport Layer Security lets you protect the network traffic between directory clients and your server.
    • SSL: SSL requires its own, separate port for LDAPS traffic. The default port for LDAPS is 636. If you are working as a user who cannot open port 636, setup suggests 1636 by default.
    • TLS: TLS lets you use StartTLS to negotiate a secure connection between a client and server, starting from the same server port you configured for LDAP.
    • X.509 certificates: The digital certificate you need for SSL and TLS can be self-signed and created on the fly. Trouble is, client applications view self-signed certificates like fake IDs, and so do not trust them. Self-signed certificates facilitate testing, but are not intended for production use.
  • Start the server: If you do not start the server during installation, you can use the bin/start-ds command later.

Run the status command to make sure your OpenDJ server is working as expected.

$ /path/to/OpenDJ-version/bin/status


>>>> Specify OpenDS LDAP connection parameters

Administrator user bind DN [cn=Directory Manager]:

Password for user 'cn=Directory Manager':

          --- Server Status ---
Server Run Status:        Started
Open Connections:         1

          --- Server Details ---
Host Name:                my-iMac.local
Administrative Users:     cn=Directory Manager
Installation Path:        /path/to/OpenDJ-version
Version:                  OpenDJ version
Java Version:             1.6.0_29
Administration Connector: Port 4444 (LDAPS)

          --- Connection Handlers ---
Address:Port : Protocol : State
-------------:----------:---------
--           : LDIF     : Disabled
0.0.0.0:161  : SNMP     : Disabled
0.0.0.0:636  : LDAPS    : Disabled
0.0.0.0:1389 : LDAP     : Enabled
0.0.0.0:1689 : JMX      : Disabled

          --- Data Sources ---
Base DN:     dc=example,dc=com
Backend ID:  userRoot
Entries:     160
Replication: Disabled

To install a DSML gateway

The OpenDJ DSML gateway functions as a web application located in a web application container. The DSML gateway runs independently of the OpenDJ directory server. You configure the gateway to access your directory service by editing the ldap.host and ldap.port parameters in the WEB-INF/web.xml configuration file.

  1. Deploy OpenDJ-version.war according to the instructions for your application server.
  2. Edit WEB-INF/web.xml to ensure the values for ldap.host and ldap.port are correct.
  3. Restart the web application container according to the instructions for your application server.

Installing OpenDJ Directory Server on Microsoft Windows

OpenDJ directory server can be installed to run as a Windows Service. The graphical install is identical to the WebStart version. This section covers options in more depth, however.

To prepare for installation

Make sure you have the correct Java environment installed.

If your default Java environment is not appropriate, set OPENDS_JAVA_HOME to the path to the correct Java environment, or set OPENDS_JAVA_BIN to the absolute path of the java.exe file. The latter environment variable is useful for example if you have both 32-bit and 64-bit versions of the Java environment installed, and want to make sure you use the 64-bit version.

Get the appropriate installation packages from the OpenDJ download page.

  • OpenDJ-version.zip contains the cross-platform OpenDJ directory server installation files
  • OpenDJ-version-DSML.war contains the cross-platform OpenDJ DSML gateway web archive

Allow OpenDJ software to use at least 64K (65536) file descriptors to operate properly.

On recent Windows systems, the default limit is much higher than 64K, so unless you have lowered the limit you can skip this step.

If you plan to install OpenDJ DSML gateway, make sure you have an appropriate application server installed.

If you plan to configure SSL or TLS to secure network communications between the server and client applications, get a properly signed digital certificate that your client applications recognize, such as one that fits with your organization's PKI or one provided by a recognized certificate authority.

To use the certificate during installation, the certificate must be located in a key store provided with Java (JKS, JCEKS, PKCS#12), or on a PKCS#11 token. To import a signed certificate into a key store, you can use the Java keytool command.

To install an OpenDJ directory server

Unzip OpenDJ-version.zip in the folder where you want to install the server.

Note - Unlike the web-based Quick Setup install, the setup command uses the directory where you unzipped the files as the installation directory, and does not ask you where to install OpenDJ. Therefore, if you want to install elsewhere on the file system, unzip the files in that location.

Double-click the setup.bat command found in the OpenDJ-version folder.

As the installer starts, you might have to allow the program access to communicate through the firewall by accepting the conditions that Windows displays.

Alternatively, use the setup --cli command and additional options to script the installation process. See setup --help and the notes throughout this procedure.

In the Server Settings screen, make decisions about the root account, and about port numbers including secure ports.

Some notes on the options follow.

  • Initial root user DN: The root user Distinguished Name identifies a user who can perform all administrative and other operations allowed for the server, called root user due to the similarity to the UNIX root. The default, cn=Directory Manager, is a well-known name. If you have reason to be paranoid, you might opt for a different name.
  • Initial root user password: The root user will use simple, password-based authentication. Later you can limit cleartext access to avoid snooping, but for now use a strong password here unless this is a throwaway server.
  • LDAP port: The default for LDAP is 389. If you are working as a user who cannot open port 389, setup suggests 1389 as a default.
  • Administration port: This is the service entrance used to configure the server, run tasks, and so forth. The default is 4444.

Enabling Secure Sockets Layer or Transport Layer Security lets you protect the network traffic between directory clients and your server.

For deployment, use a digital certificate signed by a recognized authority.

  • SSL: SSL requires its own, separate port for LDAPS traffic. The default port for LDAPS is 636. If you are working as a user who cannot open port 636, setup suggests 1636 by default.
  • TLS: TLS lets you use StartTLS to negotiate a secure connection between a client and server, starting from the same server port you configured for LDAP.
  • X.509 certificates: The digital certificate you need for SSL and TLS can be self-signed and created on the fly. Trouble is, client applications view self-signed certificates like fake IDs, and so do not trust them. Self-signed certificates facilitate testing, but are not intended for production use.

If you plan to replicate server data, choose your settings in the Topology Options screen.

You can import real data during installation.

Some notes on the options follow.

  • Create base DNs: You need a base Distinguished Name, such as the default dc=example,dc=com, to add directory data. If you already have LDIF, the base DN you want is the distinguished name suffix common to all entries in your LDIF. You can provide more than one base DN if your data belongs in more than one suffix.
  • Import LDIF: LDAP data interchange format is the standard text format for expressing LDAP data. If you have LDIF already, one reason you might not want to import the data at the same time you install is because your data uses attributes not defined in the default schema, and so you will need to add those before you import.

If you have a huge data set to import, you no doubt should also increase the import cache size, which you can do by passing a Java properties file. You might also prefer to perform data import offline.

Adjust the JVM options to cache as much directory data in memory as possible, depending on the volume of active data you have.

You can choose to start OpenDJ when install completes, and to run OpenDJ as a Windows Service.

If you do not start the server during installation, you can use the OpenDS-version\bat\start-ds.bat command later.

Following installation, open the Control Panel to make sure your OpenDJ server is working as expected.

Double-click OpenDS-version\bat\control-panel.bat if you closed the QuickSetup program too quickly.

Also check that OpenDJ is registered as a Windows Service if you chose that option.

To install a DSML gateway
The OpenDJ DSML gateway functions as a web application located in a web application container. The DSML gateway runs independently of the OpenDJ directory server. You configure the gateway to access your directory service by editing the ldap.host and ldap.port parameters in the WEB-INF\web.xml configuration file.

  1. Deploy OpenDJ-version-DSML.war according to the instructions for your application server.
  2. Edit WEB-INF\web.xml to ensure the values for ldap.host and ldap.port are correct.
  3. Restart the web application container according to the instructions for your application server.

Upgrading OpenDJ Directory Server

You can upgrade from an earlier version of OpenDJ either directly from within the Java WebStart installer, or on the command-line using the upgrade command.


Note - Upgrade from OpenDS 2.2 or OpenDJ 2.4 has been tested most thoroughly on Solaris, Mac OS X, and Linux. On Windows systems, export directory data to LDIF, start with a fresh installation of the OpenDJ software, and then import your data from LDIF.


Before You Upgrade

You must perform the upgrade procedure as the user who owns the OpenDJ server. Make sure you have the credentials to run commands as the user who owns the server.

Do a full backup of your current OpenDJ installation.

When running a server version earlier than OpenDJ 2.4.1 fix the upgrade schema by following the appropriate steps depending on your platform.

UNIX

Download and apply opendj_patch4upgrade.sh to your current server instance, by running the shell script from the root of the server instance.

$ cd /path/to/OpenDJ-version
$ sh /downloads/opendj_patch4upgrade.sh
/path/to/OpenDJ-version has been patched, you can proceed with the upgrade program now

The opendj_patch4upgrade.sh script fixes a schema issue that prevents smooth upgrades from earlier server versions. You can apply the script while the server is running.

Windows

  1. With the edit command line tool, open and then save OpenDJ-old-version\config\upgrade\schema.ldif.#### where #### represents four digits, such as 6677 for 2.4.0.
    This step changes the line endings from UNIX format to Windows format.
  2. Open the same file in Notepad.
  3. Add the following ldapSyntaxes definition all on the same line, just before the last blank line at the end of the file, taking care not to add additional spaces at the beginning or end of the line, and making sure the line is not split.
    If the result is not valid LDIF, your fix will fail.

ldapSyntaxes: ( 1.3.6.1.4.1.26027.1.3.6 DESC 'Collective Conflict Behavior' X-ENUM ( 'real-overrides-virtual' 'virtual-overrides-real' 'merge-real-and-virtual' ) X-SCHEMA-FILE '00-core.ldif' )

This fixes a schema issue that prevents upgrades from earlier server versions. You can make the change while the server is running.

Upgrading OpenDJ Directory Server

You can upgrade directly from the Quick Start installer, or from the command-line.

To upgrade with the Java WebStart installer

  1. Login to a session where you can use a GUI as the user who owns the current OpenDJ server.
  2. From a web browser with Java WebStart support, start the installer at http://download.forgerock.org/downloads/opendj/version/install/QuickSetup.jnlp. (Substitute the version you want for version in the preceding URL.)
    Alternatively, pass the installer URL to the javaws command.
  3. In the OpenDJ QuickSetup Welcome screen, select Upgrade Existing Server Instance, and make sure Server to Upgrade points to the current OpenDJ server before clicking Next.
  4. Follow the instructions in the QuickSetup wizard to complete the upgrade.
  5. If you upgraded from OpenDS 2.2, open the OpenDJ control panel, select Indexes > Rebuild Indexes..., and use the Rebuild Indexes dialog box to rebuild the dn2id index.

To upgrade with the command-line tool

  1. Login as the user who owns the current OpenDJ server.
  2. Download the OpenDJ-version.zip file.
  3. Change to the directory at the root of the server instance.
    $ cd /path/to/OpenDJ
  4. Pass the .zip file name to the upgrade command.
    $ ./upgrade -f /downloads/OpenDJ-version.zip
  5. If you upgraded from OpenDS 2.2, use the rebuild-index command to rebuild the dn2id index for your suffixes.
    $ ./bin/rebuild-index -i dn2id -b "dc=example,dc=com"

To upgrade replicated servers

Upgrade each server sequentially, as described above.

To upgrade the DSML gateway

Replace the gateweay web application with the newer version, as for a fresh installation.

Removing OpenDJ Software

Remove OpenDJ server software by using the uninstall command located in the file system directory holding the server instance.

To uninstall OpenDJ directory server on UNIX & Linux

Login as the user who installed and runs the server.

Run the uninstall --cli found in the OpenDJ-version file system directory.

This command starts the removal program in interactive mode on the command line, prompting you for each option. Alternatively, use additional uninstall options to specify values for the options you choose during interactive mode. See uninstall --help for more information.

The uninstall command without the --cli option runs the GUI version of the program.

$ cd /path/to/OpenDJ-version/uninstall --cli
Do you want to remove all components of the server or select the components to
remove?

    1)  Remove all components
    2)  Select the components to be removed

    q)  quit

Enter choice [1]:

The server is currently running and must be stopped before uninstallation can
continue.
Stop the Server and permanently delete the files? (yes / no) [yes]:

Stopping Directory Server ..... Done.
Deleting Files under the Installation Path ..... Done.

The Uninstall Completed Successfully.
To complete the uninstallation, you must delete manually the following files
and directories:
/path/to/OpenDJ-version/lib
See /var/....log for a detailed log of this operation.

If the command output tells you to delete files manually, then remove those remaining files to complete the process.

$ rm -rf /path/to/OpenDJ-version

To uninstall OpenDJ directory server on Microsoft Windows

  1. Double-click the uninstall.bat command found in the OpenDJ-version folder, and select what to remove in the initial screen.
  2. When the process is finished, you might still have some files to remove manually.

JVM and Cache Tuning Options

By default, OpenDJ installs with options appropriate for evaluation, not for production. You can change Java Virtual Machine options as part of the installation process.

  • Heap size max 256 MB or 1 GB by default depending on your JVM, should be at least 2 GB for production
  • For heaps over about 4 GB, -d64 has OpenDJ use the 64-bit JVM
  • DB cache at 10% by default, should be larger for production, for example, with 2 GB heap and 500 MB devoted to new gen, let the DB cache use 1 GB ($ dsconfig -n set-backed-prop --backend-name userRoot --set db-cache-percent:50)

Default Port Numbers

OpenDJ directory services use the following TCP/IP port numbers by default:

  • LDAP: 389 (1389 for non-root users)
  • LDAPS: 636 (1636 for non-root users)
  • Administration Connector: 4444
  • SNMP: 161 (if configured)
  • JMX: 1689
  • Replication: 8989
  • No labels