Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Calendar Server 6 2005Q1 Administration Guide 

Chapter 4
Database Migration Utilities

If you had an earlier version of Calendar Server (5.11 and earlier), after you install Calendar Server 6 2005Q1, and perform the post-installation configuration, you may need to migrate the component databases and the LDAP database.

A Choosing the Right Utilities section is provided in this chapter to assist you in choosing the correct utilities to run.

This chapter contains the following sections:

Post-Installation Database Migration Utilities

After you have installed Calendar Server 6 2005Q1, if you have calendar databases and LDAP database entries from your earlier Calendar Server 5.1.1 installation, run the following utilities in the order given:

Choosing the Right Utilities

Since there are so many potential utility choices, Figure 4-1 shows different configuration scenarios and which utilities to run and in what order.

Figure 4-1  Choosing Migration Utilities to Run

This figure shows several configuration scendarios that influence which LDAP migration utility to run.


The csmig utility assigns an owner to each calendar in the calendar database and maps each calendar ID (calid) to an owner, if needed.

The csmig utility supports hosted (virtual) domains and the LDAP Calendar Lookup Database (CLD) plug-in. Calendars in the migrated database are accessible using the LDAP CLD plug-in. For information about the LDAP CLD plug-in, see Chapter 6, "Configuring Calendar Database Distribution Across Multiple Machines".

This section describes the following topics:

csmig Functions

The csmig migration utility performs these functions:

csmig Requirements

The requirements for using csmig are:

csmig Syntax

The csmig utility has the following syntax:

csmig [ -t DestinationDB ] [ -b Backend-DWPHost ]
      [ -o OutputFile ]  [ -e ErrorFile ] [ -m MappingFile ]
        -c calendarOwner -r resourceOwner { migrate|dryrun }

Table 4-1 lists the utility options, gives a description of each, and gives the default value.

Table 4-1  Options for csmig

csmig Options

Description and Default Value

-t DestinationDB

Specifies the destination target database that csmig generates. The default is MigratedDB.

-b Backend-DWPHost

Specifies the name of the DWP back-end host server. This name must match the DWP back-end host server name specified in the ics.conf file.

-o OutputFile

Specifies an output file that captures the csmig output to the screen as well as any errors that occur. The default is MigrateOut.

-e ErrorFile

The file where csmig writes any errors or database entries that cannot be resolved. If database entries cannot be resolved, they are not written to the destination database. The default is MigrateError.

-m MappingFile

Specifies an output mapping file generated in dryrun mode that lists entries in the LDAP schema that need to be changed. For example:

Old calid = jsmith New calid = jsmith:basketball

The mapping file provides only a list of changes to make to the LDAP schema. csmig does not actually make the changes to the schema

The mapping file is not used in migrate mode.

-c calendarOwner

Specifies the owner for user calendars that don’t have owners.

-r resourceOwner

Specifies the owner for resource calendars that don’t have owners.


Specifies which mode the utility is running in. Use migrate mode to perform the migration. Use dryrun mode to generate the output mapping file before you actually migrate.

csmig Migration Steps

After you have installed and configured Calendar Server 6.x, you must run csmig to migrate your existing Calendar Server and LDAP data. Migration of the LDAP data is required for the LDAP CLD plug-in to work properly. Use these steps to migrate calendar data using csmig:

  1. Configure your Directory Server using
  2. If you have not already indexed LDAP attributes using, do so at this time. This will greatly help performance of the LDAP data migration.

  3. Using a staging server (not your production server), perform a test dry run.
  4. A dry run reports what csmig would do during an actual migration but does not migrate any data. After the dry run, and before you actually migrate, correct any errors and determine a plan to handle any unresolved calendars.

    For instructions on how to perform a test dry run, see To Perform a Test Dry Run.

  5. Migrate Your Production Data
  6. During a production run, csmig migrates the calendar database (.db files) and LDAP data (user and group preferences data), icsSubscribed, icsCalendar, icsCalendarOwned, icsFreeBusy, icsSet, and uid (for resource calendars). After the migration, all calendar resources will have an LDAP entry created.

    For instructions on how to migrate your production data, see To Migrate Your Production Data

