Copyright © 2011-2012 ForgeRock AS
Last updated: February 21, 2012
This guide shows you how to install OpenDJ directory services. The OpenDJ project offers open source LDAP directory services in Java.
This guide shows you how to install, upgrade, and remove OpenDJ software. Unless you are planning a throwaway evaluation or test installation, read the Release Notes before you get started.
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 you need not read this guide right now. Instead, visit the download page, and click the link for the latest release to start the Java WebStart installer wizard directly from your browser.
This guide is written for anyone installing OpenDJ who plans to maintain directory services for client applications. Basic OpenDJ installation, especially using Java WebStart, can be simple and straightforward, particularly if you are already acquainted with directory services. Upgrading a running directory service without a single point of failure that can cause downtime requires at least a little thought and planning. Also, even in the case of basic installation, you may find yourself wanting more background about what you are doing.
This guide covers the install, upgrade, and removal (a.k.a. uninstall) procedures that you theoretically perform only once per version. This guide aims to provide you with at least some idea of what happens behind the scenes when you perform the steps.
You do not need to be an LDAP wizard to learn something from this guide, though a background in directory services and maintaining server software can help. You do need some background in managing servers and services on your operating system of choice. You can nevertheless get started with this guide, and then learn more as you go along.
Some items are formatted differently from other text, like
filenames, commands, and
literal values.
In many cases, sections pertaining to UNIX, GNU/Linux, Mac OS X, BSD,
and so forth are marked (UNIX). Sections pertaining to Microsoft Windows
might be marked (Windows). To avoid repetition, however, file system
directory names are often given only in UNIX format as in
/path/to/OpenDJ, even if the text applies to
C:\path\to\OpenDJ as well.
Core documentation, such as what you are now reading, aims to be technically accurate and complete with respect to the software documented. Core documentation therefore follows a three-phase review process designed to eliminate errors. The review process should slow authors down enough that documentation you get with a stable release has had time to bake fully.
Fully baked core documentation is available at docs.forgerock.org.
The OpenDJ Wiki regularly brings you more, fresh content. In addition, you are welcome to sign up and then edit the Wiki if you notice an error, or if you have something to share.
After you sign up at ForgeRock, you can also login to the Wiki and the issue database to follow what is happening with the project.
If you have questions regarding OpenDJ which are not answered by the documentation, there is a mailing list which can be found at https://lists.forgerock.org/mailman/listinfo/opendj where you are likely to find an answer.
You can join the IRC discussion in the #opendj room at irc.freenode.net.
The Wiki has information on how to check out OpenDJ source code. There is also a mailing list for OpenDJ development which can be found at https://lists.forgerock.org/mailman/listinfo/opendj-dev Should you want to contribute a patch, test, or feature, or want to author part of the core documentation, first have a look on the ForgeRock Community page at how to get involved.
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 download page, and click the first link on the left for the latest release to start the Java WebStart installer directly from your browser.
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. You might see an application error message such as this:
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.
URL-to-QuickSetup-InstallerThe URL-to-QuickSetup-Installer includes the
version of OpenDJ. For example,
URL-to-QuickSetup-Installer for version
2.5.0 is
http://download.forgerock.org/downloads/opendj/2.5.0/install/QuickSetup.jnlp.
The WebStart installer corresponds to what you start if you download OpenDJ-2.5.0.zip, unzip the file, and then run OpenDJ-2.5.0/setup (UNIX), OpenDJ-2.5.0\setup.bat (Windows), or QuickSetup.app (Mac OS X).
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.
This chapter covers what you need to consider before you run OpenDJ in your production 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. For best server performance, use at least version 1.6.0_22, which includes a major security fix for TLS as well.
OpenDJ replication requires that you use fully qualified domain names,
such as opendj.example.com.
Although you can use host names like my-laptop.local
for evaluation, in production and even in your lab, you must either ensure
DNS is set up correctly to provide fully qualified domain names, or set up
/etc/hosts (or
C:\Windows\System32\drivers\etc\hosts) to provide
fully qualified domain names.
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 (32-bit) or 1 GB memory (64-bit) 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 initial production data in LDIF format.[1] To get a more accurate estimate of the disk space needed, import a known fraction of the initial LDIF with OpenDJ configured as for production, run tests based on the estimated rates of change and growth in directory data, and then use the actual space used in the test environment to estimate how much disk space you need in production.
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 much 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. You base your network throughput needs on peak loads. Also base your storage throughput needs on peak loads.
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.
[1] OpenDJ stores data in Berkeley DB Java Edition, which is implemented as a rolling log. Berkeley DB appends updates to the end of the last log file, and marks old pages as deleted. Berkeley DB cleaner threads monitor the log file occupancy ratio, moving the data to get rid of old log files. Yet, with the default occupancy ratio of 50%, log files are cleaned only when they have less than 50% valid pages. As a result, the database can reach twice its initial size in the worst case.
Furthermore, when you import data from LDIF, OpenDJ stores not only the data, but also builds indexes for many of the attributes, resulting in some growth. Replication historical data and other operational attributes can also take up space.
Finally, it makes sense to leave space for growth in the database size as you modify and add entries over time.
This chapter covers command-line installation with additional information on setup options.
Make sure you have the correct Java environment installed.
$ java -version java version "1.6.0_24" Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334-9M3326) Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode)If your default Java environment is not appropriate, set
OPENDS_JAVA_HOMEto the path to the correct Java environment, or setOPENDS_JAVA_BINto 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-2.5.0.zip
Cross-platform OpenDJ directory server installation files
- opendj.zip
SVR4 format native packages for Solaris
- OpenDJ-2.5.0-DSML.war
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 instructions.
Typically you use the ulimit -a command 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.
See Preparing For Secure Communications in the Administration Guide for examples.
Unzip
OpenDJ-2.5.0.zipin the file system directory where you want to install the server.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-2.5.0directory.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.
To perform a non-interactive, silent installation, provide all the options to configure OpenDJ, and then also use the
-nor--no-promptoption.The setup command without the
--clioption 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-2.5.0/setup --cli OpenDJ 2.5.0 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-2.5.0/bin/statusSome 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 wait to add schema definitions 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-2.5.0/bin/status >>>> Specify OpenDJ 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: opendj.example.com Administrative Users: cn=Directory Manager Installation Path: /path/to/OpenDJ-2.5.0 Version: OpenDJ 2.5.0 Java Version: 1.6.0_24 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
Note
You can install OpenDJ in unattended and silent fashion by using the
setup command with the --no-prompt
option, specifying values for all the other options you require.
The OpenDJ DSML gateway functions as a web application located in a
web application container. The DSML gateway runs independently of 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.
Deploy
OpenDJ-2.5.0-DSML.waraccording to the instructions for your application server.Edit
WEB-INF/web.xmlto ensure the values forldap.hostandldap.portare correct.Restart the web application container according to the instructions for your application server.
By default, OpenDJ installs with options appropriate for evaluation, not for production.
You can change JVM options for the server in the QuickStart installer,
and alternatively using the Control Panel (Runtime Options > Java Settings),
or with the dsjavaproperties command after editing the
config/java.properties file.
- Heap size
The JVM heap size by default is either 256 MB or 1 GB.
In production, use at least a 2 GB heap (-Xms2G -Xmx2G).
- Server optimizations
Use -server to select the HotSpot Server VM.
- 32-bit vs. 64-bit
For heap sizes over 4 GB on 64-bit systems use -d64.
- Garbage collection
Use -XX:+UseConcMarkSweepGC to select the CMS garbage collector for low GC pause times.
- New generation size
If your directory handles high throughput, set the new generation size large enough for the JVM to avoid promoting short-lived objects into the old gen space (-XX:NewSize=512M).
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.
You must perform the upgrade procedure as the user who own 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, by running the shell script from the directory where the server is installed.
The opendj_patch4upgrade.sh script fixes a schema
issuethat prevents smooth upgrades from earlier server versions. You can
apply the script while the server is running.
(Windows) Follow these steps.
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 to Windows format.
Open the same file in Notepad.
Add the following
ldapSyntaxesdefinition verbatim, before the last blank line at the end of the file, leaving a blank line at the end of the file, and taking care not to add additional spaces at the end of the lines you add. 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.
You can upgrade from the graphical installer, or from the command line.
Login to a session where you can use a GUI as the user who owns the current OpenDJ server.
Download OpenDJ, and unzip the downloaded file.
Start the installer.
(WebStart) http://www.forgerock.org/downloads/opendj/2.5.0/install/QuickSetup.jnlp
(UNIX) Run OpenDJ-2.5.0/setup.
(Windows) Double-click
OpenDJ-2.5.0\setup.bat
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.
Follow the instructions in the QuickSetup wizard to complete the upgrade.
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
dn2idindex.
Login as the user who owns the current OpenDJ server.
Download the OpenDJ .zip file.
$ cd /tmp $ wget http://www.forgerock.org/downloads/opendj/2.5.0/OpenDJ-2.5.0.zipChange to the directory at the root of the server instance.
$ cd /path/to/OpenDJPass the .zip file name to the upgrade command.
$ ./upgrade --file /tmp/OpenDJ-2.5.0.zip See /var/....log for a detailed log of this operation. Initializing Upgrade ..... Done. Calculating Schema Customizations ..... Done. Calculating Configuration Customizations ..... Done. Backing Up Files ..... Done. Upgrading Components ..... Done. Preparing Customizations ..... Done. Applying Schema Customizations ..... Done. Applying Configuration Customizations ..... Done. Verifying Upgrade ..... Done. Stopping Directory Server ..... Done. Cleaning Up ..... Done. Recording Upgrade History ..... Done. See /path/to/OpenDJ/history/log for a detailed installation history. QuickUpgrade Completed Successfully. The OpenDJ installation at /path/to/OpenDJ has now been upgraded to version OpenDJ 2.5.0 (Build ID:buildId). See /var/....log for a detailed log of this operation.If you upgraded from OpenDS 2.2, use the rebuild-index command to rebuild the
dn2idindex for your suffixes.$ ./bin/rebuild-index --index dn2id --baseDN "dc=example,dc=com" ...Rebuild complete. Processed 160 entries in 0 seconds (average rate 401.0/sec)
Remove OpenDJ directory server software with the uninstall command.
(UNIX) Run OpenDJ-2.5.0/uninstall.
(Windows) Double-click
OpenDJ-2.5.0\uninstall.bat.(Mac OS X) Double-click
OpenDJ-2.5.0/Uninstall.app.When the process is finished, you might still have some files to remove manually.
Login as the user who installed and runs the server.
Run the OpenDJ-2.5.0/uninstall --cli command.
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 choices for the options. See uninstall --help for more information.
$ cd /path/to/OpenDJ-2.5.0 $ ./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-2.5.0/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-2.5.0
C
- Command-line installation, Installing OpenDJ From the Command Line
D
- Downloading OpenDJ, Installing OpenDJ With the QuickSetup Wizard, Installing OpenDJ From the Command Line
- DSML gateway, Installing OpenDJ From the Command Line
F
- File descriptor requirements, Installing OpenDJ From the Command Line
- Fully qualified domain name requirements, FQDNs For Replication
J
- Java
- Requirements, Java Environment, Installing OpenDJ From the Command Line
- Settings, Tuning JVM Options
M
- Memory requirements, Hardware
N
- Network requirements, Hardware
Q
- Quick install, Installing OpenDJ With the QuickSetup Wizard
S
- Silent installation, Installing OpenDJ From the Command Line
- Storage requirements, Hardware
U
- Uninstalling, Removing OpenDJ Servers
- Upgrading, Upgrading to OpenDJ 2.5.0