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

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).

  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.
    $ bin/dsconfig set-connection-handler-prop \
      --handler-name "LDAP Connection Handler" \
      --remove listen-address: --add
  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.

    $ 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.

    $ kinit -p ds.admin
    $ bin/dsreplication enable \
      --host1 --port1 1389 --replicationPort1 1989 \
      --host2 --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.
    $ kinit -p replication.admin
    $ bin/dsreplication initialize \
      --hostSource --portSource 1389 \
      --hostDestination --portDestination 2389 \
      --baseDN dc=example,dc=com \
      --saslOption mech=GSSAPI \
      --saslOption authID=replication.admin@EXAMPLE.COM  \
  5. To delete the temporary userPassword from the replication.admin entry, create an LDIF file.

    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.
    $ ./ldapmodify --filename remove-password.ldif -o mech=GSSAPI
    -o \
      --saslOption useTicketCache=true \
      --hostname --port 1389 \
  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.

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