PingDirectory

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 more dsconfig 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. If encryption-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 the setup 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 the setup 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. The userRoot 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.