Using the command line

Edit online

You can issue the commands provided here at the command line to create a subtree.

This scenario assumes that you are creating a new replicated subtree and that only server1 contains any entry data. All other servers are newly installed, have a configured database, and have been started at least once for initialization purposes. The suffix of the replicated subtree must already be configured on other servers. (Be sure to read Synchronizing two-way cryptography between server instances , in the IBM® Security Directory Server documentation under the Administering section before you start the server instances.)
Note: The subtree that you want to create is shown here: 
dn: o=sample
objectclass: organization
objectclass: ibm-replicationContext
o: sample
If this entry already exists, then modify it to add objectclass=ibm-replicationContext instead of adding the entire entry.
  1. Create an ldif file suffix_update.ldif with the following information to add the objectclass=ibm-replicationContext to the already existing suffix or branch:
    dn: o=sample
changetype: modify
add: objectclass
objectclass: ibm-replicationContext
  2. Use the idsldapmodify command to modify the suffix entry on server1. On server1 issue the following command:
    idsldapmodify -D <adminDN> -w <adminPW> -i suffix_update.ldif

server1 and server2 are peer-master servers. That means that while they receive updates from each other, they only replicate entries received from clients. While both masters have the same entry content, only the server that has received the client request replicates the entry. Both masters are suppliers and consumers to each other and suppliers to the other servers.

You can use either an offline method or an online method.

To create the peer-masters (server1 and server2) for the subtree o=sample using offline method:
  1. Start servers server1 and server2 in configuration only mode. On each of the servers issue the command: 
    idsslapd -I <instance_name> -a
  2. If the administration server (idsdiradm) is not running for any instance, start idsdiradm: 
    idsdiradm -I <LDAP_instance>
  3. You must configure server1 and server2 to be peer servers. Use the idsldapadd command to add the following entry to the ibmslapd.conf file on server1 and server2. On server1 and server2 issue the following command: 
    idsldapadd -D <adminDN> -w <adminPW> -i<filename>
    where <filename> contains: 
    dn: cn=Master Server, cn=configuration
objectclass: ibm-slapdReplication
cn: Master Server
ibm-slapdMasterDN: cn=any
ibm-slapdMasterPW: secret123
    Note: It is critical that these entries be exactly the same on both servers because this example uses a credentials object that is shared on all the servers. The password is entered in cleartext, but is encrypted in the file. The ibm-slapdMasterDN must be unique and cannot be same as any already existing DN's.
  4. Stop server1 and server2. To stop the servers issue the following command on each of the servers: 
    idsslapd -I <instance_name> -k
    where <instance_name>is the name of the directory server instance you want to stop.
  5. Save the ibmslapd.conf files.
  6. At the computer where the master server, server1, is located, create a file to use for updates to the agreement information; for example mycredentialsfile, where mycredentialsfile contains: 
    dn: cn=replication,cn=IBMpolicies
objectclass: container
 
###Bind Credentials/method to peer server - replication agreement
###points to this.
dn: cn=simple,cn=replication,cn=IBMpolicies
objectclass: ibm-replicationCredentialsSimple
cn: simple
replicaBindDN: cn=any
replicaCredentials: secret123
description: Bind method of the peer master (server1)to the peer (server2)
    The replicaBindDN and replicaCredentials values should match ibm-slapdMasterDN and ibm-slapdMasterPW values respectively from master server entry in step 3.
  7. Issue the command: 
    idsldif2db -i<mycredentialsfile> -I <instance_name>
  8. Copy <mycredentialsfile> to the computer where server2 is located and issue the command: 
    idsldif2db -i<mycredentialsfile> -I <instance_name>
  9. At the computer where server1 is located create a file, <mytopologyfile>, where <mytopologyfile> includes the following setting:
    Note: Replace all occurrences of <server1-uuid> in the following files with the value of the ibm-slapdServerId attribute from the master server's cn=Configuration entry. This value is generated by the server the first time it is started. You can find it either by performing an idsldapsearch of the cn=Configuration entry or using the grep command on the ibmslapd.conf file, if you have an AIX®, Linux®, or Solaris system. Similarly, all occurrences of the <serverx-uuid> (where x represents 1 or 2) must be replaced with the value of the ibm-slapdServerId attribute from the respective server's cn=Configuration entry.
    dn: ibm-replicaGroup=default, o=sample
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default

