Chapter 5 Managing Calendar Server Databases

This chapter describes how to manage Sun ONE Calendar Server databases, including these sections:

Calendar Server Database Files

By default, the Calendar Server database files (as well as the cld_cache and ldap_cache directories) are created and maintained in the following directory:

If you prefer, you can specify a different directory by running the Calendar Server configuration program (csconfigurator.sh). For information about the configuration program, refer to the Sun ONE Calendar Server 6.0 Installation Guide for Solaris Operating Systems.

Table 5-1 Calendar Server Database Files
File	Description
ics50calprops.db	Calendar properties for all calendars. Includes the calendar ID (calid), calendar name, Access Control List (ACL), and owner.
ics50events.db	Events for all calendars.
ics50todos.db	Todos (tasks) for all calendars.
ics50alarms.db	Alarms for all events and todos (tasks).
ics50gse.db	Queue of scheduling requests for the group scheduling engine (GSE).
ics50journals.db	Journals for calendars. Journals are not implemented in the current release.
ics50caldb.conf	Database version identifier.
ics50recurring.db	Recurring events.
ics50deletelog.db	Deleted events and todos (tasks). See also Chapter 7, "Managing the Delete Log Database" on page 129.

Using the csdb Utility to Manage a Database

Specifying a Target Database

Viewing Calendar Database Status

Importing and Exporting Calendar Data

Deleting a Calendar Database

Specifying a Target Database

-t caldb — calendar database

-t sessdb — session database

-t statdb — statistics database

If you do not include the -t option, csdb operates on all three databases, except for the check and rebuild commands, which operate only on the calendar database.

Viewing Calendar Database Status

To view the status of a calendar database, use the csdb utility list command. Calendar Server can be either running or stopped.

Use the -t option to specify the target database (caldb, sessdb, or statdb); otherwise, csdb operates on all three databases.

To view information about the calendar database in the current directory in verbose mode:

Importing and Exporting Calendar Data

To export and import calendar data to and from a file, use the csexport and csimport utilities. The calendar data can be in either iCalendar (.ics) or XML (.xml) format.

You must run csexport and csimport locally on the machine where your Calendar Server is installed. Calendar Server can be either running or stopped.

Exporting Calendar Data

To export calendar data to a file, use csexport. The file name extension (.ics or .xml) that you specify for the output file determines which format is used.

For example, to export the calendar with the calendar ID (calid) JSmithcal in iCalendar (text/calendar MIME) format to a file named jsmith.ics:

To export the calendar JSmithcal in XML (text/xml MIME) format to a file named jsmith.xml:

Importing Calendar Data

To import calendar data from a file previously saved using the csexport utility, use csimport. The file name extension of the import file (.ics or .xml) indicates the format in which it was saved.

For example, to import calendar data to the calendar ID (calid) JSmithcal from the file jsmith.ics that was saved in iCalendar (text/calendar MIME) format:

To import data into the calendar JSmithcal from a file named jsmith.xml that was saved in XML (text/xml MIME) format:

If the specified calendar ID (calid) already exists, its data is cleared before the new data is imported.

Recovering a Damaged Database

To recover a damaged session or statistics database, use the csdb utility recover command. Use the -t option to specify the target database: sessdb (session) or statdb (statistics).

Before you run the recover command, stop Calendar Server using the stop-cal command.

Deleting a Calendar Database


Note	To recover a damaged calendar database (caldb), use the csdb utility check and rebuild commands instead of recover. For more information, see "Checking and Rebuilding a Calendar Database".

To delete a calendar database, use the csdb utility delete command. Calendar Server must be stopped.

Use the -t option to specify the target database (caldb, sessdb, or statdb); otherwise, csdb deletes all three databases.

Detecting and Recovering From Database Corruption

Calendar database corruption can be caused by various reasons: system resource contention, hardware failures, application errors, database failures, and of course human error. This section describes how to detect calendar database corruption and to recover a corrupted database, including:

Minimizing Data Loss

Checking and Rebuilding a Calendar Database

Using the Dump and Load Procedure to Recover a Database

Minimizing Data Loss

