Chapter 3 Using the Migration Utility

This chapter describes the Schema Migration utility, commdirmig. It includes the following topics:

• commdirmig Syntax

• commdirmig Mandatory Options

• commdirmig Non-Mandatory Options

• Steps for Running commdirmig

• commdirmig Configuration File

The commdirmig utility migrates an LDAP directory from Schema 1 to Schema 2. The utility adds object classes and attributes to existing LDAP entries; it updates the current LDAP directory. To complete the migration, you do not have to create a new LDAP directory and copy data into it from the old directory.

commdirmig Syntax

The commdirmigutility has the following syntax:

commdirmig -t {1|2|3}
            -D AuthenticationID    -w AuthenticationPasswordFile
            -X DirectoryServerHost    -p DirectoryServerPort
            -b OSIRoot    -r DCRoot
            [-o online]             [-a AuditLDIFFile]
            [-d Domain [, Domain]... [, Domain] | “*”]
            [-f DomainFile]
            [-S mail, cal]          [-H MailHost]
            [-i InputFile]    [-l LogFile]
            [-v]                    [-c]
            [-m LogMaxSize]    [-k]
            [-u UndoFile]
            [-h Option]  [-? Option]  [-V]

commdirmig Syntax lists the commdirmig mandatory options and summarizes the information in the following sections.

-w
Authentication
PasswordFile

commdirmig Syntax lists the commdirmig non-mandatory options and summarizes the information in the following sections.

commdirmig Mandatory Options

Migration Type

commdirmig can migrate the LDAP directory directly to Schema 2, native mode, or through the intermediate stage—Schema 2, compatibility mode.

Use the -t option to specify the current schema version and mode (before the migration begins) and the version and mode to which commdirmig will migrate the schema. The -t option takes one of the following arguments:

• -t 1 specifies a migration from Schema 1 to Schema 2, native mode.

• -t 2 specifies a migration from Schema 1 to Schema 2, compatibility mode.

• -t 3 specifies a migration from Schema 2, compatibility mode to Schema 2, native mode.

-t is a required option.

Directory Server Access

During the migration, commdirmig updates Directory Server schema and configuration data for Schema 2 (compatibility or native mode).

Use the following options to specify the information commdirmig needs to gain access to the Directory Server:

• -D AuthenticationID specifies the login ID of the user authorized to run and modify the Directory Server.

• -w AuthenticationPasswordFile specifies an ASCII text file containing the password for the Directory Server login ID. For security, you can, for example, set the password file to be readable only by superuser (root).

• -X DirectoryServerHost specifies the host name of the Directory Server that manages the LDAP directory you are migrating.

• -p DirectoryServerPort specifies the port number for accessing the Directory Server.

• -b OSIRoot specifies the root suffix of the OSI (Organization) Tree in the LDAP directory.

• -r DCRoot specifies the root suffix of the DC Tree in the LDAP directory.

-D, -w, -X, -p, -b, and -r are required options.

When you run commdirmig for the first time, the -X, -p, -b, and -r options are saved in a configuration file, commdirmig-userprefs.properties. When you run commdirmig again, it uses the option values stored in the configuration file. For details, see commdirmig Configuration File.

commdirmig Non-Mandatory Options

Migration Online or in Preview Mode

You can choose whether to migrate the LDAP directory data directly (online) or run the utility in preview mode (write an audit of the migration to an LDIF-formatted file).

Use one of the following options to specify whether to use online or preview mode:

• -o directs commdirmig to update the LDAP directory immediately. When you choose -o, commdirmig migrates the directory data.

• -a AuditLDIFFile directs commdirmig to write the migration audit to the LDIF-formatted file you specify. The directory entries are not changed. Choose this option to perform a dry run of the migration.

  If you want to run the utility in preview mode, do not specify the -o option.

By default, commdirmig runs in preview mode (writes the migration audit to the LDIF file). It does not migrate the directory data online.

The default AuditLDIFFile is named commdirmig.audit.ldif.n

where n is a random number appended to the file name when the LDIF file is generated. The appended number makes the file name unique, which prevents the utility from overwriting any existing LDIF file. For example:

commdirmig.audit.ldif.1126206446358

