idsideploy

Use the idsideploy command to create a copy of an existing directory server instance.

Description

You can use the idsideploy command to create a directory server instance by using an existing instance on a local or remote computer as a template. When you run idsideploy, the configuration settings and schema files from the source instance are duplicated and the directory key stash files are synchronized. The target directory server instance can be configured as a replica or peer of the source instance if it is in an existing replication deployment. You can also configure the target instance as a full directory server instance that is not participating in replication or as proxy server. The following requirements must be met for using the idsideploy command:

The source directory server instance must be running IBM® Security Directory Server, version 6.2 or later. You must not use an earlier version of IBM Security Directory Server, and cannot be running another version of LDAP.
The source directory server instance must be running in normal mode, and it cannot be running in configuration only mode.
The source directory server instance must be accessible from the computer where you are running the command.
If you are creating the target instance as a replica or peer, then a replication context must be defined on the source directory server instance. You cannot use the idsideploy command to set up the first replica or peer in a replication topology. The source directory server instance must contain at least one replication context, replication group, and replication subentry defined. If you are configuring a replica server, the source instance must contain the initial replication topology, including an agreement to at least one other server. If you are configuring a peer server, the source instance must be defined as a master for one or more subentries in the replication configuration.
If you are creating the target instance as a replica or peer, a replication subentry is created under the ibm-replicaGroup=default, replContext DN. If this DN entry is not present, the instance cannot be duplicated.
If the operating system user corresponding to the target instance does not exist, the idsideploy command creates the user by internally running the idsadduser command. However, you must provide the value for primary group name by using the -G parameter. The values for -u, -w, and -g parameters of idsadduser are taken from values of -I, -a, and -G parameters of idsideploy.

The target directory server instance is created on the computer where you run the idsideploy command. If the source directory server is on a different computer, the operating systems of the two computers can be different. For example, on a Windows system, you can make a copy of a directory server instance that is running on a Linux® system.

The idsideploy command also copies the key database files if the source directory server is running in SSL mode. To copy the key database files, the idsideploy command must be connected to the source instance over SSL.

If the source instance is a proxy server, then the target instance that gets created is a proxy server. If the source instance is a full directory server, then the target instance that gets created is a full directory server. If the source instance is a full directory server, you can choose whether to copy the data or not to the target instance.

Note: If you want to copy the data from the source instance while you create the target instance, the following requirements must be met:

The version of DB2® must be the same for both directory server instances. The fix pack levels can be different.
The source directory server instance must be configured for online backup.
An initial offline backup of the source instance must be taken before you use the idsideploy command to copy the instance. The path that you specify must contain only one backup image.
The path where the backup image is stored must be accessible to both the source instance and the target instance.

For information about preparing the source instance for copying the data, see the Installing and Configuring section of the IBM Security Directory Server documentation.

Synopsis

idsideploy [-I instance_name -e encrypt_seed -D admin_DN 
           -w admin_Pw -su LDAP_URL -sD admin_DN -sw admin_Pw
           [-l inst_location] [-L directory] [-r peer|replica]
           [-K key_file -N key_name -P key_pw]
           [-d debug_level] [-b output_file] [-G group_name]
           [-a password] [-x] [-q] [-n]] | -v | -?

Options

The idsideploy command takes the following parameters.

