This chapter describes the various database migration utilities available for migrating your calendar databases and LDAP database after you have installed and configured Calendar Server 6.3 software.
This chapter contains the following sections:
If you are migrating from Calendar Server 6.0, 6.1, or 6.2 versions, run the utility called 3.3 csmigrate Utility. If you did not already run cs5migrate for recurring events and tasks in your previous deployment, you must run cs5migrate on your existing calendar databases before running csmigrate.
If you are migrating from Calendar Server 5.1.1, migrate the calendar databases and the LDAP database using the migration utilities as explained in 3.2 Choosing the Right Calendar Server Utilities.
If you had an even earlier version of Calendar Server installed, call technical support for assistance with migration of your data.
This section describes each of the migration utilities. Use only the migration utilities you need, depending on which version of Calendar Server you previously had installed. These utilities are found in the sbin directory.
If you have ever run the cs5migrate utility against your databases, but did not use the -roption, you must run it again with the -r option before running any of the other utilities.
The migration utilities are as follows:
Assigns an owner to each calendar in the Calendar Server 6 database and maps each calendar ID (calid) to an owner, if needed, which allows support for multiple domains and the LDAP Calendar Lookup Database (CLD) plug-in.
Run this utility before csvdmig.
Upgrades a Calendar Server 6 site to use multiple domains by adding the calendar’s domain (@domainname) to each calid. For example, in the domain sesta.com, the jdoe calidwould now be jdoe@sesta.com. This utility is packaged with Calendar Server.
Run this utility aftercsmig and beforecs5migrate.
Migrates your calendar databases from Calendar Server version 5 to version 6.2 format. You must run this utility against your databases specifying the -r option. If you migrated from Calendar Server version 5.1.1 to version 6.2 prior to this time, but you did not run the cs5migrate utility with the -r option, you must run it with that option before running the csmigrate utility.
Run this utility after csmig and csvdmig and before csmigrate.
Migrates your calendar databases for upgrading from Calendar Server version 6.0, 6.1, or 6.2 to Calendar Server 6.3 version. If you need to run cs5migrate with the -r option, run it before this utility.
Migrates LDAP data from Schema version 1 to Schema version 2 in preparation for use with Access Manager (in Legacy mode).
This section helps you decide which utilities you need to run to have all calendar databases and your LDAP database at the Calendar Server 6.3 software level.
Use the following table to find the correct collection of utilities to run:
Run the utilities in the order given.
Calendar Server Version You Are Migrating From |
Condition of Your Database Files |
Utilities to Use |
---|---|---|
Calendar Server 6.0, 61. 6.2 |
You are using recurring events and tasks and have previously run cs5migrate in the past. You already use Schema version 2. |
Run csmigrate |
Calendar Server 6.0, 61. 6.2 |
You are using recurring events and tasks and have previously run cs5migrate in the past. You did not use Schema version 2 before, but need to now. |
Run csmigrate and commdirmig. |
Calendar Server 6.0, 61. 6.2 |
You have never run cs5migrate against your files. You already use Schema version 2, or you are on Schema version 1 and plan to stay with it. |
Run cs5migrate and csmigrate. |
Calendar Server 6.0, 61. 6.2 |
You have never run cs5migrate against your files. You did not use Schema version 2 before, but need to now. |
Run cs5migrate, csmigrate, and commdirmig. |
Calendar Server 5.1.1 |
You did not use multiple domains in the past. |
Run csmig, csvdmig, cs5migrate, csmigrate, and commdirmig. |
Earlier than Calendar Server 5.1.1 |
Your files do not support multiple domains or the LDAP CLD. Your LDAP database is using Schema version 1. |
Call technical support for help getting your database and LDAP files to Calendar Server 5.1.1 level. |
Earlier than Calendar Server 5.1.1 |
Your system is configured for limited virtual domains, or you have multiple instances of Calendar Server software installed on an operating system that predates Solaris 10. |
Contact the sales account representative for an evaluation of your migration requirements. |
The csmigrate utility is used to migrate Calendar Server 6.0, 6.1 or 6.2 databases to Calendar Server 6.3 databases. You can find the csmigrate utility in the sbin directory of the Calendar Server product along with other administrative tools.
This section contains the following topics:
The syntax for the csmigrate command is:
csmigrate [-q] [-d] [-l min|max] [-b backup_dir] source_dbdir target_dbdir
The options and their usage are as follows:
Specifies quiet mode and no print instructions.
Specifies dry run mode and no new database written.
Specifies log level. The migration logs are written to csmigrate.log and errors are written to csmigrateError.log in the default logs directory.
Specifies the directory to backup source database. The program backs up the source database to this directory and works on that copy to prevent any damage to the source databases. Default location is the backup under the source database directory.
The directory where pre-migration database files are located.
The directory where post-migration files are created.
To print the version information of the tool.
To print the usage information of the tool.
The exit codes for the program are 255 on failure and 0 on success.
Examples of using the options in csmigrate command are:
csmigrate -b /var/opt/SUNWics5/tmpdb /var/opt/SUNWics5/old_db /var/opt/SUNWics5/new_db csmigrate -q /var/opt/SUNWics5/old_db /var/opt/SUNWics5/new_db csmigrate -l min old_db /var/opt/SUNWics5/new_db csmigrate -l max old_db /var/opt/SUNWics5/new_db
Log in with root privileges.
Stop all services.
For example, issue the following command:
stop-cal
Move your current databases to a temporary directory.
For example, move the entire csdb directory to the oldcsdb.
mv cal-svr-base/SUNWics5/csdb/* cal-svr-base/SUNWics5/oldcsdb
Make sure both the new directory and old files in that directory are owned by the default administrator (icsuser, icsgroup).
If the ownership is not correct, change ownership using the following command:
chown -R icsuser:icsgroup /cal-svr-base/SUNWics5/oldcsdb/
Run the migration tool.
Migrate from your new backup copy (oldcsdb) to the csdb directory as shown in the following example:
cd cal-svr-base/SUNWics5/cal/sbin/ ./csmigrate -l max /cal-svr-base/SUNWics5/oldcsdb cal-svr-base/SUNWics5/csdb
Restart calendar services.
For example, use the following command:
stop-cal
The cs5migrate utility is used to migrate the Calendar Server 5.1.1 databases to Calendar Server 6.3 level. In addition, run this utility if you are migrating from one of the earlier Calendar Server 6 versions, and you did not use the recurring option.
The cs5migrate utility performs the following tasks:
In the past, if you did not plan to use the Connector for Microsoft Outlook, you could choose to run this utility without doing the recurring data conversion. However, starting with Calendar Server 6.3, you must convert your recurring data to the new format.
This utility can be found in the sbin directory along with other administrative tools, after you have upgraded to Calendar Server 6.3 software.
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 multiple 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 5, Configuring Calendar Database Distribution Across Multiple Machines in Calendar Server Version 6.3.
This section describes the following topics:
The csmig migration utility performs the following functions:
csmig migrates both user and resource calendars in the current calendar database (*.db files) specified by the caldb.berkeleydb.homedir.path parameter. In the new destination target database, csmig updates entries required by the LDAP CLD plug-in in the calendar properties (calprops), events, todos (tasks), and group scheduling engine (GSE) database files.
csmig writes only to the destination target database; it does not update your existing calendar database.
csmig assigns an owner to each calendar in the calendar database and maps each calendar ID (calid) to an owner, if needed. All default calids are kept as is, and no changes are made.
Other calendars are mapped as follows:
User calendars that don’t have valid owners will be owned by the user passed to csmig by the -c option. For example, if calendar ID jsmith doesn’t have an owner, it will be converted to orphan:jsmith, where orphan is specified as the -c option.
Resource calendars that don’t have an owner will be owned by the resource user passed to csmig by the -r option.
If a resource calendar has any colons (:) in the name, the colons are converted to underscores, so that the migrated name has only one colon.
For example, a calendar named football with owner bkamdar will be converted to bkamdar:football. A calendar named tchang:soccer with the owner bkamdar will be converted to bkamdar:tchang_soccer. A resource calendar named auditorium:room1 with an owner admin1 will be converted to admin1:auditorium_room1.
csmig updates LDAP attributes for all relevant LDAP entries, including icsSubscribed, icsCalendar, icsCalendarOwned, icsFreeBusy, icsSet, and for resource calendars, uid. csmig creates the icsDWPHost attribute for each calendar in the LDAP directory server database. icsDWPHost specifies the host name of the back-end server where a calendar resides.
The requirements for using csmig are:
The calendar database must not be corrupted. Use the csdb check command to check your calendar database, and if necessary, run the csdb rebuild command to rebuild the database. For information about these commands, Appendix D, Calendar Server Command-Line Utilities Reference.
You must have sufficient disk space for the new destination target database and if applicable, your backup database.
To run csmig, 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.
You must also have privileges to manage the attributes of calendar users in the LDAP directory server that stores user preferences.
Calendar Server must be stopped.
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 } |
The following table lists the utility options, gives a description of each, and gives the default value.
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. |
migrate|dryrun |
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. |
If you had a version of Calendar Server predating version 5.1.1, after you install and configure Calendar Server 6.3, run csmig to migrate your existing Calendar Server and LDAP databases. 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:
Configure your Directory Server using comm_dssetup.pl.
If you have not already indexed LDAP attributes using comm_dssetup.pl, do so at this time. This will greatly help performance of the LDAP data migration.
Using a staging server (not your production server), perform a test dry run.
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 3.5.4 csmig Utility Migration Steps.
Migrate Your Production Data
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 3.5.4 csmig Utility Migration Steps.
Install Calendar Server 6.3 (if necessary) on the staging server.
Copy a snapshot of your calendar database to the staging server.
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.
Run comm_dssetup.pl to configure the staging Directory Server.
Run csconfigurator.sh to configure the staging Calendar Server.
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.
Change to the cal-svr-base/SUNWics5/cal/sbin directory.
Run the csdb check command to check your database for corruption. If corruption is indicated, run csdb rebuild to rebuild the database.
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:
./csuser -g orphan -s adminuser -y password -l en -c orphan create orphan |
Stop the Calendar Server using the stop-cal command (if necessary).
cal-svr-base/SUNWics5/cal/sbin/stop-cal
Run csmig with the -dryrun option. For example, you might enter:
./csmig -b sesta.com -o csmig.out -e csmig.errors -m csmig.map -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.
Check the output mapping file (csmig.map). The mapping file lists entries that need to be updated in the LDAP schema.
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.
Run csmig to migrate your staging calendar database.
For example, the following command migrates the calendar database to the /var/opt/SUNWics5/testcsdb/ directory:
./csmig -t /var/opt/SUNWics5/testcsdb/ -b sesta.com -o csmig.out -e csmig.errors -m csmig.map -c orphan -r calmaster migrate
After the test migration is finished, perform these steps to check out the newly migrated calendar database.
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.
Run csdb check on the new calendar database. The number of events and todos in the migrated database should match the pre-migration totals.
Search for icsCalendarOwned entries and make sure that the entries match the pre-migration number of calendars.
Log in to 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.
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.
Change to the cal-svr-base/SUNWics5/cal/sbin directory.
Stop the Calendar Server using the stop-cal command.
cal-svr-base/SUNWics5/cal/sbin/stop-cal
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.
Run csmig with the -migrate option.
For example, the following command migrates the calendar database to the /var/opt/SUNWics5/newcsdb/ directory:
./csmig -t /var/opt/SUNWics5/newcsdb/ -b sesta.com -o csmig.out -e csmig.errors -m csmig.log -c orphan -r calmaster migrate
Check for any unresolved calendars in the error file (csmig.errors) and resolve them according to your plan from 3.5.4 csmig Utility Migration Steps under 3.5.4 csmig Utility Migration Steps.
Run the csdb check command to check your migrated database. If any corruption is indicated, run csdb rebuild to rebuild the database.
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.
Enable the LDAP CLD plug-in by making any necessary changes to the following configuration parameters in the ics.conf file:
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 5, Configuring Calendar Database Distribution Across Multiple Machines in Calendar Server Version 6.3.
Restart Calendar Server using the start-cal command.
Log in to Communications Express and verify that your configuration is working by checking several of the migrated calendars.
To disable alarms while you are making your checks, set each of the following parameters in the ics.conf file to "no":
The section describes the following tips and trouble shooting examples:
3.5.5.1 The csmig dry run calendar shows the wrong owner for a calendar.
3.5.5.3 The csmig dry run indicates duplicate calendar names.
3.5.5.4 How do I assign orphan calendars to different owners?
3.5.5.5 How do I move calendar users to another back-end server?
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.
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.
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:
LDAP search with filter (&(objectclass=icscalendaruser)(icscalendarowned=*substr*))
LDAP search with filter (icscalendarowned=*substr*)
Since the server uses the filter that includes icsCalendarUser object class, the LDAP server might have been deployed with the schema check disabled, and some calendar entries may have been provisioned without the icsCalendarUser object class.
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:
basketball with 5 events
jsmith:basketball with 10 events
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
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.
By default csmig assigns all orphan calendars to a single owner, but I would like to assign different owners for some orphan calendars.
csmig does not 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 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 15.6 Managing User Calendars.
The csvdmig utility prepares your calendar databases and LDAP user and group entries for use in a multiple-domain environment. Even if you plan to use only the default domain, you must run this utility.
Be sure to run csmig before using this utility if you are migrating from a non-domain environment to the multiple domain environment in Calendar Server 6.3.
This sections contains the following topics:
The csvdmigutility performs the following changes to your databases and LDAP entries:
The format of calendar IDs (calids) is changed:
From: userid[:calendar-name]
To: userid@domain[:calendar-name]
Access Control List (ACL) access rules are changed:
From: userid
To: userid@domain
The LDAP directory server user entries for the Calendar Server attributes are modified as:
userid[:calendar-name] to userid@domain[:calendar-name].
Updates the owner and attendee fields in events and tasks in the calendar database. For example:
If jsmith in the domain sesta.com is the owner of an event, the new owner field would contain jsmith@sesta.com.
The csvdmig utility updates the databases and LDAP directory in place. That is, it does not create a separate migrated database, but alters the database you are converting. Therefore, to be safe, run csvdmig against snapshots of your databases and LDAP directory.
The csvdmig utility has the following syntax:
csvdmig [-t DestinationDB] [-c ConfigFile] [-e ErrorFile] [-m MappingFile] migrate [DB|LDAP] |
The following table lists the options used by csvdmig, and gives a description of each.
Option |
Description and Default Value |
---|---|
-m MappingFile |
Input parameter specifying a mapping file. For more information on the mapping file, see 3.6.2.1 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 to be migrated. The default is MigratedDB. Tip – Always use the -t option. For more information on this option, see 3.6.2.2 Destination DB. |
-e ErrorFile |
output parameter that specifies the name of the error file for errors that cannot be resolved. The default is MigrateError. |
DB | LDAP |
Specifies which database to modify: DB – the calendar database LDAP – the LDAP directory The default is the calendar database (DB). |
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:
user1 user1@sesta.com user2 user2@siroe.com user3 user3@sesta.com ... usern usern@siroe.com
The location of the database to be migrated. The utility updates the file in place. Be sure you have backed up this directory before using the csvdmig utility.
If you do not specify the -t option, the utility will attempt to migrate the contents of the current directory (the directory specified by performing pwd at the command line), with unpredictable results.
The following are csvdmig examples
Migrate the LDAP directory server data using default values:
csvdmig migrate LDAP
Migrate the Calendar Server database:
csvdmig -t targetDB -e errorFile -m mappingFile migrate
The commdirmig utility migrates your LDAP data from Sun Java System LDAP Schema version 1 to Schema version 2 in preparation for using Access Manager for authentication services. If your previous installation already used Schema version 2, you do not have to run this utility again.
This migration utility migrates your Schema version 1 LDAP database to Schema version 2. If you are going to use Access Manager software for authentication, you must convert your LDAP entries to Schema version 2 format by running this utility.
If you are not using Access Manager, you should still consider migrating your LDAP data, since Schema version 2 is the preferred LDAP mode for all Communications Suite products that use LDAP.
If you have a separate LDAP directory for preferences, you must run commdirmig on that LDAP as well as the one used for authentication.
Run commdirmig after you have run all the other migration utilities necessary to migrate your calendar and LDAP databases from your earlier version of Calendar Server software to the 6.3 version of the Calendar Server software.
The commdirmig migration utility requires special preparation and planning. It is documented in a separate guide, see Sun Java Communications Suite 5 Schema Migration Guide.
The commdirmig utility comes bundled with Delegated Administrator that you install from the Communications Suite installer.
A patch is also available from technical support for the utility.