Joining a PingDirectoryProxy server to an existing PingDirectory server topology

PingDirectory server 8.0.0.0 supports the addition of PingDirectoryProxy server instances to the same topology as the PingDirectory server instances.

You can do this when the PingDirectoryProxy server instance is initially configured using either the setup utility (in either interactive or non-interactive mode) or the manage-profile setup command. You can do this later using the manage-topology add-server command.

Joining a topology with interactive setup

If you run setup without any arguments, it starts in interactive mode and prompts you for all of the necessary information. After you accept the license, the next prompt asks if you want to add the server to an existing Directory server topology.

If you have at least one PingDirectoryProxy server instance that is already in the desired topology, you can enter yes at this prompt and it walks you through the process of creating a new instance that is a copy of the existing instance (with all of the same configuration). You are then asked for the information needed to connect and authenticate to the existing PingDirectoryProxy server instance, as shown in the following example.

Do you accept the terms of this license agreement?  Enter 'yes' to accept,
'no' to reject, or press ENTER to display the next page of the agreement []: yes

Would you like to add this server to an existing Directory Proxy Server
topology? (yes / no) [no]: yes

Enter the host name of the peer Directory Proxy Server from which you would
like to copy configuration settings. [proxy2.example.com]: proxy1.example.com

Enter the LDAP port of the peer Directory Proxy Server [389]: 636

How would you like to connect to the peer Directory Proxy Server?

    1)  None
    2)  SSL
    3)  StartTLS

Enter option [1]: 2

Enter the manager account DN for the peer Directory Proxy Server [cn=Directory
Manager]: cn=Directory Manager

Enter the password for cn=Directory Manager:
The server presented the following certificate chain:

     Subject: CN=proxy1.example.com,O=Example Corp,C=US
     Valid From: Saturday, November 2, 2019 at 10:34:09 PM CDT
     Valid Until: Sunday, November 1, 2020 at 09:34:09 PM CST
     SHA-1 Fingerprint: 54:7f:6c:c1:99:73:c4:19:66:6e:da:4b:ee:a9:d5:62:24:2e:ba:41
     256-bit SHA-2 Fingerprint: 54:ce:59:c5:25:85:95:17:17:69:e0:5c:57:9e:ed:27:3d:af:9c:bd:34:51:c8:46:1e:e4:2f:31:13:18:31:ca
     -
     Issuer 1 Subject: CN=Example Certification Authority,O=Example Corp,C=US
     Valid From: Saturday, November 2, 2019 at 10:34:03 PM CDT
     Valid Until: Friday, October 28, 2039 at 10:34:03 PM CDT
     SHA-1 Fingerprint: 34:25:1f:8f:18:ff:a8:a9:ac:22:d3:d2:fc:bb:0b:4c:53:e1:8c:de
     256-bit SHA-2 Fingerprint: 51:69:1f:bb:cf:6f:1c:7a:e6:d4:6d:5a:01:c7:08:45:88:53:fc:75:f1:63:bb:ec:65:f1:1f:4e:26:f0:89:a3

Do you wish to trust this certificate?  Enter 'y' or 'n': y


Initializing ..... Done
Reading Peer Configuration ..... Done
Connecting to 'proxy1' ..... Done

However, cloning an existing installation isn’t possible when setting up the first PingDirectoryProxy server instance.

In this case, if you enter no at the prompt to join an existing PingDirectoryProxy server topology, setup asks if you want to join a PingDirectory server topology instead. If you enter yes, the process is basically the same as joining an existing directory server topology, and you are prompted for the information needed to connect and authenticate to a PingDirectory server instance in the topology. The primary difference is that you have to define the PingDirectoryProxy server configuration yourself, as shown in the following example.

Do you accept the terms of this license agreement?  Enter 'yes' to accept,
'no' to reject, or press ENTER to display the next page of the agreement []: yes

Would you like to add this server to an existing Directory Proxy Server
topology? (yes / no) [no]: no

Would you like to add this server to an existing PingDirectory server topology
to enable automatic backend server discovery? (yes / no) [no]: yes

Enter the host name of a PingDirectory server instance in the topology to
join. [proxy1.example.com]: ds1.example.com

Enter the LDAP port of a PingDirectory server instance in the topology to join
[389]: 636

How would you like to secure communication with the PingDirectory server

    1)  None
    2)  SSL
    3)  StartTLS

Enter option [1]: 2

Enter the DN used to bind to a PingDirectory server instance in the topology
to join [cn=Directory Manager]: cn=Directory Manager

