Installing the PingDirectory server
After you prepare your hardware and software systems, you can set up the PingDirectory server.
Click the following tabs to see instructions for the type of installation you want to perform.
-
In interactive mode
-
In non-interactive mode
-
As a lightweight server
-
On Windows
Installing the PingDirectory server in interactive mode
The setup
command provides an interactive text-based command-line interface to set up a PingDirectory server instance.
Before you begin
Review Pre-installation considerations.
Steps
-
Extract the distribution
.zip
archive, then go to the server root directory. -
Run the
setup
command.Example:
$ ./setup
If the JAVA_HOME environment variable is set to an older version of Java, explicitly specify the path to the Java Development Kit (JDK) installation during the setup process. Either set the <JAVA_HOME> environment variable with the JDK path or execute the
setup
command in a modified Java environment using theenv
command.Example:
$ env JAVA_HOME=/ds/java ./setup
-
Read the Ping Identity End-User License Agreement, and type
yes
to continue. -
Enter the fully qualified host name or IP address of the local host, or press Enter to accept the default.
-
Enter the distinguished name (DN) for the initial root user, or press Enter to accept the default (
cn=Directory Manager
). -
Enter and confirm the root user password.
-
Press Enter to enable the Ping Identity services (Configuration, Consent, Delegated Admin, Documentation, and Directory REST API) and Administrative Console over HTTPS.
After setup, you can enable or disable individual services and applications by configuring the HTTPS Connection Handler.
-
Enter the port on which the PingDirectory server will accept connections from HTTPS clients, or press Enter to accept the default.
-
Select the unencrypted LDAP connection setting option for this server or press Enter to accept the default (option 3).
Choose from:
-
Do not accept unencrypted LDAP connections
If you select this option, skip to step 12.
-
Accept unencrypted LDAP connections, but require StartTLS to secure all communication on those connections
-
Accept unencrypted LDAP connections, but optionally allow StartTLS to secure communication on those connections
-
Accept unencrypted LDAP connections and do not enable support for StartTLS
-
-
Enter the port on which the PingDirectory server will accept connections from LDAP clients, or press Enter to accept the default.
-
Select the desired setting for enabling LDAPS, or press Enter to accept the default.
If you do not enable LDAPS, skip to step 12.
-
Enter the port on which the PingDirectory server will accept connections from LDAPS clients, or press Enter to accept the default.
-
Select the certificate option for this server:
Choose from:
-
Generate self-signed certificate (recommended for testing purposes only).
-
Use an existing certificate located on a Java Keystore (JKS). Enter the keystore path and keystore PIN to use an existing certificate using a Java Keystore.
-
Use an existing certificate located on a PKCS12 keystore. Enter the keystore path and the keystore PIN to use an existing certificate using use a PKCS#12 keystore.
-
Use an existing certificate on a PKCS11 token. Enter only the keystore PIN to use the PKCS#11 token.
-
-
Choose the desired encryption for the directory data, backups, and log files from the choices provided:
Choose from:
-
Encrypt data with a key generated from an interactively provided passphrase. Using a passphrase (obtained interactively or read from a file) is the recommended approach for new deployments. Use the same encryption passphrase when setting up each server in the topology.
-
Encrypt data with a key generated from a passphrase read from a file.
-
Encrypt data with a randomly generated key. This option is primarily intended for testing purposes, especially when only testing with a single instance, or if you intend to import the resulting encryption settings definition into other instances in the topology.
-
Encrypt data with an imported encryption settings definition. This option is recommended if you are adding a new instance to an existing topology that has older server instances with data encryption enabled.
-
Do not encrypt server data.
-
-
Type the base DN for the data, or accept the default base DN of
dc=example,dc=com
. -
To choose an option to generate and import sample data, type the desired number of entries, or press Enter to accept the default number (10000).
This option is used for quick evaluation of the PingDirectory server. See Importing data if you want to use other options to initialize the server.
-
Choose the option to tune the amount of memory that will be consumed by the PingDirectory server and its tools.
-
Press Enter to prime or preload the database cache at startup before accepting client connections.
Priming the cache can increase the startup time for the PingDirectory server but provides optimum performance after startup has completed. This option is best used for strict throughput or response time performance requirements, or if other replicas in a replication topology can accept traffic while this PingDirectory server instance is starting. Priming the cache can also allow the server to collect information at startup that can be helpful in tuning garbage collection in the Java virtual machine (JVM). See JVM garbage collection using CMS.
-
Enter a location name for this server.
-
Enter a unique instance name for this server.
You cannot change the name after you set it.
-
Press Enter to accept the default (yes) to start the PingDirectory server after the configuration has completed.
Enter
no
if you want to configure additional settings or import data. Doing this keeps the server in shutdown mode. -
Select the desired option for populating the
config/tools.properties
file during setup, or press Enter to select the default (option 1).Choose from:
-
Do not populate the
tools.properties
file -
Populate the
tools.properties
file with properties needed to connect to the server -
Populate the
tools.properties
file with properties needed to connect to the server, and also include the initial root user DN as the default bind DN -
Populate the
tools.properties
file with propertiesThis fourth option, which is not recommended for production environments, populates the
tools.properties
file with properties needed to connect to the server, includes the DN for the initial root user as the default bind DN, and writes the password for that user to atools.pin
file for use as the default bind password. -
-
In the Setup Summary window, review your configuration details, and then select your setup option, or press Enter to select the default (option 1): file with properties needed to connect to the server, and also include the DN and password for the initial root user DN as the default bind DN and password
Choose from:
-
Set up the server with the parameters you have given
-
Provide the setup parameters again
-
Cancel the setup
-
Result
If you select option 1, your PingDirectory server is configured and initialized.
Installing the PingDirectory server in non-interactive mode
Run the setup
command in non-interactive mode to automate the installation process using a script or to run the command directly from the command line.
Non-interactive mode is useful when setting up production or QA servers with specific configuration requirements. There are two ways to set up a server in non-interactive mode:
-
Use the
setup
command with the required arguments. -
Use the
manage-profile setup
command to set up the server with a configured server profile. For more information, see Setting up the server with an existing encryption settings database and Server profiles.
Using the setup
command in non-interactive mode requires that all mandatory arguments be present for each command call. If there are missing or incorrect arguments, the setup
command fails and aborts the process. You must use a --no-prompt
option to suppress interactive output, except for errors, when running in non-interactive mode. You must also specify the port on which the server listens for connections:
-
--ldapPort
for connections from unencrypted LDAP clients -
--ldapsPort
for connections from TLS-encrypted LDAPs clients
Lastly, you must use the --acceptLicense
option. To view the license, run the bin/review-license
command.
To automatically tune the Java Virtual Machine (JVM) to use maximum memory, use the --maxHeapSize
option. To preload the database at startup, use the --primeDB
option.
To configure a deployment using a truststore, see Installing the PingDirectory server with a truststore.
To see a description of the available command-line options for the setup
command, use setup --help
.
Instructions for additional tasks you can perform while installing the server in non-interactive mode are provided in the following sections:
Enabling data encryption during non-interactive setup
Enabling data encryption during setup provides the strongest protection for your PingDirectory server.
About this task
Enabling encryption during setup ensures that all data written to the local DB backends, the changelog, and the replication database will be encrypted. Enabling encryption during setup also ensures that directory backups and LDIF exports are encrypted by default.
If you enable encryption after setup, then only entries created or updated after enablement will be encrypted, along with their corresponding records in the LDAP changelog and replication database. Any data and indexes that existed before enabling encryption remain unencrypted. To encrypt pre-existing local DB backends, export the data to LDIF and then re-import the LDIF file. To ensure future encryption of backups and LDIF exports, set the encrypt-backups-by-default
and encrypt-ldif-exports-by-default
system configuration properties to true
.
You can enable encryption in either interactive or non-interactive setup. For information on enabling encryption in interactive setup, see Installing the PingDirectory server in interactive mode.
To enable encryption non-interactively:
Steps
-
Run the
setup
command with one of the following arguments:Arguments Description --encryptDataWithRandomPassphrase
Creates an encryption settings definition for you with a strong, randomly generated key.
Because all instances in a topology should have the same encryption settings definitions, you should only use this argument for standalone instances or the first instance in a topology that will export its definitions to other instances.
--encryptDataWithPassphraseFromFile
Creates an encryption settings definition from a passphrase you specify. When using this argument, you must specify the path for the file containing the desired passphrase. If you are setting up multiple server instances, you should supply the same passphrase to ensure that definitions are consistent.
--encryptDataWithSettingsImportedFromFile
Imports one or more definitions from a file generated by the
encryption-settings export
command. When using this argument, you must specify the path for the file containing the passphrase that protects the encryption settings export.--encryptDataWithPreExistingEncryptionSettingsDatabase
Uses the encryption settings definitions from an encryption settings database that was created by another server instance. For more information, see Setting up the server with an existing encryption settings database.
Setting up the server with an existing encryption settings database
For added convenience, you can use an existing encryption settings database when setting up the server.
About this task
Setting up the server with an existing encryption settings database offers several advantages. You can:
-
Use an encryption settings database protected by an alternative cipher stream provider. Other methods for enabling data encryption during setup will create an encryption settings database that is protected by an unencrypted password stored in a local file, and anyone with access to the system during setup can decrypt that database’s contents. Alternative cipher stream providers offer stronger protection.
-
Enable data encryption restrictions during setup without the need to configure them later.
-
Use an encryption settings database that is frozen at the time of setup without needing to freeze it later.
If you provide a frozen encryption settings database with data encryption restrictions enabled, the definitions it contains are not exposed, even to server administrators.
To set up the server with an existing encryption settings database:
Steps
-
Run the
manage-profile setup
command on a server profile with the following properties:-
A
setup-arguments.txt
file including the--encryptDataWithPreExistingEncryptionSettingsDatabase
argument -
A
<server-root>/pre-setup/config/encryption-settings/encryption-settings-db
file representing the desired encryption settings database -
The
pre-setup-dsconfig
directory including one or moredsconfig
batch files containing changes needed to enable the cipher stream provider -
Any metadata files contained in the
<server-root>/pre-setup
directory that the cipher stream provider needs to access the encryption settings database.
The metadata files needed depend on the enabled cipher stream provider:
-
For the file-based cipher stream provider, use the file specified by the cipher stream provider’s
password-file
configuration property. Ifencryption-metadata-file
has a value, you must also include the file specified by that property. -
For the Amazon Key Management Service cipher stream provider, use the file specified by the cipher stream provider’s
encrypted-metadata-file
configuration property. -
For the Amazon Secrets Manager cipher stream provider, use the file specified by the cipher stream provider’s
encryption-metadata-file
configuration property. -
For the Azure Key Vault cipher stream provider, use the file specified by the cipher stream provider’s
encryption-metadata-file
configuration property. -
For the Conjur cipher stream provider, use the file specified by the cipher stream provider’s
encryption-metadata-file
configuration property. -
For the PKCS #11 cipher stream provider, use the file specified by the cipher stream provider’s
encryption-metadata-file
configuration property. -
For the Vault cipher stream provider, use the file specified by the cipher stream provider’s
vault-encrpytion-metadata-file
configuration property.
-
Installing the PingDirectory server with no security enabled
You can install a PingDirectory server in non-interactive mode in a production or QA environment with no security enabled.
Steps
-
Extract the distribution
.zip
file and, from the server root directory, run thesetup
command with the--no-prompt
option for non-interactive mode.The following example command uses the default root user distinguished name (
cn=Directory Manager
) with the specified--rootUserPassword
option. You must include the--acceptLicense
option or the setup generates an error message. The--instancename
option specifies the name for the server instance and should be unique across all instances in the topology. The--location
option specifies the name of the location in which the instance will be installed. You should generally configure your topology with a separate location for each data center to allow inter-server communication to prioritize servers in the same location over those in remote locations.Example:
$ ./setup --no-prompt --rootUserPassword "password" \ --baseDN "dc=example,dc=com" --acceptLicense --ldapPort 389 \ --instancename Instance1 --location Location1
Installing the PingDirectory server with a truststore
You can set up the PingDirectory server in non-interactive mode using an existing truststore for secure communication. This section assumes that you have an existing keystore and truststore with trusted certificates.
About this task
Steps
-
Unzip the distribution
.zip
file and, from the server root directory, run thesetup
command with the--no-prompt
option for non-interactive mode. The following example enables security using both SSL and StartTLS. It also specifies a JKS keystore and truststore that define the server certificate and trusted CA. TheuserRoot
database contents will remain empty and the base DN entry will not be created.Example:
$ ./setup --no-prompt --rootUserPassword "password" \ --baseDN "dc=example,dc=com" --ldapPort 389 --enableStartTLS \ --ldapsPort 636 --useJavaKeystore config/keystore.jks \ --keyStorePasswordFile config/keystore.pin \ --certNickName server-cert --useJavaTrustStore config/truststore.jks \ --acceptLicense --instancename Instance1 --location Location1
The password to the private key with the keystore is expected to be the same as the password to the keystore. If this is not the case, the private key password can be defined with the administrative console or the
dsconfig
command by editing the Trust Manager Provider standard configuration object.
Installing a lightweight server
Users who want to demo or test a lightweight version of the PingDirectory server on a memory-restricted machine can do so by removing all unused or unneeded configuration objects.
All configuration entries, whether enabled or not, take up some amount of memory to hold the definition and listeners that are notified of changes to those objects.
The configuration framework does not allow you to remove objects that are referenced, and in some cases if you have one configuration object referencing another but really do not need it, then you must first remove the reference to it. If you try to remove a configuration object that is referenced, both dsconfig
and the administrative console should prevent you from removing it and tell you what still references it.
Depending on your test configuration, some example configuration changes that you can make are as follows:
- Reduce the number of worker threads
-
Each thread has a stack associated with it, and that consumes memory. If you’re running a bare-bones server, then you probably do not have enough load to require a lot of worker threads.
$ bin/dsconfig set-work-queue-prop \
--set num-worker-threads:8 \
--set num-administrative-session-worker-threads:4 \
--set max-work-queue-capacity:100
- Reduce the percentage of JVM memory used for the JE database cache
-
When you have a memory-constrained environment, you want to ensure that as much memory as possible is available for use during processing and not tied up caching database contents.
$ bin/dsconfig set-backend-prop --backend-name userRoot --set db-cache-percent:5
- Disable the Dictionary Password Validator
-
The Dictionary Password Validator takes a lot of memory to hold its dictionary. Disabling it frees up some memory. You can delete the other password validators if not needed, such as Attribute Value, Character Set, Length-based, Repeated Characters, Similarity-based, or Unique Characters Password Validator.By default, the Dictionary Password Validator is referenced by the Secure Password Policy and the Root Password Policy. Therefore, you must first enter the following commands to update the password policies so that they no longer reference the validator.
$ bin/dsconfig set-password-policy-prop --policy-name "Secure Password Policy" --remove password-validator:Dictionary
$ bin/dsconfig set-password-policy-prop --policy-name "Root Password Policy" --remove password-validator:Dictionary
Then, you can disable the Dictionary Password Validator by using the following command:
$ bin/dsconfig delete-password-validator --validator-name Dictionary
- Disable the Commonly-Used Passwords Validator
-
The Commonly-Used Passwords Validator loads a relatively large dictionary of banned passwords into memory. By default, this validator is referenced by the Secure Password Policy and the Root Password Policy. Therefore, you must first enter the following commands to update the password policies so that they no longer reference the validator.
$ bin/dsconfig set-password-policy-prop --policy-name "Secure Password Policy" --remove password-validator:Commonly-Used Passwords
$ bin/dsconfig set-password-policy-prop --policy-name "Root Password Policy" --remove password-validator:Commonly-Used Passwords
Then, you can disable the Commonly-Used Passwords Validator by using the following command.
$ bin/dsconfig delete-password-validator --validator-name Commonly-Used Passwords
There are other items that can be removed, depending on your desired configuration. Contact your authorized support provider for assistance.
Installing the server on Windows
Use the setup.bat
script to install the server on Windows.
Before you begin
-
Make sure that you have set the
JAVA_HOME
environment variable to the location of your Java installation directory. For more information, see the "Java Runtime Environment" section in System requirements and Installing Java. -
Review Pre-installation considerations.
About this task
Complete the following steps to install the PingDirectory server.
Steps
-
Extract the distribution
.zip
file. -
In the Windows Command Prompt or PowerShell, go to the server’s root directory, and enter setup.bat.
-
Read the Ping Identity End-User License Agreement, and type
yes
to continue. -
Respond to the prompts. You can enter your own values or press Enter to accept the defaults.
If you want to see a detailed step-by-step description of the installation, see Installing the PingDirectory server in interactive mode starting with step 3.
-
In the setup summary, review your configuration details, and then select your setup option, or press Enter to select the default (option 1): Set up the server with the parameters you have given.
Result:
If you select option 1, your PingDirectory server is configured and initialized.
-
If you want to run the server as a Windows service, follow the instructions in Running the server as a Microsoft Windows service.