dn: ibm-replicaServerId=<server1-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: <server1-uuid>
ibm-replicationServerIsMaster: true
cn: server1
description: server 1 (peer master) ibm-replicaSubentry 

dn: ibm-replicaServerId=<server2-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: <server2-uuid>
ibm-replicationServerIsMaster: true
cn: server2
description: server2 (peer master) ibm-replicaSubentry 

#server1 to server2 agreement
dn: cn=server2,ibm-replicaServerId=<server1-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicationAgreement
cn: server2
ibm-replicaConsumerId: <server2-uuid>
ibm-replicaUrl: ldap://server2:389
ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=IBMpolicies
description: server1(master) to server2(master) agreement

#server2 to server1 agreement
dn: cn=server1,ibm-replicaServerId=<server2-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicationAgreement
cn: server1
ibm-replicaConsumerId: <server1-uuid>
ibm-replicaUrl: ldap://server1:389
ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=IBMpolicies
description: server2(master) to server1(master) agreement
  10. To load this topology, issue the command: 
    idsldif2db -r no -i<mytopologyfile> -I <instance_name>
    where -r no prevents replication of the set of entries.
  11. At this point you might want to load additional data for your subtree.
    Note: Use the -r no flag to prevent replication of the set of entries.
  12. When you have finished loading the data, to be able to export the topology and any additional data for the replication context to populate the other servers, issue the command: 
    idsdb2ldif -s"o=sample" -o <mymasterfile.ldif> -I <instance_name> \
		-k <key seed> -t <key salt>
    Note: You must use the -I option if there is more than one instance. You must use the -k and -t options if keys on the server are not synchronized. See the idsdb2ldif command information in the Command Reference for more information.
    Attention: If you are exporting data that will be imported into an Advanced Encryption Standard (AES)-enabled server and if the two servers are not cryptographically synchronized, see Synchronizing two-way cryptography between server instances , for information about cryptographic synchronization of servers.

    When the source server (the server you are exporting data from) and the destination server (the server into which you will be importing the data) are using non-matching directory key stash files, and you specify the encryption seed and salt values of the destination server, any AES-encrypted data will be decrypted using the source server's AES keys, then re-encrypted using the destination server's encryption seed and salt values. This encrypted data is stored in the LDIF file.

    The encryption seed is used to generate a set of AES secret key values. These values are stored in a directory stash file and used to encrypt and decrypt directory stored password and secret key attributes. The encryption seed must contain only printable ISO-8859-1 ASCII characters with values in the range of 33 to 126, and must be a minimum of 12 and a maximum of 1016 characters in length. See ASCII characters from 33 to 126 , in the IBM Security Directory Server documentation under the Administering section for information about these characters.

    The encryption salt is a randomly generated value that is used to generate AES encryption keys. You can obtain the destination server's salt value by searching (using the idsldapsearch utility) the destination server's "cn=crypto,cn=localhost" entry. The attribute type is ibm-slapdCryptoSalt.

  13. Restart server1.
  14. Copy the <mymasterfile.ldif> file to the computer where server2 is located.
  15. On the computer where server2 is located, issue the following command: 
    idsldif2db -r no -i <mymasterfile.ldif> -I <instance_name>
    where -r no prevents replication of the set of entries. For large ldif data imports, use idsbulkload command (without -r no option).
  16. After completing the data import on server2, issue the command idsrunstats to optimize the table statistics:
    idsrunstats -I <instance_name>
  17. Start server2: 
    idsslapd -I <instance_name> -n