A new AuditLDIFFile is created whenever the maximum audit LDIF file size is exceeded. The file size is set by the -m LogMaxSize option.

The default paths for the AuditLDIFFile are as follows:

Solaris

/var/opt/SUNWcomm/log/commdirmig.audit.ldif

Linux

/var/opt/sun/comms/commcli/log/commdirmig.audit.ldif

Examples

commdirmig -o

commdirmig -a /home/user/migration.audit.ldif

Domains Being Migrated

commdirmig can migrate a single domain, a list of domains, or all the domains in the LDAP directory. By default, commdirmig migrates all domains in the LDAP directory.

Use one of the following options to specify the domains to be migrated:

• -d Domain [, Domain]... [, Domain] specifies individual domain names. You can specify a single domain or a comma-separated list of domains.

• -d “*” specifies all domains in the LDAP directory. You must enclose the asterisk in quotes or use the Escape character before the asterisk.

• -f DomainFile specifies an ASCII text file that contains a blank-line separated list of domain names. The commdirmig utility migrates the domains named in the file.

  In a DomainFile, you also can specify a preferred mail host associated with a specified domain. This option is used as the mail host when mail service is added to users and groups in the domain.

  Formatting the Domain File

  For each domain to be specified in the DomainFile, type the option letter d, then a space, then the domain name.

  To specify an associated mail host, start a new line and type the option letter H, then a space, then the mail host name.

  Separate each specified domain with a blank line.

  Do not type a dash (-) before the option letters.

  In the following example, a DomainFile named domainnames.txt specifies three domains to be migrated and their associated mail hosts to be used for new mail services:

  d Domain1 H host1.siroe.com

  d Domain2 H host2.sesta.com

  d Domain3 H host3.siroe.com

Examples

commdirmig -d sesta.com, siroe.com, varrius.org

commdirmig -d *

commdirmig -f /home/user/domainnames.txt

Services to Add

By default, commdirmig migrates only the services it finds in the current directory. It does not add new services.

The -S option specifies whether to add new mail services, Calendar services, or both mail and Calendar services to the migrated directory.

Use the following arguments to add mail and Calendar services:

• -S mail adds new mail services to the directory.

• -H MailHost specifies the mail host to be used to add mail services to users and groups.

  When you use -S mail to add mail services, -H MailHost is required.

• -S cal adds new Calendar services to the directory.

Examples

commdirmig -S mail -H host1.siroe.com

commdirmig -S mail, cal -H host1.siroe.com

Input File

-i InputFile directs commdirmig to read a user-created text file, InputFile, which contains a list of commdirmig options and arguments. commdirmig uses the information in the file to migrate the directory.

The command-line version of an option overrides the InputFile version of the same option. That is, if you enter an option in the command line and the same option exists in the InputFile, commdirmig uses the command-line option and ignores the option in the InputFile.

Formatting the Input File

The InputFile is a new-line separated ASCII text file. For each option to be specified in the InputFile, type the option letter, then a space, then the option arguments. Do not type a dash (-) before the option letters.

In the following example, an InputFile named commdirmig.input.txt specifies the Directory Server login ID and a file containing the password of the Directory Server user, the Directory Server host name and port number, and the OSI root and DC root:

D "cn=Directory Manager"
w /opt/SUNWcomm/passwd
X ldaphost
p 389
b "o=isp"
r "o=internet"

Uses of the Input File

If you use this option, you do not have to type all the options in the command line when you run the utility. Also, you can edit and reuse the InputFile, which makes it easier to run the utility multiple times. For example, you can do the following:

• Run the utility once to migrate a test directory and later to migrate the production directory.

• Migrate several domains, one at a time.

  Before you reuse the file, alter the -d or -f option to point to the domains or the directory you intend to migrate.

• Migrate to Schema 2, compatibility mode, and later to Schema 2, native mode. Before you perform the second migration, alter the -t option to specify the correct target Schema version and mode.

Example

commdirmig -i /home/user/commdirmig.input.txt

Logging

Use the following options to specify logging:

• -l LogFile specifes the file to which commdirmig writes log information. The default LogFile is commdirmig.log.

• -v specifes verbose (maximum) log details. The default level is standard.

• -c directs commdirmig to continue running when an error occurs. The default is to exit when an error occurs.

