--- title: Install DS description: DS software has no GUI. Instead, DS software is bundled with command-line tools. component: pingds version: 7.2 page_id: pingds:getting-started:install canonical_url: https://docs.pingidentity.com/pingds/8.1/getting-started/install.html llms_txt: https://docs.pingidentity.com/pingds/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2024-09-30T17:31:29Z superseded_by: https://docs.pingidentity.com/pingds/8.1/getting-started/install.html 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, see [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. For details, check the [supported Java versions](https://docs.pingidentity.com/pingds/release-notes/requirements.html#prerequisites-java). 3. If you plan to run the Bash-based REST API examples, make sure the `curl` command is available. For details, see the [curl site](https://curl.haxx.se). ## Download DS software 1. If you do not have an account on [Ping Identity Backstage](https://backstage.forgerock.com), 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.2.5` directory from the folder you specify. The documentation shows the installation file system directory as `/path/to/opendj`. For example: * Bash * PowerShell * Zsh ```bash $ unzip ~/Downloads/DS-7.2.5.zip -d /path/to ``` ```powershell PS C:\path\to> Expand-Archive DS-7.2.5.zip C:\path\to ``` ```zsh % unzip ~/Downloads/DS-7.2.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 ```bash $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password $ export DEPLOYMENT_ID= ``` ```powershell PS C:\path\to> C:\path\to\opendj\bat\dskeymgr.bat create-deployment-id --deploymentIdPassword password ``` ```zsh % /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. 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 ```bash $ /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 ``` ```powershell PS C:\path\to> 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 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 ``` ```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 ``` > **Collapse: 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 ` > > 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 ```bash $ export PATH=/path/to/opendj/bin:${PATH} ``` ```powershell PS C:\path\to> $env:PATH += ";C:\path\to\opendj\bat" ``` ```zsh % export PATH=/path/to/opendj/bin:${PATH} ``` 5. Run the `status` command: * Bash * PowerShell * Zsh ```bash $ status \ --bindDn uid=admin \ --bindPassword password \ --hostname localhost \ --port 4444 \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin ``` ```powershell 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 ``` ```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 ``` 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.