Directory Services 7.3.5

Install DS

DS software has no GUI. Instead, DS software is bundled with command-line tools.

Because LDAP is standard, you can use third-party GUI tools to view and edit directory data. For a short list, refer to Try third-party tools.

Prepare for installation

  1. To evaluate DS software, make sure you have 10 GB free disk space for the software and for sample data.

  2. Verify that you have a supported Java version installed on your local computer.

    For details, check the supported Java versions.

  3. If you plan to run the Bash-based REST API examples, make sure the curl command is available.

    For details, refer to the curl site.

Download DS software

  1. If you do not have an account on Ping Identity Backstage, sign up for one.

  2. Sign in to Backstage.

  3. Find and download the latest Directory Services ZIP distribution.

Install a directory server

  1. Unzip the .zip file into the file system directory where you want to install the server.

    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-7.3.5-20240506155118-fba46f79e3510f00d8e7e5228e53672e49833f71 directory from the folder you specify.

    The documentation shows the installation file system directory as /path/to/opendj.

    For example:

    • Bash

    • PowerShell

    • Zsh

    $ unzip ~/Downloads/DS-7.3.5.zip -d /path/to
    PS C:\path\to> Expand-Archive DS-7.3.5.zip C:\path\to

    This example installs DS files with the cross-platform zip. When using the native installer, refer to Use the Windows MSI.

    % unzip ~/Downloads/DS-7.3.5.zip -d /path/to

  2. Generate and save a deployment ID using the deployment ID password of your choice.

    You will use this ID and its password when setting up DS servers in your deployment. The DS server uses the two together when generating other keys to protect shared secret keys and secure connections to other DS servers:

    • Bash

    • PowerShell

    • Zsh

    $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password
<deployment-id>
$ export DEPLOYMENT_ID=<deployment-id>
    PS C:\path\to> C:\path\to\opendj\bat\dskeymgr.bat create-deployment-id --deploymentIdPassword password
<deployment-id>
    % /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password
<deployment-id>
$ export DEPLOYMENT_ID=<deployment-id>

  3. Use the setup command to set up a server with the ds-evaluation profile. The evaluation profile includes Example.com sample data, more lenient access control, and some other features.

    You must have write access to the folder where you install DS.

    The following example runs the command non-interactively. Use the same settings shown here to be able to copy and paste the commands shown in this guide:

    • Bash

    • PowerShell

    • Zsh

    $ /path/to/opendj/setup \
 --serverId first-ds \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --rootUserDn uid=admin \
 --rootUserPassword password \
 --monitorUserPassword password \
 --hostname localhost \
 --ldapPort 1389 \
 --ldapsPort 1636 \
 --httpsPort 8443 \
 --adminConnectorPort 4444 \
 --replicationPort 8989 \
 --profile ds-evaluation \
 --start \
 --acceptLicense
Validating parameters..... Done
Configuring certificates..... Done
Configuring server... Done
Configuring profile DS evaluation..................... Done
Starting directory server............... Done