• -m LogMazSize specifies the maximum size of the log file. You can configure the size in kilobytes (K) or megabytes (M). Following are two examples:

  500 K2 M

  When you run commdirmig for the first time, the -m option is saved in a configuration file, commdirmig-userprefs.properties. When you run commdirmig again, it uses the option values stored in the configuration file. For details, see commdirmig Configuration File.

• -k checks for erroneous domain provisioning in the existing LDAP directory and reports the erroneous information to the log file.

Undo Migration

The following option allows you to undo (roll back) the changes made to the LDAP directory if an error occurs during the migration process:

• -u UndoFile directs commdirmig to create a log in LDIF format that can be applied to undo the migration. The log entries are saved in the UndoFile you specify.

If an error occurs during the migration, you can use the ldapmodify tool with the Undo log to roll back all the changes made by commdirmig. This step returns the LDAP directory to the state it was in before the migration began.

By default, commdirmig creates an Undo file.

By default, the UndoFile is named commdirmig.undo.ldif.

Help

Use the following options to get help information and version:

• -h Option displays help information about the specified option.

• -? Option displays help information about the specified option.

• -V displays the current version of the commdirmig utility.

Steps for Running commdirmig

You can run commdirmig while the Messaging and Calendar servers are online. The servers can continue to look up user entries in the LDAP directory while commdirmig migrates the directory data to Schema 2.

Before you run commdirmig, complete following tasks:

Step

If you intend to use a file that lists domain names (by specifying the -f option), create the domain-name file.

• If you intend to use an input file containing the commdirmig options (by specifying the -i option), create the input file.

• Create a file to contain the Directory Server login password. The password file must be specified as an argument with the -w option.

To run commdirmig, follow these steps:

Steps

1. Log in as or become superuser (root).

   By default, the commdirmig utility is located in the /opt/SUNWcomm/bin directory.

2. Run commdirmig. For the syntax, see commdirmig Syntax.

   Command-line examples are shown below.

3. After commdirmig is finished, view the commdirmig.log file to check the migration status. If errors occur during the migration or if schema entries cannot be migrated, commdirmig writes them to commdirmig.log.

   By default, the log file is located in the following directory:

   /var/opt/SUNWcomm/logs/commdirmig.log

Example 1

The following example migrates all domains in the LDAP directory from Schema 1 to Schema 2, native mode:

commdirmig -D "cn=Directory Manager" -w /opt/SUNWcomm/passwd -t 1
-X ldaphost -p 389 -b "o=isp" -r "o=internet" -o -d “*”

Example 2

The following example does not migrate the actual directory data. It creates an LDIF audit file showing the modification requests for migrating domains siroe.com and sesta.com from Schema 1 to Schema 2, native mode:

commdirmig -D "cn=Directory Manager" -w /opt/SUNWcomm/passwd -t 1
-X ldaphost -p 389 -b "o=isp" -r "o=internet" -d siroe.com -d sesta.com

If this example were run with the -o option, the actual directory data would be migrated.

Example 3

The following example migrates the domain varrius.com from Schema 1 to Schema 2, native mode, and adds Calendar service to all the users in the domain:

commdirmig -D "cn=Directory Manager" -w /opt/SUNWcomm/passwd -t 1
-X ldaphost -p 389 -b "o=isp" -r "o=internet" -d varrius.com -S cal -o

commdirmig Configuration File

When you run commdirmig for the first time, it saves the following options in a configuration file named commdirmig-userprefs.properties:

-X DirectoryServerHost-p DirectoryServerPort-b OSIRoot-r DCRoot-m LogMaxSize

When you run commdirmig again, it uses the option values stored in the configuration file.

The commdirmig-userprefs.properties file is created in the following directory:

/opt/SUNWcomm/lib

How commdirmig Chooses Which Option Value to Use

The command-line version of an option overrides the InputFile version of the same option; the InputFile version overrides the configuration-file version.

That is, for a given option, commdirmig uses the value entered in the command line and ignores any other value for that option stored in the InputFile or configuration file.

If an option is not in the command line and the -i InputFile option is entered, commdirmig uses the value stored in the InputFile (if it is present), ignoring the configuration file.