|
| |
| Sun Java System Calendar Server Administration Guide | |
Chapter 4
Migration UtilitiesAfter you install Calendar Server, and configure it, you may need to migrate the component databases and the LDAP database. Several migration utilities are provided to bring your down level databases up to the current version. A Migration Utility Roadmap is provided in this chapter to assist you in choosing the correct utilities to run.
This chapter contains the following sections:
Overview of Calendar Server Migration UtilitiesCalendar Server 6 2004Q2 provides two types of database migration utilities:
Component Databases Migration Utilities
Component databases contain the events and todos for all calendar users and resources. The following utilities migrate component databases:
If you already have Calendar Server 6.0 (2003Q4) installed and you are upgrading to Calendar Server 6 2004Q2, you do not need to run this utility. The update from Berkeley 3.2.9 to 4.2 will be done automatically for you when the database is accessed for the first time.
Run this program before csmig, csvdmig, and commdirmig.
This utility is available at the migrations Web site. See Migrations Web Site.
You do not need to run the basic version of this utility first, since the recurring version also performs the same functions as the basic version. That is, it migrates a Calendar Server 5.x database to Calendar Server 6.x and upgrades the calendar database from Berkeley DB version 2.6 to 4.2. In addition, for visibility to Outlook, it converts existing recurring events to master records with exceptions.
This utility is available at the migrations Web site. See Migrations Web Site.
- ics2migrate – Migrates data from iPlanet Calendar Server 2.x to 5.x. This utility is bundled with Calendar Server 5.1.1.
- ncs4migrate – Migrates data from Netscape Calendar Server 4.x to 5.x. This utility is available at the migrations Web site. See Migrations Web Site.
LDAP Databases Migration and Upgrade Utilities
LDAP databases contain authentication (user and resource entries) and calendar preferences information. The following utilities upgrade or migrate LDAP data:
- csmig – Assigns an owner to each calendar in the Calendar Server 6.x database and maps each calendar ID (calid) to an owner, if needed, which allows support for hosted (virtual) domains and the LDAP Calendar Lookup Database (CLD) plug-in. This utility is packaged with Calendar Server. Run this utility after cs5migrate and before csvdmig.
- csvdmig – Upgrades a Calendar Server 6.x site to use hosted (virtual) domains by adding the calendar’s domain (@domainname) to each calid. For example, in the domain sesta.com, jdoe’s calid would now be jdoe@sesta.com. This utility is packaged with Calendar Server. Run this utility after cs5migrate, and csmig.
- commdirmig Utility – Migrates LDAP data from Schema 1 to Schema 2 in preparation for use with Identity Server 6.1 or higher. This migration utility is documented in a separate guide, see Sun Java System Communications Services Schema Migration Guide at:
http://docs.sun.com/coll/CalendarServer_04q2
If you previously used Messaging Server 5.x or Calendar Server 5.x, your LDAP entries were formatted for Sun LDAP Schema 1. In your new Calendar Server 6 2004Q2 environment, if you are going to use Identity Server for authentication, you must convert your LDAP entries to Schema 2 format by running this 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.
For Sun Java Enterprise System 2004Q2, this utility is bundled with Identity Server 6.2 (2004Q2), along with the provisioning utility, commadmin.
If you are not updating Identity Server and just need the migration utility for your Calendar Server 6.0 (2003Q4), a patch is available from technical support for just the utility.
Migration Utility RoadmapSince there are so many potential utility choices, Figure 4-1 shows a roadmap meant to assist you in determining what order to use the utilities.
Figure 4-1 Roadmap for Running the Calendar Server Migration Utilities
After you have installed Calendar Server 6.x and run cs5migrate, decide which if any of the other migration utilities you need to run. Figure 4-2 shows the different configuration scenarios and which migration utilities to run for each.
Figure 4-2 Configuration Scenarios
Migrations Web SiteTo further assist you in making the proper choices for your particular site, additional information and the utility downloads can be obtained from technical support who will direct you to a Web site.
At the Web site, you will be required to answer a short questionnaire, which will help you determine which of the utilities to use, and help you calculate what kind of downtime you can expect for the migration process.
In some cases, you will be referred to Sun Microsystems Technical Support or Professional Services for assistance.
ics2migrateThe ics2migrate utility migrates iPlanet Calendar Server 2.x calendar data and LDAP user preferences to Sun ONE Calendar Server 5.x.
This section describes:
Migration Requirements
Calendar Server 2.x to 6.x migration requires the following hardware and software:
- The source machine has the Calendar Server 2.x data that you plan to migrate.
- The target machine is where the migrated data will be created. This machine must have Calendar Server 6.0 (or later) installed.
- ics2migrate utility–Before you migrate, first check with technical support or your account team to ensure that you have the latest version of the utility.
The source machine and destination machines can be different servers or the same server. For a list of supported platforms refer to the Sun Java System Calendar Server Release Notes.
What Gets Migrated?
The following table lists the Calendar Server 2.x data and describes how ics2migrate migrates the data to Calendar Server 6.x.
The following table lists the Calendar Server 2.x LDAP attributes and describes how ics2migrate migrates the attributes to Calendar Server 6.x.
Migration Process
To migrate from 2.x to 5.x:
Run the db_recover on your 2.x Berkeley Database
Run the Berkeley DB db_recover utility to merge the log file transactions into the database before you convert it. If you do not use this utility, you will lose the unmerged transactions.
Download and Install Calendar Server 5.1.1
Refer to the iPlanet Calendar Server 5.1 Installation Guide found at:
http://docs.sun.com/db/doc/816-5516-10
Upgrade the 2.x Calendar Database
Calendar Server 5.1.1 requires Berkeley DB version 3.2.9 from Sleepycat Software. Before you run ics2migrate, you must use the Berkeley DB db_upgrade utility to upgrade your calendar database to version 3.2.9. Calendar Server 5.x includes the Berkeley DB utilities in the following directory:
cal_svr_base/opt/SUNWics5/cal/tools/unsupported/bin
For more information about the Berkeley DB utilities, refer to the following web site:
http://www.sleepycat.com/docs/utility/index.html
To upgrade your database to version 3.2.9:
- On Solaris and other UNIX systems, login as the user and group under which Calendar Server is running, such as icsgroup and icsuser.
- If necessary, stop the 2.x Calendar Server.
- Back up your calendar 2.x database, if you have not already done so.
- Remove (delete) any old share (__db_name.share) or log (log.*) files from the following directories:
cal_svr_base/opt/SUNWics5/cal/lib/http
cal_svr_base/var/opt/SUNWics5/csdb
- Run the db_upgrade utility to upgrade your 2.x calendar database to version 3.2.9. If you are not in the same directory with the 2.x calendar database, use the -h option to point to the database files.
Notes You must run db_upgrade on all 2.x database files (alarms.db, calprops.db, events.db, and todos.db). You must also run db_upgrade on all front-end and back-end servers in your Calendar Server configuration, even if a server is not directly connected to a calendar database.
- Locate the Calendar Server 2.x caldb.conf file in the csdb directory with the database files and change the first line in the file as follows:
Old value: caldb.version "1.0.0 [BerkeleyDB]"
New value: caldb.version= "1.0.0 [BerkeleyDB]"
Note If this file is not in the csdb directory, create it using a text editor and then set the first line to the new value.
Migrate the Data (run ics2migrate)
Follow these steps to run ics2migrate:
- Change to the directory where ics2migrate is located.
- Run ics2migrate using the syntax in ics2migrate Syntax.
- After migration, make sure that the caldb.berkeleydb.homedir.path parameter in the ics.conf file points to the migrated database.
- Run the csdb check command and, if necessary, the csdb rebuild command to rebuild your calendar database.
ics2migrate Syntax
To migrate both the Calendar Server 2.x database and LDAP user preferences
To migrate only the Calendar Server 2.x database
To migrate only the LDAP user preferences
Table # lists the ics2migrate options with a description of each option.
Check the Migration Results
After you have finished the migration, check the results:
The check command scans a calendar database for corruption. If the check command finds an inconsistency that cannot be resolved, it reports the situation in its output. If necessary, you can then run the csdb utility rebuild command to rebuild the calendar database (caldb).
For documentation about the csdb utility check and rebuild commands, see the Sun Java System Calendar Server Administration Guide on the documentation web site.
Migration Examples
This section has examples for the following topics:
Migrate in Quiet Mode
Perform the same migration as the previous example, except operate in quiet mode. ics2migrate does not display migration statistics on the console or generate a log file.
ics2migrate -q /var/opt/SUNWicsrv/2x_db /var/opt/SUNWics5/50_db
Migrate Only the Calendar Database
Migrate only the 2.x calendar database stored in the 2x_db directory (relative to the current directory) and create a 6.0 database in the /var/opt/SUNWics5/50_db directory.
ics2migrate -m db 2x_db /var/opt/SUNWics5/50_db
Migrate Only LDAP User Information
Migrate only the Calendar Server 2.x LDAP user information to version 6.0 format.
ics2migrate -m ldap
Migrate Both Calendar Database and LDAP User Information
Migrate both the LDAP user information and the Calendar Server 2.x database. The Calendar Server 2.x database is stored in the /var/opt/SUNWicsrv/2x_db directory and the 6.0 database is in the /var/opt/SUNWics5/50_db directory.
Grant scheduling and free/busy access to all calendars and log minimal migration statistics in a log file named ics2migrate.log.
ics2migrate /var/opt/SUNWicsrv/2x_db /var/opt/SUNWics5/50_db -l min
csmigThe 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 then accessible using this plug-in. The LDAP CLD plug-in provides horizontal scalability of the calendar database by allowing calendars to be distributed over a number of back-end servers. For information about the LDAP CLD plug-in, see the Sun Java System Calendar Server 6 2004Q2 Administration Guide.
This section describes the following topics:
csmig Functions
The csmig migration utility performs these 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 updates LDAP attributes for all relevant LDAP entries, including icsSubscribed, icsCalendar, icsCalendarOwned, icsFreeBusy, icsSet, and uid (for resource calendars) . 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.
- 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 jsmith doesn’t have an owner, it will be converted to orphan:jsmith, if 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.
For example, a calendar named football with owner bkamdar will be converted to bkamdar:football. A calendar tchang:soccer with the owner bkamdar will be converted to bkamdar:tchang_soccer. (Only one colon should be in the calid.) A resource calendar named auditorium:room1 will be converted to auditorium_room1.
csmig Requirements
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, see the Sun Java System Calendar Server Administration Guide.
- 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.
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 }
-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 is 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 is an output mapping file generated in dryrun mode that list 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.
In migrate mode, MappingFile is not used.
-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.
csmig Migration Steps
After you have installed Calendar Server 6.0 on all of the servers in your configuration, you must run csmig to migrate your existing Calendar Server and LDAP data to the new Calendar Server 6.0 and LDAP data, which is required for the LDAP CLD plug-in to work properly. Use these steps to migrate calendar data using csmig:
- Configure Your LDAP Directory Server–Adding indexes can greatly improve the performance of your migration and calendar searches on LDAP data.
- Perform a Test Dry Run–A dry run reports what csmig would do during a migration, but it does not migrate any actual data. After the dry run, you can correct any errors and determine a plan to handle any unresolved calendars.
- 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.
Configure Your LDAP Directory Server
To improve performance, consider adding the following two new indexes to the slapd.ldbm.conf file:
For information about creating indexes in the slapd.ldbm.conf file, refer to your directory server documentation.
Perform a Test Dry Run
A test dry run performed on a staging server reports what would be migrated, but it does not perform the actual migration of your production database. A dry run allows you to determine a plan for migrating your production database. For example, you can decide how you want to handle “orphan” calendars, which are calendars that don’t have an owner.
To perform a test dry run using csmig, follow these steps:
- 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.
- Install Calendar Server 6.0 (if necessary) on the staging server.
- Copy a snapshot of your calendar database to the staging server.
- Install an LDAP server to mimic the production LDAP environment. Install a snapshot of the LDAP database on this server with the new indexes in the slapd.ldbm.conf file.
- Change to the cal_svr_base/opt/SUNWics5/cal/sbin directory.
- Consider creating a catchall calid for user calendars that don’t have an owner. For example, on Solaris systems, 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).
- Run the csdb check command to check your database for corruption. If corruption is indicated, run csdb rebuild to rebuild the database.
- Run csmig with the dryrun option. For example, on a Solaris system, 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 to orphan and resource calendars without an owner to 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:
- Migrate your calendar database on your staging server before you migrate your actual production calendar database. This steps allows you to see exactly how your data will be migrated and to correct any problems before you migrate your production database.
For example, on a Solaris system, 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, 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. Then perform these checks:
- Run csdb check on the new calendar database. The number 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.
- Login to Calendar 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.
Migrate Your Production Data
To migrate your production database using csmig, follow these steps:
- 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/opt/SUNWics5/cal/sbin directory.
- Stop the Calendar Server using the stop-cal command (if necessary).
- Backup the following data:
- Run csmig with the migrate option. For example, on a Solaris system, 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 and resolve them according to your plan from Step 10 under Perform a Test Dry Run.
- 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.
- Run the csdb check command to check your migrated database. If any corruption is indicated, run csdb rebuild to rebuild the database.
- 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"
- csapi.plugin.calendarlookup.name = "*"
- 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 cal_svr_base/var/opt/SUNWics5/csdb/cld_cache.
- Restart the Calendar Server using the start-cal command.
- Log in to the Calendar Server 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”:
csmig Tips and Troubleshooting
The section describes the following tips and trouble shooting solutions:
The csmig dry run calendar owner is not the owner I want for a calendar
For example, a calendar named tchang:myCalendar has the owner as jsmith in the calendar database, and the csmig dry run shows the mapping as jsmith:tchang_myCalendar. I would like to keep this calendar name as tchang:myCalendar and assign the owner as tchang.
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 tchang’s LDAP entry.
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.
Solution
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
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
The output file will include the following warning message:
Error modifying calendar properties, error=2
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.
Solution
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?
Solution
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 detailed steps about moving users, see the Sun Java System Calendar Server 6 2004Q2 Administration Guide.
csvdmigThe csvdmig utility modifies the Calendar Server database and LDAP directory server database for sites that want to use hosted (virtual) domains. The csvdmig utility adds the domain name to the user ID as follows:
csvdmig Syntax
The csvdmig utility has the following syntax:
-m MappingFile is an input parameter that specifies a mapping file. The default is MigrateMapping.
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
...
user-n user-n@siroe.com-c ConfigFile is an input parameter that specifies a Calendar Server configuration file. The default is the ics.conf file.
-t DestinationDB is an output parameter that specifies the location of the migrated database. The default is MigratedDB.
-e ErrorFile is an output parameter that specifies the name of the error file for errors that cannot be resolved. The default is MigrateError.
DB | LDAP specifies whether to modify the Calendar Server database (DB) or the LDAP directory server (LDAP). The default is the calendar database (DB).
csvdmig Examples
