Sun Java System Communications Services 6 2005Q4 Schema Migration Guide

Chapter 3 Using the Migration Utility

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

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.

Table 3–1 commdirmig Mandatory Options

commdirmigMandatory Option

Description  

-t 1|2|3

1 specifies a migration from Schema 1 to Schema 2, native mode. 2— specifies a migration from Schema 1 to Schema 2, compatibility mode.3— specifies a migration from Schema 2, compatibility mode to Schema 2, native mode.

-D AuthenticationID

Specifies the login ID of the user authorized to run and modify the Directory Server. 


-w
Authentication
PasswordFile

Specifies a text file containing the password for the Directory Server login ID. You can choose to 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. 

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

Table 3–2 commdirmig Non-Mandatory Options

commdirmig

Non-Mandatory Option 

Description  

[-o ]

Directs commdirmig to migrate the LDAP directory online (immediately).

[-a AuditLDIFFile]

Directs commdirmig to write the migration audit to an LDIF-formatted file you specify. The directory entries are not changed.

By default, commdirmig writes the migration audit to a file. It does not migrate online.

The default AuditLDIFFile is 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

The default paths (and name) for AuditLDIFFile are as follows:

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

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

[-d Domain[,Domain]

...[,Domain]

| “*”]

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

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

The default is to migrate all domains in the LDAP directory. 

[-f DomainFile]

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

Optionally, you 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. 

For details about formatting the DomainFile, see Domains Being Migrated

[-S mail, cal]

mail– adds new Messaging services to the directory.

cal– adds new Calendar services to the directory.

The default is to migrate only the services commdirmig finds in the current 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.

[-i InputFile]

Directs commdirmig to migrate the directory by using the options and arguments listed in a user-created file, InputFile.

[-l LogFile]

Specifies the file to which commdirmig writes log information. The default is commdirmig.log.

[-v ]

Specifies 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 LogMaxSize]

Specifies the maximum size of the log file. Size can be configured in kilobytes (K) or megabytes (M). For example: 500 K or 2 M.

[-k ]

Checks for erroneous domain provisioning in the existing LDAP directory and reports the erroneous information to the log file. 

[-u UndoFile]

Directs commdirmig to create an undo log that can be applied to undo the migration. The log entries are saved in LDIF format in the user-specified file, UndoFile.

The default is to create an undo log. The default file is commdirmig.undo.ldif.

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

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 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, -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:

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:

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:

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:

Example

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

Logging

Use the following options to specify logging:

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:

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:

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.

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

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