To Perform a Test Dry Run

  1. Install Calendar Server 6.x (if necessary) on the staging server.
  2. Copy a snapshot of your calendar database to the staging server.
  3. Mimic your production LDAP environment on the staging server by performing the following tasks:
    • Install Directory Server.
    • Install a snapshot of the LDAP database on this server.
  4. Run to configure the staging Directory Server.
  5. Run to configure the staging Calendar Server.
  6. Log in as icsuser (or, if its different, log in as the Calendar Server runtime user ID specified during configuration). If you run csmig as superuser (root), you might need to reset the permissions for the migrated files.
  7. Change to the cal_svr_base/SUNWics5/cal/sbin directory.
  8. Run the csdb check command to check your database for corruption. If corruption is indicated, run csdb rebuild to rebuild the database.
  9. Consider creating a catchall calid for user calendars that don’t have an owner. For example, the following command creates a user with the calid of orphan:
  10. ./csuser -g orphan -s adminuser -y password -l en -c orphan create orphan

  11. Stop the Calendar Server using the stop-cal command (if necessary).
  12. cal_svr_base/SUNWics5/cal/sbin/stop-cal

  13. Run csmig with the dryrun option. For example, you might enter:
  14. ./csmig -b -o csmig.out -e csmig.errors -m -c orphan -r calmaster dryrun

    This command assigns user calendars without an owner (orphan calendars) to the owner orphan and resource calendars without an owner to the owner calmaster.

  15. Check the output mapping file ( The mapping file lists entries that need to be updated in the LDAP schema.
  16. Check the output, mapping, and error files. Resolve any LDAP issues or errors that you find. Determine how you will handle any unresolved calendars before the actual migration. Several options are:
    • Delete any unneeded calendars before you migrate.
    • Assign owners to any unresolved calendars.
    • Allow csmig to assign owners to the calendars during migration using the -c and -r options.
  17. Run csmig to migrate your staging calendar database.
  18. For example, the following command migrates the calendar database to the /var/opt/SUNWics5/testcsdb/ directory:

    ./csmig -t /var/opt/SUNWics5/testcsdb/ -b -o csmig.out -e csmig.errors -m -c orphan -r calmaster migrate

  19. After the test migration is finished, perform these steps to check out the newly migrated calendar database.
    1. Copy the migrated database to the /csdb directory specified by the caldb.berkeleydb.homedir.path parameter. Or, edit this parameter to point to the new location of the migrated database.
    2. Run csdb check on the new calendar database. The number of events and todos in the migrated database should match the pre-migration totals.
    3. Search for icsCalendarOwned entries and make sure that the entries match the pre-migration number of calendars.
    4. Log in to Calendar Express or Communications Express and verify some of the calendars in the migrated database.

If the test migration is successful, you are ready to migrate your production database.

To Migrate Your Production Data

  1. Log in as icsuser (or as the Calendar Server runtime user ID specified during configuration). If you run csmig as superuser (root), you might need to reset the permissions for the migrated files.
  2. Change to the cal_svr_base/SUNWics5/cal/sbin directory.
  3. Stop the Calendar Server using the stop-cal command (if necessary).
  4. cal_svr_base/SUNWics5/cal/sbin/stop-cal

  5. Backup the following data:
    • Calendar database (.db files).
    • LDAP data: slapd database directory and LDAP database.
    • ics.conf file. This step is not actually required, but it can be useful if you need to revert to your original configuration.
  6. Run csmig with the migrate option.
  7. For example, the following command migrates the calendar database to the /var/opt/SUNWics5/newcsdb/ directory:

    ./csmig -t /var/opt/SUNWics5/newcsdb/ -b -o csmig.out -e csmig.errors -m csmig.log -c orphan -r calmaster migrate

  8. Check for any unresolved calendars in the error file (csmig.errors) and resolve them according to your plan from Step 13 under To Perform a Test Dry Run.
  9. Run the csdb check command to check your migrated database. If any corruption is indicated, run csdb rebuild to rebuild the database.
  10. Copy the new migrated database to the /csdb directory specified by the caldb.berkeleydb.homedir.path parameter. Or, edit this parameter to point to the new location of the migrated database.
  11. Enable the LDAP CLD plug-in by making any necessary changes to the following configuration parameters in the ics.conf file:
    • service.dwp.enable = "yes"
    • service.dwp.port = "9779"
    • csapi.plugin.calendarlookup = "y"
    • = "*"
    • caldb.cld.type = "directory"
    • caldb.dwp.server.default = "default-server-name"
    • caldb.dwp.server.server-hostname.ip = "server-hostname" (for each back-end server including the local server)
    • caldb.cld.cache.enable = "yes" (if you want to use the CLD cache option)
    • caldb.cld.cache.homedir.path specifies the location of the CLD cache directory. The default is /var/opt/SUNWics5/csdb/cld_cache.
    • For information about setting configuration parameters for the LDAP CLD plug-in, see Chapter 6, "Configuring Calendar Database Distribution Across Multiple Machines".

  12. Restart Calendar Server using the start-cal command.
  13. Log in to your calendar user interface (Calendar Express or Communications Express) and verify that your configuration is working by checking several of the migrated calendars.
  14. To disable alarms while you are making your checks, set each of the following parameters in the ics.conf file to “no”:

    • caldb.serveralarms = "no"
    • caldb.serveralarms.dispatch = "no"
    • service.ens.enable = "no"
    • service.notify.enable = "no"
    • ine.cancellation.enable = "no"
    • ine.invitation.enable = "no"
    • service.admin.alarm = "no"

csmig Tips and Troubleshooting

The section describes the following tips and trouble shooting examples:

The csmig dry run calendar shows the wrong owner for a calendar.

Example Problem

A calendar named tchang:myCalendar has the owner jsmith in the calendar database, and the csmig dry run shows the mapping as jsmith:tchang_myCalendar. However, you would like to name this calendar tchang:myCalendar and assign the owner as tchang.

Example Solution

Before the migration, use the cscal utility to change the owner of the calendar tchang:myCalendar to tchang. Once this is done, the migration will map this calendar to tchang:myCalendar and add icsCalendarowned to the LDAP entry for user ID tchang.

The LDAP calendar search doesn’t work correctly.


After migration, the LDAP calendar search is enabled, but the calendar search dialog does not return any results or returns only partial results.


Enabling the LDAP calendar search allows Calendar Server to search (&(objectclass=icscalendaruser)(icscalendarowned=*substr*)).

Manually run two different searches on the LDAP data with the following filters and compare the output:

Since the server uses the filter that includes icsCalendarUser objectclass, the LDAP server might have been deployed with the schema check disabled, and some calendar entries may have been provisioned without the icsCalendarUser objectclass.

The csmig dry run indicates duplicate calendar names.

Example Problem

The csmig dry run mapping file and output file indicate that there is a duplicate calendar name. For example, in the original database, jsmith owns the following calendars:

The dry run indicates that during a migration, the two calendars will be merged, and the resulting calendar will be jsmith:basketball with owner jsmith and 15 total events

The output file will include the following warning message:

Error modifying calendar properties, error=2

Example Solution

If you don’t want the two calendars to be merged, change the owner of basketball to a user other than jsmith before the migration. This will preserve the data integrity of the two separate calendars.

How do I assign orphan calendars to different owners?


By default csmig assigns all orphan calendars to a single owner, but I would like to assign different owners for some orphan calendars.


csmig doesn’t accept the mapping file in the command line. However, you can assign owners to the orphan calendars in the original database before the migration. Check the dry run mapping file for all orphan calendars. Then use the cscal utility to assign owners to the orphan calendars before the migration. Run csmig in dryrun mode again to verify the new owners.

How do I move calendar users to another back-end server?


How do I move users from one back-end server to another?


To move a calendar user, you export each of the user’s calendars on the original server and then import the calendars on the second server. After the calendars are moved, you can delete the calendars on the original server. For instructions on how to move calendars, see To Move a User Calendar to a Different Back-End Server, or To Move a Resource Calendar to a Different Back-End Server.


The csvdmig utility modifies the Calendar Server database and LDAP directory server database for sites that want to use hosted (virtual) domains.

This sections contains the following topics:

csvdmig Functions

The csvdmig utility adds the domain name to the user ID as follows:

csvdmig Syntax

The csvdmig utility has the following syntax:

csvdmig [-t DestinationDB] [-c ConfigFile] [-e ErrorFile] [-m MappingFile]
  migrate [DB | LDAP]

Table 4-2 lists the options used by csvdmig, and gives a description of each.

Table 4-2  Options for csvdmig


Description and Default Value

-m MappingFile

Input parameter specifying a mapping file. For more information on the mapping file, see Mapping File. The default is MigrateMapping.

-c ConfigFile

Input parameter that specifies a Calendar Server configuration file. The default is the ics.conf file.

-t DestinationDB

Output parameter that specifies the location of the database. The default is MigratedDB. See Destination DB.

-e ErrorFile

output parameter that specifies the name of the error file for errors that cannot be resolved. The default is MigrateError.


Specifies which database to modify:

DB–the Calendar Server database
LDAP–the LDAP directory

The default is the calendar database (DB).

Mapping File

The mapping file is an input text file that maps existing users to their respective domains. You must create the mapping file before you run csvdmig. Specify one entry per line with a space between the old and new values. For example:


Destination DB

Even though the variable is named DestinationDB and the default is MigratedDB, csvdmig does not create a separate migrated database. It updates in place the original database that you specify with this option.

csvdmig Examples


The commdirmig utility migrates your LDAP data from Sun LDAP Schema 1 to Schema 2 in preparation for using Access Manager for authentication services.

This section contains the following topics:

Who Should Run the Utility

If you previously used Messaging Server 5.x or Calendar Server 5.x, your LDAP entries were formatted Schema 1. In your new Calendar Server 6 2005Q1 environment, if you are going to use Access Manager for authentication, you must convert your LDAP entries to Schema 2 format by running this utility.

If you are not using Access Manager, you should still consider migrating your LDAP data, since Schema 2 is the preferred LDAP mode for all Java Enterprise System products that use LDAP. In the future it is possible that newer versions of the communications products (Calendar, Messaging and Instant Messaging) may not support Schema 1. However, the migration can be deferred until a later, more convenient time if you are not going to be using Access Manager at this time.


If you have a separate LDAP directory for preferences, you must run commdirmig on that LDAP as well as the one used for authentication.

When to Run the Utility

If you are migrating from a pre-Java Enterprise System version of Calendar Server, run this utility after you run cs5migrate, csmig and csvdmig.

Where to Find Documentation

This migration utility requires special preparation and planning. It is documented in a separate guide, see Sun Java System Communications Services Schema Migration Guide at:

Where to Find the Utility

For Sun Java Enterprise System 2005Q1, this utility is bundled with Access Manager 2005Q1, along with the user management utility, commadmin.

If you are not updating Access Manager and just need the migration utility for your Calendar Server, a patch is available from technical support for just the utility.

Previous      Contents      Index      Next     

Part No: 819-0024-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.