Enter the password for cn=Directory Manager:
Testing connection to the existing PingDirectory server topology
The server presented the following certificate chain:

     Subject: CN=ds1.example.com,O=Example Corp,C=US
     Valid From: Saturday, November 2, 2019 at 10:44:26 PM CDT
     Valid Until: Sunday, November 1, 2020 at 09:44:26 PM CST
     SHA-1 Fingerprint: e1:4a:9e:dc:55:e8:40:78:9b:e1:1b:bd:3e:4c:85:fb:60:b4:27:35
     256-bit SHA-2 Fingerprint: 6e:92:c7:d6:66:c8:3d:2d:04:4c:f2:6a:cb:cb:51:5a:bf:f8:d6:18:0a:fc:64:d9:76:f4:4e:58:eb:c0:b8:b7
     -
     Issuer 1 Subject: CN=Example Certification Authority,O=Example Corp,C=US
     Valid From: Saturday, November 2, 2019 at 10:44:23 PM CDT
     Valid Until: Friday, October 28, 2039 at 10:44:23 PM CDT
     SHA-1 Fingerprint: 9a:b7:aa:a3:33:49:ce:b8:f3:7e:60:13:e0:3c:63:4b:8f:95:7a:f3
     256-bit SHA-2 Fingerprint: 04:07:86:f2:5c:e2:c1:88:fe:08:27:c1:1e:52:b0:4b:98:6e:a8:5c:85:fc:e0:d9:25:4f:07:ae:d7:0d:43:ba

Do you wish to trust this certificate?  Enter 'y' or 'n': y
Successfully connected to the existing PingDirectory server topology

Joining a topology with non-interactive setup

About this task

Interactive mode is a convenient method to get the server up and running when you’re just getting started, but the installation process for production deployments is generally scripted. For this process, non-interactive mode is a better choice and setup offers several useful arguments.

To join a topology with non-interactive setup:

Steps

Run setup:

Choose from:

Use the following arguments to join an existing PingDirectory server topology:
--existingDSTopologyHostName {address}

The address of a PingDirectory server instance in the topology to be joined.

--existingDSTopologyPort {port}

The port for communication with the PingDirectory server to retrieve information about the topology.

--existingDSTopologyUseSSL

Indicates that the communication with the PingDirectory server to retrieve information about the topology should be encrypted with SSL.

--existingDSTopologyUseStartTLS

Indicates that the communication with the PingDirectory server to retrieve information about the topology should be encrypted with the StartTLS extended operation.

--existingDSTopologyUseNoSecurity

Indicates that the communication with the PingDirectory server to retrieve information about the topology should be not be encrypted.

--existingDSTopologyUseJavaTruststore{path}

The path to a JKS trust store that has the information needed to trust the certificate presented by the PingDirectory server when using SSL or StartTLS.

--existingDSTopologyUsePkcs12Truststore{path}

The path to a PKCS #12 trust store that has the information needed to trust the certificate presented by the PingDirectory server when using SSL or StartTLS.

--existingDSTopologyTrustStorePassword{password}

The password needed to access the contents of the JKS or PKCS #12 trust store. A password is typically required when using a PKCS #12 trust store but is optional when using a JKS trust store.

--existingDSTopologyTrustStorePasswordFile{path}

The path to a file containing the password needed to access the contents of the JKS or PKCS #12 trust store.

--existingDSTopologyBindDN{path}

The DN of the account to use to authenticate to the PingDirectory server. This account must have full read and write access to the configuration and to manage the topology.

--existingDSTopologyBindPassword{password}

The password for the account to use to authenticate to the PingDirectory server.

--existingDSTopologyBindPasswordFile{path}
The path to a file containing the password to use to authenticate to the PingDirectory server.

For example, you can use a command similar to the following to set up a PingDirectoryProxy server instance in the same topology as a PingDirectory server instance.
$ ./setup --acceptLicense \ --licenseKeyFile PingDirectory.lic --maxHeapSize 2g \ --localHostName proxy1.example.com \ --skipHostnameCheck \ --instanceName proxy1 \ --location Austin \ --rootUserDN "cn=Directory Manager" \ --rootUserPasswordFile directory-manager-password.txt \ --ldapPort 389 \ --ldapsPort 636 \ --httpsPort 443 \ --enableStartTLS \ --useJavaKeyStore config/keystore \ --keyStorePasswordFile config/keystore.pin \ --certNickname server-cert \ --useJavaTrustStore config/truststore \ --trustStorePasswordFile config/truststore.pin \ --encryptDataWithPassphraseFromFile encryption-passphrase.txt \ --existingDSTopologyHostName ds1.example.com \ --existingDSTopologyPort 636 \ --existingDSTopologyBindDN "cn=Directory Manager" \ --existingDSTopologyBindPasswordFile directory-manager-password.txt \ --existingDSTopologyUseSSL \ --existingDSTopologyUseJavaTrustStore config/truststore \ --no-prompt

Use the following arguments to clone the configuration of an existing PingDirectoryProxy server instance, including joining the same topology as the existing instance:

--peerHostName{address}

The address of a PingDirectoryProxy server instance whose configuration should be cloned and whose topology should be joined.

--peerPort{port}

The port communication with the PingDirectoryProxy server to retrieve the configuration and topology information.

--peerUseSSL

Indicates that communication with the PingDirectoryProxy server to retrieve configuration and topology information should be encrypted with SSL.

--peerUseStartTLS

Indicates that communication with the PingDirectoryProxy server to retrieve configuration and topology information should be encrypted with the StartTLS extended operation.

