Installing the PingDirectoryProxy server
After you install the PingDirectory server, you can install and set up the PingDirectoryProxy server.
Click the following tabs to see instructions for the type of installation you want to perform.
-
In interactive mode
-
In non-interactive mode
Installing the server in interactive mode
The setup
command provides an interactive text-based interface to install a PingDirectoryProxy server instance.
Installing the first server
Steps
-
Change to the server root directory.
Example:
cd PingDirectoryProxy
-
Run the
setup
command.$ ./setup
-
Read the Ping Identity End-User License Agreement, and type
yes
to continue. -
Press Enter to accept the default of
no
in response to adding this new server to an existing topology.Would you like to add this server to an existing Directory Proxy Server topology? (yes / no) [no]:
-
Enter the fully qualified host name for this server, or press Enter to accept the default.
-
Create the initial root user DN for this server, or press Enter to accept the default.
-
Enter and confirm a password for this account.
-
To enable the PingDirectoryProxy server services (Configuration, Documentation, and Directory REST API) and Administrative Console over HTTPS, press Enter to accept the default. After setup, individual services can be enabled or disabled by configuring the HTTPS Connection Handler.
-
Enter the port on which the PingDirectoryProxy server should accept connections from HTTPS clients, or press Enter to accept the default.
-
Enter the port on which the PingDirectoryProxy server should accept connections from LDAP clients, or press Enter to accept the default.
-
The next two options enable LDAPS and StartTLS. Press Enter to accept the default (yes), or type no. If either are enabled, certificate options are required. To use the Java Keystore or the PKCS#12 keystore, the keystore path and the key PIN are required. To use the PKCS#11 token, only the key PIN is required.
-
Choose a certificate server option:
Choose from:
-
1) Generate self-signed certificate (recommended for testing purposes only)
-
2) Use an existing certificate located on a Java Keystore (JKS)
-
3) Use an existing certificate located on a PKCS#12 keystore
-
4) Use an existing certificate on a PKCS#11 token
-
-
Choose the desired encryption for 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, and you should 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.
-
-
To configure your PingDirectoryProxy server to use entry balancing, type
yes
, or accept the defaultno
. In an entry balancing environment, entries immediately beneath the balancing base DN are divided into disjoint subsets. Each subset of data is handled by a separate set of one or more directory server instances, which replicate this subset of data between themselves. Choosingyes
will enable more memory be allocated to the server and tools. -
Choose the option for the amount of memory to assign to this server.
-
Enter an option to set up the server with the current configuration, provide new parameters, or cancel.
-
After setup is complete, choose the next configuration option.
This server is now ready for configuration What would you like to do? 1) Start 'create-initial-proxy-config' to create a basic initial configuration (recommended for new users) 2) Start 'dsconfig' to create a configuration from scratch 3) Quit Enter choice [1]:
Installing additional servers
About this task
The setup
command provides an interactive text-based interface to install a PingDirectoryProxy server instance that clones a previously installed PingDirectoryProxy server instance.
Steps
-
Change to the server root directory.
Example:
cd PingDirectoryProxy
-
Use the
setup
command.$ ./setup
-
Read the Ping Identity End-User License Agreement, and type
yes
to continue. -
Enter
yes
in response to add this new server to an existing topology.Would you like to add this server to an existing Directory Proxy Server topology? (yes / no) [no]: yes
-
Enter the host name of the PingDirectoryProxy server from which configuration settings are copied during setup.
Enter the host name of the peer Directory Proxy Server from which you would like to copy configuration settings. [proxy.example.com]:
-
Type the port number of the peer PingDirectoryProxy server from which configuration settings are copied during setup. You can press Enter to accept the default port, which is 389.
Enter the port of the peer Directory Proxy Server [389]:
-
Enter the option corresponding to the type of connection you want to use to connect to the peer PingDirectoryProxy server.
How would you like to connect to the peer Directory Proxy Server? 1) None 2) SSL 3) StartTLS Enter choice [1]:
-
Type the root user DN of the peer PingDirectoryProxy server, or press Enter to accept the default (
cn=Directory Manager
), and then type and confirm the root user password.Enter the manager account DN for the peer Directory Proxy Server [cn=Directory Manager]: Enter the password for cn=Directory Manager:
-
Enter the host name of the new local PingDirectoryProxy server.
Enter the fully qualified host name or IP address of the local host [proxy.example.com]:
-
Choose the location of your new PingDirectoryProxy server instance or enter a new one.
-
Enter an option to set up the server with the current configuration, provide new parameters, or cancel.
-
After setup is complete, choose the next configuration option.
Installing the server in non-interactive mode
You can 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.
The following sections describe how to install the first PingDirectoryProxy server, how to install additional servers, and how to install the server with a truststore.
Installing the first server
About this task
The setup
command automatically chooses the maximum heap size. You can manually tune the maximum amount of memory devoted to the server’s process heap using the --maxHeapSize
option. The --maxHeapSize
option is only valid if the --entryBalancing
option is also present.
If you are using entry balancing, tune the amount of memory devoted to the PingDirectoryProxy server using the --entryBalancing
option as follows.
--entryBalancing --maxHeapSize 1g
The amount of memory allowed when using the --entryBalancing
option is calculated and depends on the amount of system memory available.
If you already configured a truststore, you can run the setup
command to enable security. The following example enables both SSL and StartTLS security. It also specifies a Java Keystore (JKS) and Truststore that define the server certificate and trusted CA. The passwords for the keystore files are defined in the corresponding .pin
files, where the password is written on the first line of the file. The values in the .pin
files are copied to the <server-root>/config
directory in the keystore.pin
file.
$ env JAVA_HOME=/ds/java ./setup \
--no-prompt --rootUserDN "cn=Directory Manager" \
--rootUserPassword "password" --ldapPort 389 \
--enableStartTLS --ldapsPort 636 \
--useJavaKeystore /path/to/devkeystore.jks \
--keyStorePasswordFile /path/to/devkeystore.pin \
--certNickName server-cert \
--useJavaTrustStore /path/to/devtruststore.jks \
--trustStorePasswordFile /path/to/devtruststore.pin \
--acceptLicense
The password to the private key within the keystore is expected to be the same as the password to the keystore. If this is not the case, you can define the private key password within the administrative console or using the |
Steps
-
Run the
setup
command with the--no-prompt
option.The command uses the default root user distinguished name (DN) (
cn=Director Manager
) with the specified--rootUserPassword
option. You must include the--acceptLicense
,--instanceName
, and--location
options or thesetup
command will generate an error message.$ env JAVA_HOME=/ds/java ./setup --no-prompt \ --rootUserDN "cn=Directory Manager" \ --rootUserPassword "password" --ldapPort 389 \ --acceptLicense \ --instanceName ds1 --location Denver
Installing additional servers
Steps
-
Run the
setup
tool with the--no-prompt
option.$ env JAVA_HOME=/ds/java ./setup --no-prompt \ --rootUserDN "cn=Directory Manager" \ --rootUserPassword "password" --ldapPort 1389 \ --localHostName proxy2.example.com \ --peerHostName proxy1.example.com --peerPort 389 \ --peerUseNoSecurity --acceptLicense --instanceName ds1 \ --location austin1
Installing the server with a truststore
About this task
If you’ve already configured a trust store, you can use the setup
command to enable security. The following example enables SSL security and specifies a Java KeyStore (JKS) and truststore that define the server certificate and trusted certificate authority (CA). The passwords for the keystore files are defined in the corresponding .pin
files, where the password displays on the first line of the file. The values in the .pin
files are copied to the server-root/config
directory in the keystore.pin
and truststore.pin
files.
Steps
-
To install a PingDirectoryProxy server with a truststore, run the
setup
command.$ env JAVA_HOME=/ds/java ./setup \ --no-prompt --rootUserDN "cn=Directory Manager" \ --rootUserPassword "password" \ --ldapPort 389 --ldapsPort 636 \ --useJavaKeystore /path/to/devkeystore.jks \ --keyStorePasswordFile /path/to/devkeystore.pin \ --certNickName server-cert \ --useJavaTrustStore /path/to/devtruststore.jks \ --acceptLicense \ --instanceName ds1 --location Denver In order to update the trust store, the password must be provided See 'prepare-external-server --help' for general overview Testing connection to ds-east-01.example.com:1636 ..... Done Testing 'cn=Proxy User,cn=Root DNs,cn=config' access ..... Created 'cn=Proxy User,cn=Root DNs,cn=config' Testing 'cn=Proxy User,cn=Root DNs,cn=config' access ..... Done Testing 'cn=Proxy User,cn=Root DNs,cn=config' privileges ..... Done Verifying backend 'dc=example,dc=com' ..... Done