To see basic server status and configuration, you can launch
/path/to/opendj/bin/status
    PS C:\path\to> C:\path\to\opendj\setup.bat `
 --serverId first-ds `
 --deploymentId <deployment-id> `
 --deploymentIdPassword password `
 --rootUserDn uid=admin `
 --rootUserPassword password `
 --monitorUserPassword password `
 --hostname localhost `
 --ldapPort 1389 `
 --ldapsPort 1636 `
 --httpsPort 8443 `
 --adminConnectorPort 4444 `
 --replicationPort 8989 `
 --profile ds-evaluation `
 --start `
 --acceptLicense
Validating parameters..... Done
Configuring certificates..... Done
Configuring server..... Done
Configuring profile DS evaluation..................... Done
Starting directory server............... Done

To see basic server status and configuration, you can launch
C:\path\to\opendj\bat\status
    % /path/to/opendj/setup \
 --serverId first-ds \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --rootUserDn uid=admin \
 --rootUserPassword password \
 --monitorUserPassword password \
 --hostname localhost \
 --ldapPort 1389 \
 --ldapsPort 1636 \
 --httpsPort 8443 \
 --adminConnectorPort 4444 \
 --replicationPort 8989 \
 --profile ds-evaluation \
 --start \
 --acceptLicense
Validating parameters..... Done
Configuring certificates..... Done
Configuring server... Done
Configuring profile DS evaluation..................... Done
Starting directory server............... Done

To see basic server status and configuration, you can launch
/path/to/opendj/bin/status
    More about setup options

    The setup command shown here has the following options:

    --serverId first-ds

    A server identifier string that is unique across servers in your deployment.

    --deploymentId <deployment-id>

    The deployment ID is a random string generated using the dskeymgr command. It is paired with a deployment ID password, which is a random string that you choose, and that you must keep secret.

    Together, the deployment ID and password serve to generate the shared master key that DS servers in the deployment require for protecting shared encryption secrets. By default, they also serve to generate a private CA and keys for TLS to protect communication between DS servers.

    When you deploy multiple servers together, reuse the same deployment ID and password for each server installation.

    --deploymentIdPassword password

    This is a random string that you choose, and that you must keep secret. It is paired with the deployment ID.

    --rootUserDn uid=admin

    These options set the credentials for the directory superuser. This user has privileges to perform any and all administrative operations, and is not subject to access control. It is called the root user due to the similarity to the UNIX root user.

    The root user distinguished name (DN) identifies the directory superuser. In LDAP, a DN is the fully qualified name for a directory entry. The name used here is the default name: uid=admin.

    --monitorUserPassword password

    The monitor user has the privilege to read monitoring data. No --monitorUserDn option is set, so the DN defaults to uid=Monitor.

    --hostname localhost

    The server uses the fully qualified domain name for identification between replicated servers.

    Using localhost is a shortcut suitable only for evaluation on your local computer. In production, set this to the fully qualified domain name, such as ds.example.com.

    --ldapPort 1389

    The reserved port for LDAP is 389. Connections to this port can be secured with StartTLS, but are not secure by default.

    Examples in the documentation use 1389, which is accessible to non-privileged users.

    --ldapsPort 1636

    The reserved port for LDAPS is 636. Connections to this port are secured with TLS.

    Examples in the documentation use 1636, which is accessible to non-privileged users.

    --httpsPort 8443

    The reserved port for HTTPS is 443.

    HTTP client applications access directory data and monitoring information on this port.

    Examples in the documentation use 8443, which is accessible to non-privileged users.

    --adminConnectorPort 4444

    This is the service port used to configure the server and to run tasks. Connections to this port are secured with TLS.

    The port used in the documentation is 4444, which is the initial port suggested during interactive setup.

    --replicationPort 8989

    This is the service port used for replication messages.

    The port used in the documentation is 8989, which is the initial port suggested during interactive setup.

    --profile ds-evaluation

    The setup profile adds hard-coded entries for users like Babs Jensen, and groups like Directory Administrators. It also generates 100,000 sample LDAP user entries. All generated users have the same password, literally password. The generated user accounts are helpful for performance testing.

    All entries are added under the base DN dc=example,dc=com. A base DN is the suffix shared by all DNs in a set of directory data.

    LDAP entries are arranged hierarchically in the directory. The hierarchical organization resembles a file system on a PC or a web server, often visualized as an upside down tree structure, or a pyramid. In the same way a full path uniquely identifies each file or folder in a file system, a DN uniquely identifies each LDAP entry.

    Each DN consists of components separated by commas, such as uid=bjensen,ou=People,dc=example,dc=com. The base DN matches the final components of each DN in that branch of the directory. A DN’s components reflect the hierarchy of directory entries. The user entry with DN uid=bjensen,ou=People,dc=example,dc=com is under the organizational unit entry ou=People,dc=example,dc=com, which in turn is under dc=example,dc=com.

    Basic components have the form attribute-name=attribute-value, such as dc=com. In the example dc=com, the attribute dc (DNS domain component) has the value com. The DN dc=example,dc=com reflects the DNs domain name example.com.

    --start

    By default, the setup command does not start the server. This lets you complete any necessary configuration steps before starting the server for the first time, which may initiate the replication process.

    In this case, you have no further configuration to do. This option causes the server to start immediately.

    --acceptLicense

    Remove this option to read the license and then accept it interactively.

    Alternatively, you can run the setup command interactively by starting it without options.

  4. Add the DS tools to your PATH to avoid having to specify the full path for each command:

    • Bash

    • PowerShell

    • Zsh

    $ export PATH=/path/to/opendj/bin:${PATH}
    PS C:\path\to> $env:PATH += ";C:\path\to\opendj\bat"
    % export PATH=/path/to/opendj/bin:${PATH}

  5. Run the status command:

    • Bash

    • PowerShell

    • Zsh

    $ status \
 --bindDn uid=admin \
 --bindPassword password \
 --hostname localhost \
 --port 4444 \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin
    PS C:\path\to> status.bat `
 --bindDn uid=admin `
 --bindPassword password `
 --hostname localhost `
 --port 4444 `
 --usePkcs12TrustStore C:\path\to\opendj\config\keystore `
 --trustStorePassword:file C:\path\to\opendj\config\keystore.pin
    % status \
 --bindDn uid=admin \
 --bindPassword password \
 --hostname localhost \
 --port 4444 \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin

    The status command uses a secure connection to the administration port. To trust the server’s certificate, the command uses the server’s own truststore.

    Read the output that the status command displays.