To create the peer-masters (server1 and server2) for the subtree o=sample using online method:
  1. Assumes the server server1 is already loaded with necessary data and is up and serving client applications. If required start the server1 with the command: 
    idsslapd -I <instance_name> -n
  2. Start server server2 in configuration only mode. On each of the servers issue the command: 
    idsslapd -I <instance_name> -a
  3. You must configure server1 and server2 to be peer servers. Use the idsldapadd command to add the following entry to the ibmslapd.conf file on server1 and server2. On server1 and server2 issue the following command: 
    idsldapadd -D <adminDN> -w <adminPW> -i<filename>
    where <filename> contains: 
    dn: cn=Master Server, cn=configuration
objectclass: ibm-slapdReplication
cn: Master Server
ibm-slapdMasterDN: cn=any
ibm-slapdMasterPW: secret123
    Note: It is critical that these entries be exactly the same on both servers because this example uses a credentials object that is shared on all the servers. The password is entered in cleartext, but is encrypted in the file. The ibm-slapdMasterDN must be unique and cannot be same as any already existing DN's.
  4. On server1, re-read the updated configuration into the running ibmslapd process. Issue the command on server1: 
    idsldapexop -D <adminDN> -w <adminPW> -op readconfig -scope entire
  5. Stop server2. To stop issue the following command on server2: 
    idsslapd -I <instance_name> -k
    where <instance_name> is the name of the directory server instance you want to stop.
  6. Save the ibmslapd.conf files on both server1 and server2.
  7. At the computer where the primary server, server1, is located, create a file to use for updates to the agreement information; for example mycredentialsfile, where mycredentialsfile contains: 
    dn: cn=replication,cn=IBMpolicies
objectclass: container
 
###Bind Credentials/method to peer server - replication agreement
###points to this.
dn: cn=simple,cn=replication,cn=IBMpolicies
objectclass: ibm-replicationCredentialsSimple
cn: simple
replicaBindDN: cn=any
replicaCredentials: secret123
description: Bind method of the peer master (server1)to the peer (server2)
    The replicaBindDN and replicaCredentials values should match ibm-slapdMasterDN and ibm-slapdMasterPW values respectively from master server entry in step 3.
  8. Issue the command on server1: 
    idsldapadd -D <adminDN> -w <adminPW> -i<mycredentialsfile>
  9. Copy <mycredentialsfile> to the computer where server2 is located and issue the command on server2: 
    idsldif2db -i<mycredentialsfile> -I <instance_name>
  10. At the computer where server1 is located create a file, <mytopologyfile>, where <mytopologyfile> includes the following setting:
    Note: Replace all occurrences of <server1-uuid> in the following files with the value of the ibm-slapdServerId attribute from the master server's cn=Configuration entry. This value is generated by the server the first time it is started. You can find it either by performing an idsldapsearch of the cn=Configuration entry or using the grep command on the ibmslapd.conf file, if you have an AIX, Linux, or Solaris system. Similarly, all occurrences of the <serverx-uuid> (where x represents 1 or 2) must be replaced with the value of the ibm-slapdServerId attribute from the respective server's cn=Configuration entry.
    dn: ibm-replicaGroup=default, o=sample
objectclass: top
objectclass: ibm-replicaGroup
ibm-replicaGroup: default

dn: ibm-replicaServerId=<server1-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: <server1-uuid>
ibm-replicationServerIsMaster: true
cn: server1
description: server 1 (peer master) ibm-replicaSubentry

dn: ibm-replicaServerId=<server2-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicaSubentry
ibm-replicaServerId: <server2-uuid>
ibm-replicationServerIsMaster: true
cn: server2
description: server2 (peer master) ibm-replicaSubentry

#server1 to server2 agreement
dn: cn=server2,ibm-replicaServerId=<server1-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicationAgreement
cn: server2
ibm-replicaConsumerId: <server2-uuid>
ibm-replicaUrl: ldap://server2:389
ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=IBMpolicies
description: server1(master) to server2(master) agreement
ibm-replicationOnHold: TRUE