No matter how good a recovery procedure is, it is always better to detect database corruption early to minimize any data loss. To detect possible database corruption, follow these suggestions:

Backup your database daily using a utility such as csbackup, the Sun StorEdge Enterprise Backup™ software, or Legato Networker®. For more information refer to Chapter 6, "Backing Up and Restoring Calendar Server Data."

Monitor the Calendar Server log files, including the alarm logs, for any error messages that might indicate database corruption. For information about the log files, refer to "Monitoring Calendar Server Log Files".

Use the csmonitor utility to monitor Calendar Server and to alert an administrator by e-mail if it detects problems, such as more than one transaction log file or a shortage of disk space for the calendar database. For more information, see "csmonitor".

Never remove any transaction log files in the database directory. The transaction log files contain the transaction updates (additions, modifications, or deletions), and removing them can corrupt the calendar database beyond recovery.

Checking and Rebuilding a Calendar Database

The csdb utility commands includes the following commands to check and, if necessary, to rebuild a calendar database (caldb):

The check command scans a calendar database to determine if any corruption has occurred and reports the results in its output. (The check command does not check for corruption in the alarm or group scheduling engine (GSE) database.)

The rebuild command also scans a calendar database to determine if any corruption has occurred and if necessary, generates a rebuilt calendar database (.db files).

Run the check command (and rebuild command, if necessary) after any event that might cause database problems. For example, if your site experiences a power failure, run the check command to determine if any database corruption occurred.

The csdb utility also incudes the recover command to recover a damaged session or statistics database. If your calendar database is corrupted, use check and rebuild instead of recover.

Checking a Calendar Database for Corruption


Caution	Before you run these commands, backup your calendar database using the csbackup utility (or another backup utility).

The check command scans a calendar database and checks calendar properties (calprops) events and todos (tasks) for corruption. If the check command finds an inconsistency that cannot be resolved, it reports the situation in its output.

You should run the check command regularly to check your calendar database for inconsistencies. For example, consider running check after each backup of your database. However, if you already know that your calendar database is corrupted, you don’t need to run the check command. Go ahead and rebuild your corrupted database.

To check a calendar database for corruption

Calendar Server can be either running or stopped; however, if possible, stop Calendar Server.

Make a copy of your calendar database, if you haven’t already done so. Copy only the database (.db) files. You don’t need to copy any share (__db_name.share) or log (log.*) files.

Change to the cal_svr_base/opt/SUNWics5/cal/sbin directory. For example, on Solaris Systems, enter:

cd /opt/SUNWics5/cal/sbin

Run the check command on the copy of your calendar database:

./csdb check dbdir > /tmp/check.out 2>&1

If you don’t specify dbdir, check uses the database in the current directory.

The check command can generate a lot of information, so consider redirecting all output, including stdout and stderr, to a file (as shown in the example).

When check has finished, review the output file. If your database is corrupted, run the rebuild command.

Rebuilding a Calendar Database

The rebuild command scans a calendar database and checks the calendar properties (calprops) events and todos (tasks) for corruption. If the rebuild command finds an inconsistency, it generates a rebuilt calendar database (.db files) in the cal_svr_base/opt/SUNWics5/cal/sbin/rebuild_db directory.

The rebuild command without the -g option rebuilds all databases except the group scheduling engine (GSE) database. To also rebuild the GSE database, include the -g option.

To determine if the GSE database has any entries, run the csschedule -v list command and then let the GSE finish processing the entries before you run the rebuild command.

To rebuild a calendar database

Stop Calendar Server.

Make a copy of your calendar database, if you haven’t already done so. Copy only the database (.db) files. You don’t need to copy any share (__db_name.share) or log (log.*) files.

Change to the cal_svr_base/opt/SUNWics5/cal/sbin directory. For example, on Solaris systems, enter:

cd /opt/SUNWics5/cal/sbin

Note If disk space is a problem for the sbin directory, run the rebuild command in a different directory.

Run the rebuild command on the copy of your calendar database:

./csdb rebuild /tmp/db /tmp/