--peerUseNoSecurity

Indicates that communication with the PingDirectoryProxy server to retrieve configuration and topology information should not be encrypted.

When using SSL or StartTLS to encrypt the communication, you also need to use one of the --useJavaTruststore or --usePkcs12Truststore arguments to specify the path to a trust store with the information needed to trust the certificate that is presented by the PingDirectoryProxy server.

The following is an example of a sample command to set up a new PingDirectoryProxy server as a clone of an existing PingDirectoryProxy server instance.

$ ./setup --acceptLicense \
     --licenseKeyFile PingDirectory.lic
     --maxHeapSize 2g \
     --localHostName proxy2.example.com \
     --skipHostnameCheck \
     --instanceName proxy2 \
     --location Austin \
     --rootUserDN "cn=Directory Manager" \
     --rootUserPasswordFile directory-manager-password.txt \
     --ldapPort 389 \
     --ldapsPort 636 \
     --httpsPort 443 \
     --enableStartTLS \
     --useJavaKeyStore config/keystore \
     --keyStorePasswordFile config/keystore.pin \
     --certNickname server-cert \
     --useJavaTrustStore config/truststore \
     --trustStorePasswordFile config/truststore.pin \
     --encryptDataWithPassphraseFromFile encryption-passphrase.txt \
     --peerHostName proxy1.example.com \
     --peerPort 636 \
     --peerUseSSL \
     --no-prompt

Joining a topology with manage-profile setup

About this task

You can use the manage-profile tool to set up an instance of the server from information contained in a server profile. This tool invokes setup and performs other tasks, such as applying configuration changes, installing schema and extensions, and adding files to the server root.

Steps

Place an appropriate set of arguments in the setup-arguments.txt file in the root directory of the profile, along with all of the other arguments that should be used when invoking setup.

Because manage-profile setup uses the setup tool in non-interactive mode, you should use the arguments listed in the previous section, including:

--existingDSTopologyHostName {address}
--existingDSTopologyPort {port}
--existingDSTopologyUseSSL
--existingDSTopologyUseStartTLS
--existingDSTopologyUseNoSecurity
--existingDSTopologyUseJavaTruststore {path}
--existingDSTopologyUsePkcs12Truststore {path}
--existingDSTopologyTrustStorePassword {password}
--existingDSTopologyTrustStorePasswordFile {path}
--existingDSTopologyBindDN {path}
--existingDSTopologyBindPassword {password}

--existingDSTopologyBindPasswordFile {path}

Unlike the setup utility, manage-profile setup does not support cloning an existing PingDirectoryProxy server instance, so the --peerHostName, --peerPort, and other related arguments cannot be included in the setup-arguments.txt file.

Run manage-profile setup.
If you have already set up an instance of the server, run manage-profile generate-profile to generate a profile from the information contained in that instance.

If the server was added to the topology during the setup process, the generated profile includes an appropriate set of arguments for joining the same topology.

Joining a topology with manage-topology add-server

Steps

Use the manage-topology add-server command to add a PingDirectoryProxy server instance to a topology after it has been installed.

You can only do this if the PingDirectoryProxy server instance is not already part of any other topology, since it is not possible to join two topologies together. This tool supports all of the normal arguments for connecting and authenticating to the local server instance, including the following:
- --hostname {address}
- --port {port}
- --useSSL
- --useStartTLS
- --trustStorePath {path}
- --trustStorePassword {password}
- --trustStorePasswordFile {path}
- --bindDN {dn}
- --bindPassword {password}
- --bindPasswordFile {path}

The manage-topology add-server command also allows the following arguments to provide information about a server in the topology to be joined:

--remoteServerHostname{address}

The address of a server in the topology to be joined.

--remoteServerPort{port}

The port for communication with the remote server.

--remoteServerConnectionSecurity\{noSecurity\|useSSL\|useStartTLS}

The type of security to use when communicating with the remote server. This value must be one ofuseSSL, to indicate that the communication should be encrypted with SSL,useStartTLS, to indicate that the communication should be encrypted with the StartTLS extended operation, ornoSecurityto indicate that the communication should not be encrypted.

--remoteServerBindDN{dn}

The DN of the account to use to authenticate to the remote server.

--remoteServerBindPassword{password}

The password for the account to use to authenticate to the remote server.

--remoteServerBindPasswordFile {path}

The path to a file containing the password for the account to use to authenticate to the remote server.

Example:

Use a command similar to the following to add a PingDirectoryProxy server to an existing PingDirectory server topology.

$ bin/manage-topology add-server \
     --hostname proxy1.example.com \
     --port 636 \
     --useSSL \
     --trustStorePath config/truststore \
     --bindDN "cn=Directory Manager" \
     --bindPasswordFile directory-manager-password.txt \
     --remoteServerHostname ds1.example.com \
     --remoteServerPort 636 \
     --remoteServerConnectionSecurity useSSL \
     --remoteServerBindDN "cn=Directory Manager" \
     --remoteServerBindPasswordFile directory-manager-password.txt