-a password: Specifies the instance owner password. This password is used during the user creation if the user does not exist, and is also used for the database configuration. On AIX®, Linux, and Solaris systems, this parameter is required when the -G parameter is specified. On Windows systems, this parameter is required when a new user is created for the target instance.
-b outputfile: Specifies the full path of a file in which to redirect output. If you use this parameter with the -q parameter, errors are sent to the outputfile file. If debug mode is set, then the debug output is also sent to this file.
-d debuglevel: Sets the debug level in the LDAP library. Set debug mode when you use the ldtrc command.
-D admin_DN: Specifies the directory administrator distinguished name (DN) for the target directory server instance.
-e encrypt_seed: Specifies the encryption seed for the target directory server instance. This value must match with the value provided for the source directory server instance.
-G: Specifies the name of primary group of the user that is associated with the target instance. This parameter is valid only on AIX, Linux, and Solaris systems and is required on these systems to create the user.
-I instance_name: Specifies the name of the directory server instance to create. The instance name must be an existing user ID on the system and must not be greater than eight characters in length.
-l inst_location: Specifies the location to store the configuration files and logs of a directory server instance. On Windows systems, this parameter is required and a drive letter must be specified. This location must have a minimum of 30 MB of free space. More disk space must be available to accommodate growth as the directory server log files increase. For a full directory server, a minimum of 80 MB is required to also store DB2 database.
-L directoryPath: Specifies the directory path of the backup image of the source instance from where to load data into the target instance. This parameter must be specified with the -r and -p parameters. The -L parameter must not be specified when the -x parameter is specified.
-K keyfile: Specifies the key file to use for an SSL connection.
-n: Specifies to run in no prompt mode. All output from the command is generated, except for messages that require user interaction.
-N key_name: Specifies the private key name to use in the key file for an SSL connection.
-p: Specifies to restore database on the target instance. To use -p parameter, the instance that is specified with the -I parameter must exist and back up of the source instance must be taken. The -L parameter is required with the -p parameter.
-q: Specifies to run in quiet mode. All output from the command is suppressed, except for error messages. If you also specify the -d parameter, then the trace output is not suppressed.
-r peer | replica: Specifies to configure the target instance in a replication environment as a peer or replica. This parameter must not be specified with the -x parameter. The only valid values with this parameter are peer and replica.
-sD admin_DN: Specifies the directory administrator DN of the source instance.
-sU LDAP_URL: Specifies the LDAP URL of the source instance.
-sw pw: Specifies the administrator password of the source instance.
-v: Specifies to show the version information of the command.
-w password: Specifies the administrator password for the target instance.
-x: Specifies to create a proxy server instance. The source instance must also be configured as a proxy server. This parameter must not be specified with the -L, -p, or -r parameter.
-?: Specifies to show the syntax format.

Note: If idsideploy is run with the -p parameter to restore a database, then you must set the DB2INSTANCE environment variable. The variable must point to the database instance name associated with the directory server instance. Otherwise, idsideploy might fail.

Examples

Example 1:

To create a target instance with data from an existing source instance, run the idsideploy command of the following format:

idsideploy -sU ldap://host:port -sD adminDN -sw adminPWD \ 
-e encrypt_seed -I inst_name -a user_pwd -D adminDN -w adminPWD \
-l inst_location –b outputfile -q -L directory_path

Example 2:

To create a stand-alone target instance without data from an existing source instance, run the following command:

idsideploy -sU ldap://host:port -sD adminDN -sw adminPWD \
-e encrypt_seed -I inst_name -a user_pwd -D adminDN -w adminPWD \
-l inst_location –b outputfile

This command does not clone the database.

Example 3:

To create a target instance as a peer in an existing replication setup, run the following command:

idsideploy -sU ldap://host:port -sD adminDN -sw adminPWD \
-e encrypt_seed -I inst_name -a user_pwd -D adminDN -w adminPWD \
-l inst_location –b outputfile -L directory_path -r peer

Example 4:

To deploy a proxy instance in SSL mode, run the following command:

idsideploy -sU ldaps://host:sec_port -sD adminDN -sw adminPWD \
-e encrypt_seed -I inst_name -K kdb_file -P kdb_file_pwd \
-N certificate_name -D adminDN -w adminPWD -x -l inst_location

Example 5:

To create a target instance when the corresponding operating system user does not exist, run the following command:

idsideploy -I instance_name -a inst_owner_PWD -D adminDN \
-w adminPWD -e encryption_seed -l inst_location –G group_name \
-sU ldap_URL -sD adminDN -sw adminPWD -L directoryPath