PingDirectory

Example deployment with non-interactive dsreplication

The following example creates a 4-server topology spanning two data centers.

In the example, the four servers are already installed and have locations Austin and Budapest defined.

When enabling or initializing servers, the --topologyFilePath option can be used with dsreplication to specify a file with a series of hosts and ports available in the topology that can be used as source servers. This option is used in place of specifying host 1, port 1.

When the hosts file is used for an enable or initialize action, the servers in the file are tried sequentially until the new server is successfully enabled or added. The rest of the servers in the file are ignored. This ensures that a host server is always available for replication. This file is generated with the manage-topology export command.

Deploying with non-interactive dsreplication

Steps

  1. To generate the sample data on the first server, use the make-ldif tool.

    Example:

    $ bin/make-ldif --templateFile config/MakeLDIF/example-10K.template \
      --ldifFile ldif/10K.ldif
  2. To import the data, select a server from which to import data and to be the source for future initialization to other servers, and then follow the import steps.

    1. Stop the server.

    2. To import the sample LDIF to the server, run import-ldif.

    3. Start the server.

      Example:

      $ bin/stop-server
      $ bin/import-ldif --backendID userRoot --ldifFile ldif/10K.ldif
      $ bin/start-server
  3. To enable replication, select a specific server and run dsreplication enable three times.

    For the first invocation, create the replication topology administrator with the name admin.

    Example:

    $ bin/dsreplication enable --host1 austin01.example.com --port1 1389 \
        --bindDN1 "cn=Directory Manager" --bindPassword1 password \
        --replicationPort1 8989 --host2 austin02.example.com --port2 1389 \
        --bindDN2 "cn=Directory Manager" --bindPassword2 password \
        --replicationPort2 8989 --baseDN dc=example,dc=com --adminUID admin \
        --adminPassword password --no-prompt
    
    $ bin/dsreplication enable --host1 austin01.example.com --port1 1389 \
        --bindDN1 "cn=Directory Manager" --bindPassword1 password \
        --replicationPort1 8989 --host2 budapest01.example.com --port2 1389 \
        --bindDN2 "cn=Directory Manager" --bindPassword2 password \
        --replicationPort2 8989 --baseDN dc=example,dc=com --adminUID admin \
        --adminPassword password --no-prompt
    
    $ bin/dsreplication enable --host1 austin01.example.com --port1 1389 \
        --bindDN1 "cn=Directory Manager" --bindPassword1 password \
        --replicationPort1 8989 --host2 budapest02.example.com --port2 1389 \
        --bindDN2 "cn=Directory Manager" --bindPassword2 password \
        --replicationPort2 8989 --baseDN dc=example,dc=com --adminUID admin \
        --adminPassword password --no-prompt
  4. To initialize the other servers, the dc=example,dc=com replicas, from the server you imported the data into with import-ldif, run dsreplication initialize.

    Example:

    For this example, initialize budapest02 from budapest01 to minimize the WAN transfers.

    $ bin/dsreplication initialize --hostSource austin01.example.com --portSource 1389 \
      --hostDestination austin02.example.com --portDestination 1389 \
      --adminUID admin --adminPassword password --baseDN dc=example,dc=com --no-prompt
    
    $ bin/dsreplication initialize --hostSource austin01.example.com --portSource 1389 \
      --hostDestination budapest01.example.com --portDestination 1389 \
      --adminUID admin --adminPassword password --baseDN dc=example,dc=com --no-prompt
    
    $ bin/dsreplication initialize --hostSource budapest01.example.com --portSource 1389 \
      --hostDestination budapest02.example.com --portDestination 1389 \
      --adminUID admin --adminPassword password --baseDN dc=example,dc=com --no-prompt
  5. To view the replication state, run dsreplication status.

    Example:

    $ bin/dsreplication status --adminPassword password --no-prompt --displayServerTable --showAll

Using dsreplication with SASL GSSAPI (Kerberos)

Before you begin

This example procedure assumes that you have configured SASL GSSAPI on all servers in the replication topology and that they are working properly.

