Skip to main content
Last updated February 16, 2012 13:32, by ctissot

Running the OpenDS Directory Server

Once the OpenDS directory server has been built using either the default "package" or the "all" targets, a packaged version of the server will be placed in the package subdirectory. In particular, the package/OpenDS-0.1 directory should contain a "working" copy of the server. Alternately, you may download a pre-built version of the server.

The simplest way to get started is to run the shell script on UNIX-based systems or the setup.bat batch file on Windows. This will provide an interactive process that may prompt you for several key settings, including the LDAP port number, the base DN, and the root DN and password. It will also offer the ability to create the base entry or import an existing LDIF file.

To run the server, first try issuing the command:

bin/ --nodetach (on Unixes)
bat\start-ds.bat --nodetach (on Windows)

If everything is configured properly, then the OpenDS directory server should start and be able to handle client requests. If something is not configured properly, then the startup script or directory server itself should report an error with sufficient information to help you diagnose the problem.

One potential problem could arise if the JAVA_HOME environment variable is not set, or does not point to the root of a valid Java 5.0 or higher installation, in which setting that variable should help work around the problem. Alternately, using the JAVA_BIN variable to point to the absolute path of the Java executable may be helpful if you want to use a 64-bit JVM rather than the default 32-bit version (for example, "$JAVA_HOME/bin/sparcv9/java" or "$JAVA_HOME/bin/amd64/java").

In some cases, the version of the JVM specified by the JAVA_HOME variable is used by other applications but is not supported by OpenDS. You can specify a JVM installation that should be used only when executing the OpenDS administrative scripts by setting OpenDS-specific environment variables. To specify a JVM installation for OpenDS, do one of the following:

  • Set the OPENDS_JAVA_BIN environment variable (with the JAVA binary path)
  • Set the OPENDS_JAVA_HOME environment variable (with the JAVA installation path)
  • Update the contents of the lib/set-java-home file (if it exists) with the correct value of the JAVA installation path

Another useful environment variable that may be set is JAVA_ARGS. This may be used to pass arguments directly to the JVM. This may be used with standard options like "-Xms" and "-Xmx" to specify the amount of memory that may be used, or "-d64" to request a 64-bit JVM. However, there are some special JVM arguments that may be of particular interest when running the OpenDS directory server, including:

  • -ea -- Enables assertions within the JVM. This has a special meaning for the directory server because it will allow the server to operate in debug mode so that things like exception stack traces, protocol encoding and decoding output, and database interactions may be observed. Using Java assertions for this capability is very useful because it makes it possible to provide a single directory server build that contains both "production-ready" and "debug" versions of the code, but the presence of the debug code will not impact performance in any way if assertions are not enabled.
  • -Xrunhprof:cpu=samples,depth=10,doe=y -- Enables the HPROF profiler provided with Java so that it may be possible to identify potential hot-spots or areas of poor performance in the code. The set of arguments provided above are a good set for many purposes, but other settings may be useful in other cases. See this page for more information on using the HPROF utility to profile JVM CPU and memory usage.

If multiple JVM arguments are to be used, then they should all be included in the JAVA_ARGS environment variable separated by spaces. For example:

    JAVA_ARGS="-Xms1500m -Xmx1500m" 

This will set the minimum and maximum Java heap sizes to 1500 megabytes.

If --nodetach is given as a command-line argument, then the directory server will be started as a foreground process and will not detach from the console, which is helpful for debugging purposes. If it is not provided, then the server will start as a background process. Note that this argument is interpreted by the shell script rather than the directory server, and if it is provided, it must be the first argument.

The OpenDS directory server itself does allow for a few command-line arguments as well. The "-H" argument may be provided to see a listing of the arguments. There are a couple of other "undocumented" arguments that may be provided, including:

  • --fullVersion -- Displays detailed information about the directory server build and the environment in which it was created.
  • --systemInfo -- Displays information about the system on which the directory server is being run.

Both of these may provide useful information if it is necessary to get help to diagnose a problem with the server.

Please Confirm