If you don’t specify a database directory, rebuild uses the database in the current directory.The /tmp/ parameter species the destination directory for the rebuilt database.

To also rebuild the GSE database, include the -g option.

The rebuild command can generate a lot of information, so consider redirecting all output, including stdout and stderr, to a file.



Note	Always rebuild your calendar database using the latest backup copy. However, if you have experienced a significant loss of data and you have periodically backed up your database and have more than one copy available, rebuild from the latest copy to the oldest one. (The only drawback is that calendar components that were deleted will reappear in the rebuilt database.) For example, if you have three sets of backup calendar database files in directories db_0601, db_0615, and db_0629, run the rebuild command in the following sequence: ./csdb rebuild db_0629 ./csdb rebuild db_0615 ./csdb rebuild db_0601 The rebuild command then writes the rebuilt database to the cal_svr_base/opt/SUNWics5/cal/sbin/rebuild_db directory.

When rebuild has finished, review the output in the rebuild.out file. If the rebuild was successful, the last line in the rebuild.out file should be:

Calendar database has been rebuilt

After you have verified that rebuild was successful in the previous step, copy the rebuilt database (.db) files from the rebuild_db directory to your production database.

If you have any share (__db_name.share) or log (log.*) files from the corrupted database, move them to another directory.

Restart Calendar Server.

Using the Dump and Load Procedure to Recover a Database

If the csdb rebuild command is not successful, the next step is to use the dump and load procedure to try to recover a corrupted database. The dump and load procedure uses the Berkeley database db_dump and db_load utilities, which Calendar Server includes in the following directory:

The db_dump utility reads a database file and writes the database entries to an output file, using a format that is compatible with the db_load utility.

For documentation about the db_dump and db_load utilities, refer to the Sleepycat Software Web site:

Your success in recovering a database using the db_dump and db_load utilities depends on the degree of corruption of your database. You might need to try several db_dump options before you successfully recover your database. If your database is severely corrupted, however, recovery might not be possible, and you might need to revert to your last good backup of your database.

Calendar Database Version

Before you perform the dump and load procedure, your calendar database must be Berkeley DB version 3.2.9. If you have an earlier version, first run the cs5migrate utility to upgrade your calendar database.

For information about running cs5migrate, refer to the Sun ONE Calendar Server 6.0 Installation Guide for Solaris Operating Systems.

To perform the dump and load procedure

On Solaris Systems, log in as the user and group under which Calendar Server is running, such as icsuser and icsgroup, or as superuser (root).

Stop Calendar Server, if necessary.

Backup your corrupted database using a utility such as csbackup, the Sun StorEdge Enterprise Backup™ software, or Legato Networker®. For more information refer to Chapter 6, "Backing Up and Restoring Calendar Server Data."

Dump each corrupted database file using the db_dump utility. The database files are ics50calprops.db, ics50journals.db, ics50alarms.db, ics50events.db, ics50todos.db, and ics50gse.db.

Run db_dump using the following options, in order, until your database is recovered (or until you determine that the database can’t be recovered):

No options for minor database corruption.

-r option for moderate database corruption.

-R option for severe database corruption. The -R option dumps more data than the -r option, including partial and deleted records, from the corrupted database.

For example, to run db_dump with the -r option:

db_dump -r ics50events.db > ics50events.db.txt

Load the output file into a new database file using the db_load utility. For example:

db_load new.ics50events.db < ics50events.db.txt

Note If db_load reports an odd number of keys or data entries, edit the db_dump output file from Step 4 and remove the odd key or data entries. Then run db_load again.

Repeat Step 4 and Step 5 for the other corrupted database files.

Rebuild the recovered database files using the csdb rebuild command, as described in Rebuilding a Calendar Database.

When rebuild has finished, review the output in the output file. If the rebuild was successful, the last line in the rebuild.out file should be:

Calendar database has been rebuilt

If the csdb rebuild command was not successful, return to Step 4 and dump your database using the next db_dump option (-r or -R).

If the db_dump -R option does not recover your corrupted database, contact your Sun Microsystems technical support or sales account representative for assistance. You might need to revert to your last good backup of your database.