About this task

The PingDirectory server’s utilities all support SASL GSSAPI options for systems using Kerberos as its main authentication mechanism. The following procedure shows how to use dsreplication with SASL GSSAP to set up a new replication.admin identity while enabling replication on a server.

A separate Kerberos identity is required to manage replication. Existing Kerberos credentials can be used to interact with the server when enabling replication and creating the new identity.

The new identity, such as replication.admin, must not exist as the cn or uid value under any public base distinguished name (DN).

Steps

  1. To set the LDAP Connection Handler to explicitly listen on the server’s host name address, run dsconfig with the set-connection-handler-prop option.

    Example:

    $ bin/dsconfig set-connection-handler-prop \
      --handler-name "LDAP Connection Handler" \
      --remove listen-address:0.0.0.0 --add listen-address:host.example.com
  2. To update the identity mapper to have cn=topology,cn=config included in the list of base DNs and to add the cn attribute to match attributes, run dsconfig with the set-identity-mapper-prop option.

    You must do this to map the admin account to the Kerberos realm.

    Example:

    $ bin/dsconfig set-identity-mapper-prop \
      --mapper-name "Regular Expression" \
      --add match-attribute:cn \
      --set "match-base-dn:cn=topology,cn=config" \
      --set match-base-dn:dc=example,dc=com
  3. To invoke replication enable, authenticate as the existing Kerberos authid, and then run dsreplication enable.

    No bind DNs and passwords are required to authenticate because you are using SASL binding. However, the new replication admin user requires a password at creation time, and you should use a strong random password. After SASL is working, you no longer have to provide this random password.

    You must use the ticket cache, so make sure you have properly authenticated as ds.admin from your local host and the ticket is not expired in the cache.

    Example:

    $ kinit -p ds.admin
    $ bin/dsreplication enable \
      --host1 server1.example.com --port1 1389 --replicationPort1 1989 \
      --host2 server2.example.com --port2 2389 --replicationPort2 2989 \
      --baseDN dc=example,dc=com \
      --adminUID replication.admin --adminPassword strongPassword \
      --saslOption1 mech=gssapi --saslOption1 authid=ds.admin@EXAMPLE.COM \
      --saslOption1 useTicketCache=true --saslOption1 requireCache=true \
      --saslOption2 mech=gssapi --saslOption2 authid=ds.admin@EXAMPLE.COM \
      --saslOption2 useTicketCache=true --saslOption2 requireCache=true
  4. To initialize data on the remote server, run dsreplication initialize.

    Example:

    $ kinit -p replication.admin
    $ bin/dsreplication initialize \
      --hostSource server1.example.com --portSource 1389 \
      --hostDestination server2.example.com --portDestination 2389 \
      --baseDN dc=example,dc=com \
      --saslOption mech=GSSAPI \
      --saslOption authID=replication.admin@EXAMPLE.COM  \
      --no-prompt
  5. To delete the temporary userPassword from the replication.admin entry, create an LDIF file.

    Example:

    In this example, the file is named remove-password.ldif and contains the following.

    dn: cn=replication.admin,cn=Administrators,cn=topology,cn=config
    changetype: modify
    delete: userPassword
  6. To apply the modifications, use the ldapmodify tool.

    Example:

    $ ./ldapmodify --filename remove-password.ldif -o mech=GSSAPI
    -o authid=replication.admin@example.com \
      --saslOption useTicketCache=true \
      --hostname host.example.com --port 1389 \
      --noPropertiesFile
  7. To check the topology’s status, run dsreplication status.

    After the admin account and mappers are created, you can use the --saslOption useTicketCache=true and --saslOption requireCache=true properties instead of a password for all dsreplication commands.

    Example:

    $ bin/dsreplication status \
      --saslOption mech=gssapi \
      --saslOption authid=replication.admin@EXAMPLE.COM \
      --saslOption useTicketCache=true --saslOption requireCache=true \
      --hostname host.example.com --port 1389 \
      --no-prompt