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.
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.
Review Pre-installation considerations.
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.
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:
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.
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.Note:
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:
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.
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.
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.
- 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
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.
- 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.
Complete the following steps to install the PingDirectory server.