#server2 to server1 agreement
dn: cn=server1,ibm-replicaServerId=<server2-uuid>,ibm-replicaGroup=default,o=sample
objectclass: top
objectclass: ibm-replicationAgreement
cn: server1
ibm-replicaConsumerId: <server1-uuid>
ibm-replicaUrl: ldap://server1:389
ibm-replicaCredentialsDN: cn=simple,cn=replication,cn=IBMpolicies
description: server2(master) to server1(master) agreement
ibm-replicationOnHold: TRUE
  11. To load this topology, on server1, issue the command: 
    idsldapadd -D <adminDN> -w <adminPW> -l -i<mytopologyfile>
    where -l option prevents replication of the set of entries.
  12. Now the peer server1 is aware of the peer server2 and keeps track of all changes (updates) in the suspended replication queue.
  13. If you need the data synchronization to be successful, it is important to quiesce the server1 to make it read only until the data extract is completed. To quiesce the server1 issue the command:
    idsldapexop -D <adminDN> -w <adminPW> -op quiesce -rc o=sample
    If you need the server1 to function in read and write mode, there may be a set of replicated changes that are also going to be extracted into ldif file via idsdb2ldif.
  14. Export the server1 data (which also includes replication topology information) for the replication context, issue the command on server1: 
    idsdb2ldif -s "o=sample" -o <server1data.ldif> -I <instance_name> \
		-k <key seed> -t <key salt>
    Note: You must use the -I option if there is more than one instance. You must use the -k and -t options if keys on the server are not synchronized. See the idsdb2ldif command information in the Command Reference for more information.
    Attention: If you are exporting data that will be imported into an Advanced Encryption Standard (AES)-enabled server and if the two servers are not cryptographically synchronized, see Synchronizing two-way cryptography between server instances , for information about cryptographic synchronization of servers.

    When the source server (the server you are exporting data from) and the destination server (the server into which you will be importing the data) are using non-matching directory key stash files, and you specify the encryption seed and salt values of the destination server, any AES-encrypted data will be decrypted using the source server's AES keys, then re-encrypted using the destination server's encryption seed and salt values. This encrypted data is stored in the LDIF file.

    The encryption seed is used to generate a set of AES secret key values. These values are stored in a directory stash file and used to encrypt and decrypt directory stored password and secret key attributes. The encryption seed must contain only printable ISO-8859-1 ASCII characters with values in the range of 33 to 126, and must be a minimum of 12 and a maximum of 1016 characters in length. See ASCII characters from 33 to 126 , in the IBM Security Directory Server documentation under the Administering section for information about these characters.

    The encryption salt is a randomly generated value that is used to generate AES encryption keys. You can obtain the destination server's salt value by searching (using the idsldapsearch utility) the destination server's "cn=crypto,cn=localhost" entry. The attribute type is ibm-slapdCryptoSalt.

  15. After successful data export using idsdb2ldif unquiesce the server1 so that it can function in read and write mode.
    idsldapexop -D <adminDN> -w <adminPW> -op quiesce -rc o=sample -end
  16. Copy the <server1data.ldif> file to the computer where server2 is located.
  17. On the computer where server2 is located, issue the following command: 
    idsldif2db -r no -i <server1data.ldif> -I <instance_name>
    where -r no prevents replication of the set of entries. For large ldif data imports, use idsbulkload command (without -r no option).
  18. After completing the data import on server2, issue the command idsrunstats to optimize the table statistics:
    idsrunstats -I <instance_name>
  19. Start server2: 
    idsslapd -I <instance_name> -n
  20. On the server1, resume the suspended replication agreement to server2:
    idsldapexop -D <adminDN> -w <adminPW> -op controlrepl -action resume \
             -ra "cn=server2,ibm-replicaServerId=<server1-uuid>,ibm-replicaGroup=default,o=sample"
  21. On the server2, resume the suspended replication agreement to server1:
    idsldapexop -D <adminDN> -w <adminPW> -op controlrepl -action resume \
             -ra "cn=server1,ibm-replicaServerId=<server2-uuid>,ibm-replicaGroup=default,o=sample"