Getting Started with the UnboundID Identity Data Store

UnboundID Identity Data Store
	Return to Documentation Index

Getting Started with the UnboundID Identity Data Store

The UnboundID Identity Data Store is a high-performance, extensible, user-friendly, pure-Java server that is accessible via multiple protocols: LDAPv3, SCIM, and a REST based Identity API. This document provides a basic set of instructions that can help you start using the server.

Installing the UnboundID Identity Data Store

The UnboundID Identity Data Store will be distributed in a zip file. Extract the contents of this zip file in the location where you want the server to reside.

To provide the initial Identity Data Store configuration, simply run the setup command provided in the Identity Data Store installation root. This will attempt to use an existing Java installation to launch the setup utility, but if for some reason no Java installation cannot be found, or if is not at least Java SE version 6.0, then it may be necessary to set the JAVA_HOME environment variable in order to specify the location of the Java SE 6.0 or higher installation that you wish to use for the server.

If possible, a graphical interface will be displayed that will prompt you for the necessary information. Otherwise, an interactive text-based installation will be used. If you wish to force the text-based installation, then you can add the "--cli" argument to the command line (e.g., "./setup --cli"). The setup utility will allow you to configure a number of things, including:

The port number on which the server should listen for connections from LDAP clients.
Whether you wish to enable SSL and/or StartTLS within the server, and if so whether to create a self-signed certificate or to use an existing certificate in a Java keystore, PKCS#12 file, or PKCS#11 module.
The DN and password to use for the initial root user.
Whether to configure the server as a standalone instance or to be part of a replicated environment.
The base DN that you wish to use for your data.
Whether you wish to leave the database empty, create only the base entry, populate the database with sample data, or import data from an existing LDIF file.
Whether you wish to start the server after setup is complete.

Starting and Stopping the Identity Data Store

In order to start the UnboundID Identity Data Store on a UNIX-based system, run the bin/start-ds command. On Windows systems, use bat\start-ds.bat. The Identity Data Store will be started in the background, and control will be returned to the terminal once the server has been started. If you wish to keep the server running in the foreground, then you may add the "--nodetach" argument to the command line (e.g., "bin/start-ds --nodetach").

To stop the Identity Data Store on a UNIX-based system, use the bin/stop-ds command. On Windows systems, use bat\stop-ds.bat. If you wish to restart the server rather than stop it, then you may add the "--restart" argument to the command line (e.g., "bin/stop-ds --restart").

Utilities Provided with the Identity Data Store

A number of administrative utilities and other tools are included with the Identity Data Store. They are located in the bin directory on UNIX-based systems, and in the bat directory for Windows systems.

The primary utility for interacting with the Identity Data Store configuration is the dsconfig tool. This may be used in either interactive or non-interactive mode. The interactive mode provides a text-based menu-driven interface that allows you to view and manage the various components within the server, while the non-interactive is ideal for use in administrative scripts. Initially, it is recommended that you use the interactive mode to familiarize yourself with the configurable elements of the server, and the interactive mode does provide the ability to display the non-interactive command line that may be used to perform the same task. The interactive mode may be used by launching the dsconfig tool with no arguments. Use the --help argument to see what other options are available. Note that the Identity Data Store must be running in order to use the dsconfig tool, whether in interactive or non-interactive mode. For more information about the configurable components within the Identity Data Store, see the Configuration Reference Guide.

A number of other command-line utilities are provided with the server. In each case, the "--help" argument may be used to obtain information about how they may be used.

Administrative Utilities

backup -- Back up the contents of one or more backends.
restore -- Restore an existing backup.
import-ldif -- Import the contents of an LDIF file into a backend.
export-ldif -- Export the contents of a backend to an LDIF file.
dsreplication -- Configure a replication topology.
rebuild-index -- Generate and rebuild indexes within a backend.
verify-index -- Verify the integrity of existing indexes within a backend.

LDAP Client Utilities

ldapsearch -- Perform LDAP search operations.
ldapmodify -- Perform LDAP add, delete, modify, and modify DN operations.
ldapcompare -- Perform LDAP compare operations.
ldapdelete -- Perform LDAP delete operations.
ldappasswordmodify -- Modify user passwords.

LDIF Utilities

make-ldif -- Generate sample LDIF data based on a definition contained in a template.
ldifsearch -- Search the contents of an LDIF file.
ldifmodify -- Alter the contents of an LDIF file.
ldif-diff -- Compare the contents of two LDIF files.

Other Tools

create-rc-script -- Create an RC script that may be used to start the server automatically when the system is restarted (UNIX-based systems only).
base64 -- Perform base64 encoding and decoding.
dbtest -- Examine the contents of a backend database (for debugging purposes only).
encode-password -- Encode and verify passwords using their encoded representations.
manage-account -- Examine and modify password policy state information for a user.
status -- Obtain basic server status information.