--- title: Install DS description: DS software has no GUI. Instead, DS software is bundled with command-line tools. component: pingds version: 8.1 page_id: pingds:getting-started:install canonical_url: https://docs.pingidentity.com/pingds/8.1/getting-started/install.html revdate: 2025-12-09T13:43:30Z keywords: ["Evaluation", "Install", "LDAP"] section_ids: before-you-start: Prepare for installation download: Download DS software install-server: Install a directory server --- # 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](further.html#further-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. Learn more in [Java requirements](https://docs.pingidentity.com/pingds/release-notes/requirements.html#prerequisites-java). 3. If you plan to [Learn HDAP](rest.html), make sure the `curl` command is available. For details, refer to the [curl site](https://curl.haxx.se). ## Download DS software 1. If you do not have an account on [Ping Identity Backstage](https://backstage.pingidentity.com), sign up for one. 2. Sign in to Ping Identity Backstage. 3. Find and download the latest PingDS ZIP distribution. ## Install a directory server | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Example commands in the documentation favor ease of use for evaluation, often including passwords. When you deploy DS in production, don't put secrets in commands, environment variables, or Java system properties. Don't sacrifice security for ease of use in production deployments.**Protect secrets you don't store in DS, such as keystore PINs or passwords for administrative commands. Put them in files or enter them interactively.**When you set file permissions correctly, the operating system grants access only to authorized accounts, such as the account to run the DS server process. Other accounts can't read the secret from a properly protected file.Including secrets in commands, environment variables, or Java system properties isn't secure:- Operating system processes can access the full command to run another process. Those processes can read any secrets you set in the command to run DS, for example. - Operating system processes can access the environment variables of the DS server process. - Monitoring software, command-line tools, and support tools like the `supportextract` command extract values of Java system properties and can share them with other systems.DS servers can [use an HSM for asymmetric keys](../security-guide/pki-hsm.html), but not for passwords or symmetric keys. DS servers don't store secrets in secret vaults or other external services. | 1. Unzip the `.zip` file into the file system directory where you want to install the server. The documentation shows the installation file system directory as `/path/to/opendj`. For example: * Bash * PowerShell * Zsh ```console $ unzip ~/Downloads/DS-8.1.0.zip -d /path/to ``` ```powershell Expand-Archive DS-8.1.0.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](../install-guide/install-files.html#install-files-msi). ```console $ unzip ~/Downloads/DS-8.1.0.zip -d /path/to ``` 2. Generate and save a deployment ID using the deployment ID password of your choice. 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 ```console $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password $ export DEPLOYMENT_ID= ``` ```powershell C:\path\to\opendj\bat\dskeymgr.bat create-deployment-id --deploymentIdPassword password set DEPLOYMENT_ID= ``` ```console $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password $ export 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 copy and paste the commands shown in these pages: * Bash * PowerShell * Zsh ```console $ /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 ``` > **Collapse: Show output** > > ``` > 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 > editable:dsBasePath[/path/to/opendj]/bin/status > ``` ```powershell C:\path\to\opendj\setup.bat ` --serverId first-ds ` --deploymentId ` --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 ``` > **Collapse: Show output** > > ``` > 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 > editable:dsWindowsBasePath[C:\path\to\opendj]\bat\status > ``` ```console $ /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 ``` > **Collapse: Show output** > > ``` > 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 > editable:dsBasePath[/path/to/opendj]/bin/status > ``` > **Collapse: More about setup options** > > The `setup` command shown here has the following options: > > * `--serverId first-ds` > > A server identifier string that's unique across servers in your deployment. > > * `--deploymentId ` > > The *deployment ID* is a random string generated using the `dskeymgr` command. It's paired with a *deployment ID password*, a random string you choose and 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 all administrative operations and isn't subject to access control. It's called the *root user* due to the similarity to the Linux root user. > > The root user distinguished name (DN) *(tooltip: \
> \

A name uniquely identifying an object within the hierarchy of a directory tree.\

> \
)* identifies the directory superuser (superuser) *(tooltip: \
> \

An account with full administration privileges to bypass access control evaluation, change access controls, and change administrative privileges. Analogous to the Linux root and Windows Administrator accounts.\

> \
)*. In LDAP, a DN is the fully qualified name for a directory entry. The default name is `uid=admin`. > > * `--monitorUserPassword password` > > The monitor user has the privilege to read monitoring data. This example doesn't set the `--monitorUserDn` option, 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`. Use StartTLS to secure connections to this port. The connections aren't 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`. Secure connections to this port 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 to configure the server, run tasks, and respond to administrative requests. It supports both LDAPS and HTTPS requests. > > Secure connections to this port 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. > > This profile adds entries under the base DN `dc=example,dc=com`. A base DN is the suffix shared by all DNs in a set of directory data. > > A directory arranges LDAP entries hierarchically. 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 that 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 doesn't start the server. This lets you complete any necessary configuration steps before starting the server for the first time, which may start 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. You can also 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 ```console $ export PATH=/path/to/opendj/bin:${PATH} ``` ```powershell $env:PATH += ";C:\path\to\opendj\bat" ``` ```console $ export PATH=/path/to/opendj/bin:${PATH} ``` 5. Run the `status` command: * Bash * PowerShell * Zsh ```console $ status \ --bindDn uid=admin \ --bindPassword password \ --hostname localhost \ --port 4444 \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --trustStorePassword:file /path/to/opendj/config/keystore.pin ``` ```powershell status.bat ` --bindDn uid=admin ` --bindPassword password ` --hostname localhost ` --port 4444 ` --trustStorePath C:\path\to\opendj\config\ --trustStoreType PKCS12 \keystore ` --trustStorePassword:file C:\path\to\opendj\config\keystore.pin ``` ```console $ status \ --bindDn uid=admin \ --bindPassword password \ --hostname localhost \ --port 4444 \ --trustStorePath /path/to/opendj/config/keystore \ --trustStoreType PKCS12 \ --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.