Sun Java System Calendar Server 6.3 Administration Guide

Part II Post Installation Configuration for Calendar Server 6.3 Software

The chapters in this part describe the configuration and migration steps you must perform, after installation, before you can use Calendar Server.

This part includes the following chapters:

Chapter 2 Initial Runtime Configuration Program for Calendar Server 6.3 software (csconfigurator.sh)

After you install Calendar Server, and before running it, you must configure it. It is important that you run the two configuration programs in the following order:

  1. comm_dssetup.pl

    Configure the LDAP directory server as instructed in the Sun Java System Communications Suite 5 Installation and Configuration Guide.

  2. csconfigurator.sh

    Configure Calendar Server as described in this chapter.

This chapter contains the following topics:


Note –

If you had an earlier version of Calendar Server or Messaging Server installed, you might need to migrate your LDAP directory entries from Schema version 1 to Schema version 2.

Do not run the configuration utility described in this chapter until you have read the Sun Java Communications Suite 5 Schema Migration Guide. It will instruct you on the timing and options for running the configuration utilities.


2.1 Gathering Your Configuration Information for Calendar Server 6.3 Software

The Calendar Server configuration program csconfigurator.sh, creates a new ics.conf configuration file in the following directory:

For Solaris: /etc/opt/SUNWics5/config

For Linux: /etc/opt/sun/calendar/config

The configuration program will ask you many questions for which you must enter specific information about your installation.

Before running the configuration program, you should gather the following configuration information:

To help you keep track of the configuration information, use the worksheets in Appendix B, Calendar Server Configuration Worksheet. (However, you should determine this information before you run the Java Enterprise System installer to avoid conflicts (such as port numbers) with other component products.)

2.1.1 LDAP Server Options

Calendar Server requires a directory server for user authentication and for the storage and retrieval of user preferences. The following table lists the options used to gather host and port information for the LDAP server.

Table 2–1 User Preferences Directory Options

Option  

Description  

LDAP Server Host Name 

Host name of the LDAP directory server you are using for user authentication and user preferences. The default is the current host. 

LDAP Server Port 

Port number that the LDAP directory server listens on. The default is 389. 

2.1.2 Directory Manager Options

The following table lists the options used to gather the name and password of the user that is designated the Directory Manager.

Table 2–2 Directory Manager Options

Option  

Description  

Directory Manager DN 

User name that can make changes in the directory server schema. The default is cn=Directory Manager.

Directory Manager Password 

Password of the Directory Manager DN. The password is not stored in plain text. There is no default. 

2.1.3 Calendar Server Administrator

The Calendar Server Administrator is the user account that overrides any other Calendar Server ACLs. The Calendar Server Administrator user account must exist in your user authentication directory server. It is also used for proxy authentication. The following table lists the options used to gather the Calendar Server Administrator’s user ID and password.

Table 2–3 Calendar Server Administrator Options

Option  

Description  

Administrator User ID 

User ID of the Calendar Server Administrator; must be a user in the above LDAP directory server. The default is calmaster.

Administrator Password 

Password of the Calendar Server Administrator. There is no default. 

2.1.4 Email and Email Alarms Options

You can configure Calendar Server to send an email alarm message to a Calendar Server Administrator in case a server problem occurs. The following table lists the options used to gather email information.

Table 2–4 Email and Email Alarms Options

Option  

Description  

Email Alarms 

Enables or disables email alarms. The default is Enabled. 

Administrator Email Address 

Email address of the Calendar Server Administrator who will receive the email alarm messages. 

SMTP Host Name 

Host name of the SMTP server used by the Calendar Server system to send email alarm messages. The default is the current host. 

2.1.5 Runtime Configuration Options

You can configure the following Calendar Server runtime and system resource options.

Table 2–5 Runtime Configuration Options

Option  

Description  

Service Port 

Port number that Calendar Server listens on to provide Web (HTTP) access to users. The default is 80.

Maximum Sessions 

Maximum number of Calendar Server sessions to allow concurrently. The default is 5000.

Maximum Threads 

Maximum number of Calendar Server threads to allow concurrently. The default is 20.

Number of Server Processes 

For Solaris: Maximum number of Calendar Server processes to run concurrently. The default is the number of CPUs on the server where you are installing Calendar Server. 

For Linux: Only one process can run at a time.

Runtime User ID 

UNIX user name under which Calendar Server will run. This user name should not be root. If the account does not exist, the configuration program will create it. The default is icsuser.

Runtime Group ID 

UNIX group under which Calendar Server will run. If the group does not exist, the configuration program will create it. The default is icsgroup.

2.1.6 Calendar Server Startup

You can configure the following options to automatically start Calendar Server.

Table 2–6 Calendar Server Startup Options

Option  

Description  

Start after successful installation  

Whether to start Calendar Server automatically after a successful installation. The default is checked. 

Start on system startup 

Whether to start Calendar Server automatically after a system startup. The default is checked. 

2.1.7 Database, Logs, and Temporary Files Directories

Calendar Server creates and stores information in calendar database files, log files, and temporary files in specific directories.

Table 2–7 Database, Logs, and Temporary Files Directories Options

Option  

Description  

Database Directory 

Directory where the Calendar Server system creates and stores the calendar database (*.db) files. The default is:

/var/opt/SUNWics5/csdb

Logs Directory 

Directory where Calendar Server writes log files. The default is: 

/var/opt/SUNWics5/logs

Temporary Files Directory 

Directory where the Calendar Server system writes temporary files. The default is: 

/var/opt/SUNWics5/tmp

Archive and hot backup Directories 

Directory where the Calendar Server system writes archive backups. User defined directory for storing the daily snapshot and transactions logs. If both types of backups are desired, then place them in different directories. If no directory is specified, backups are stored in the current directory. 

Attachment Store Directory 

Directory where the Calendar Server system stores attachments to events and tasks. 


Note –

Do not change the location or names of the logs and temporary files directories.


2.2 Running csconfigurator.sh

You can run the configuration program from a graphical user interface (GUI), or from the command line.

If you run the program remotely, you must set your DISPLAY environment variable properly and allow X-Windows connections from the server to display on your computer. For example, to use the xhost utility, execute the following command on your computer:

# xhost +

This section contains the following topics:

ProcedureTo Run the Configuration Program from the Command Line

  1. Login as or become superuser (root).

  2. Change to the /opt/SUNWics5/cal/sbin directory.

  3. Run the script using the options chosen from the following table:

    Option 

    Description 

    -nodisplay

    Run the configuration script in text-only mode (non-GUI). 

    -noconsole

    Do not display text output. Use this with -nodisplay to run the configuration script in silent mode.

    -novalidate

    Do not validate input field text. 

    -saveState [statefile]

    Save the answers that you input in response to configuration questions to a state file (text file). Unless you specify a fully qualified path for the state file, it will be saved in the default directory: /opt/SUNWics5/cal/jconfigure.

    -state [statefile]

    Use the state file for setting input values. This option must be used in conjunction with -novalidate and -noconsole.

    For example, to run the configuration script in command-line mode, issue the following command:

    ./csconfigurator.sh -nodisplay

    The command-line version asks for the same information and in the same order as the GUI. Default values are indicated in square brackets, []. To accept a default value, press Enter on your keyboard.


    Note –

    For the text of the information contained in the various questions presented by the script, see the text in the GUI screens shown in the sections that follow.


ProcedureTo Run the Configuration Program from the GUI

  1. Login as or become superuser (root).

  2. Change to the /opt/SUNWics5/cal/sbin directory.

  3. Run the command:

    ./csconfigurator.sh

    The configuration program displays the following series of screens:


    Caution – Caution –

    The configuration program only configures a single domain. If you plan to use multiple domains, you need to add the domains using Delegated Administrator.



    Note –

    The title bars for all screens are incorrect. The version is 6.3, not 6.5 as shown.


2.3 Welcome Screen

Figure 2–1 Calendar Server Configuration Program Welcome Screen

This is the initial screen of the configuration GUI.

Click Next to continue or Cancel to exit.

2.4 Administration, User Preferences and Authentication Screen

Figure 2–2 Administration, User Preferences and Authentication Configuration Screen

This is the screen where you input LDAP Directory Manager
and LDAP server information. The input boxes are labeled User Preferences
Directory.

2.4.1 User Preferences Directory Options

LDAP Server Host Name

Host name of the LDAP directory server you are using for user authentication. Default: current host

LDAP Server Port

Port number that the LDAP server listens on. Default: 389

Directory Manager DN

User name that can make changes in the directory server schema. Default: cn=Directory Manager

Directory Manager Password

Password of the Directory Manager. This will not be stored in plain text. Default: None

2.5 Virtual Domains and Calendar Administrator Screen

Figure 2–3 Virtual Domains and Calendar Administrator Screen

This screen contains settings for virtual domains (multiple
domains) and the calendar administrator.


Note –

Virtual domains, hosted domains and multiple domains are all names for the same ability to have more than one LDAP domain with its corresponding user and group records.


If you are upgrading from a non-virtual domain environment, the Enable Virtual Domains Support checkbox must be selected. If you already have a multiple domain environment, the checkbox is greyed out. Virtual domains support is now the default behavior of Calendar Server, and is not optional.

2.5.1 Virtual Domains Settings for Calendar Server 6.3

Figure 2–4 Virtual Domain Structure

This graphic shows three domains under the root domain.

Virtual domains support is now the default behavior for Calendar Server for fresh installations. Using the configuration program graphical user interface, enter a default domain name in the New Default domain input box. The configuration program then creates the domain for you.

Choose your default domain from one of those showing in the Default domain box. If you already used multiple domains in the previous version of Calendar Server, and you do not want to use the domain showing in the Default domain box, click the box to see the list of domains you can choose from and select a new default domain.

2.5.2 Calendar Administrator Name and Password for Calendar Server 6.3

Username

Username of the Calendar Server Administrator. Default: calmaster

Administrator Password

Password of the Calendar Server Administrator. Default: None

Email Address

Email address for the Calendar Server Administrator.

Site Administrator

The Site Administrator is the user that has proxy authentication rights across domains.

Click the appropriate response: Yes if the Calendar Administrator is also the Site Administrator. No if the Calendar Administrator is not the Site Administrator.

Click Next to continue, Back to return to the previous screen, or Cancel to exit.

2.6 Email and Email Alarms Screen for Calendar Server 6.3

Figure 2–5 Email and Email Alarms Configuration Screen

This is the email alarms screen. You choose to enable
or disable email alarms and then input the Administrator Email Address and
the SMTP Host Name.

Email Alarms

Specifies whether Calendar Server should send an email alarm message to a Calendar Server administrator in case a server problem occurs. Default: disabled. If you choose Disabled, no administrator receives email alarms for server problems.

Administrator Email Address

Email address of the Calendar Server Administrator who will receive the email alarm messages. Default: None

SMTP Host Name

Host name of the SMTP server where used to send alarm messages. Default: current host.

Click Next to continue, Back to return to the previous screen, or Cancel to exit.

2.7 Runtime Configuration Screen for Calendar Server 6.3

Figure 2–6 Runtime Configuration Screen

This is a screenshot of the Runtime configuration screen.

Service Port

Port number that Calendar Server listens on to provide Web (HTTP) access to users. Default: 80.

Maximum Sessions

Maximum number of concurrent Calendar Server sessions. Default: 5000

Maximum Threads

Maximum number of concurrent Calendar Server threads. Default: 20

Number of Server Processes

Maximum number of Calendar Server processes to run on the server. Default: Number of CPUs on the server where you are installing Calendar Server.

Runtime User ID

UNIX user name under which Calendar Server will run. If the account does not exist, the configuration program will create it. Default: icsuser


Caution – Caution –

Do not use root as the Runtime User ID.


Runtime Group ID

UNIX group under which Calendar Server will run. If the group does not exist, the configuration program will create it. Default: icsgroup

Calendar Server Startup Options

Select one or both options by clicking in the check box.

  • Start after successful configuration

    Specifies whether to start Calendar Server automatically after this configuration program successfully finishes running.

  • Start on system startup

    Specifies whether to start Calendar Server automatically after a system startup.


Note –

By default, only the Start on system startup checkbox is selected.


Click Next to continue, Back to return to the previous screen, or Cancel to exit.

2.8 Set Up a Front End-Back End Deployment Screen for Calendar Server 6.3

Choose whether to configure this server as a single server deployment, or a front-end, back-end deployment. If you choose to have a single server instance of Calendar Server, then do not select the checkbox on this screen. If you want to put your Calendar Server databases on one or more servers, while keeping the processes that communicate with the client on a different server, select the checkbox.

This section covers the following topics:

2.8.1 Single Server Deployment for Calendar Server 6.3

Figure 2–7 Single Server Deployment

This is the screen used to choose your deployment option:
Front End and Back End, or Single Machine.

Do not change any part of this screen if you want a single server deployment where both the administrative processes and the databases reside on one server. Click Next to continue.

If you wish to deploy separate Front End and Back End machines, click the checkbox labeled: Setup a Front End/Back End deployment. The screen will change and you will be allowed to configure the front-end and back-end servers separately, as shown in the following two screen shots.

2.8.2 Front-End and Back-End Deployment for Calendar Server 6.3

Figure 2–8 Set Up a Front-End and Back-End Server

The Front-End, Back-End screen allows you to specify
the back-end service port and the front-end host names.

To complete this screen, perform the following steps:

  1. To configure the back-end server, that is, the server on which to store calendar databases, you need only specify the service port.

    The service port entry box is pre-filled with the port named in the ics.conf parameters service.dwp.server.hostname.port and service.dwp.port.

    If you want to change the port number, enter the desired port number in the Service Port entry box.

  2. To configure the front-end server, click Add a Host and then enter the host name and IP address of the server you are configuring.


    Note –

    Add only the server you are currently configuring to the list. If you plan to configure other front-end servers, add them at the time you configure them. (You must run the configuration program on each server you add to your configuration.)


  3. If this server is the default front-end server, select the Default checkbox.

  4. Click Next.


    Note –

    You may also remove servers from this list by clicking Remove Selected Host.


2.9 Directories to Store Configuration and Data Files Screen for Calendar Server 6.3

Accept the default directories on this screen. While you are allowed to choose the store configuration and data files directories, it is not advised.

Figure 2–9 Select Directories Configuration Screen

This is the Directories to Store configuration and data
files screen.

Config Directory

Directory where the configuration file (ics.conf) resides.

Database Directory

Directory where Calendar Server creates and stores the calendar database files. Default: /var/opt/SUNWics5/csdb

Attachment Store Directory

Directory where the attachment store resides. Default: /var/opt/SUNWics5/astore

Logs Directory

Directory where Calendar Server writes log files. Default: /var/opt/SUNWics5/logs

Temporary Files Directory

Directory where the Calendar Server writes temporary files. Default: /var/opt/SUNWics5/tmp

Then, Click Next to continue, Back to return to the previous screen, or Cancel to exit.


Note –

If any of these directories do not already exist, a pop-up window appears for each missing directory. Click the appropriate button to choose whether to have the configuration program create the new directory, or to return you to the screen where you can choose a different directory.

For any directory that already exists but is not empty, a pop-up window appears with two choices. Click the appropriate button to accept the directory anyway, or to return to the screen where you can choose a different directory.


2.10 Archive and Hot Backup Configuration Screen for Calendar Server 6.3

This screen allows you to select both automatic backup types, or either one of the two, or none. Select or deselect the boxes appropriately. Using both archive backups and hot backups is strongly recommended.


Tip –

Prevent the catastrophic loss of all your database copies due to an equipment failure. Keep your automatic backup copies on a disk or disk system other than the one where your live databases reside.


For information on automatic backups, see Chapter 9, Configuring Automatic Backups (csstored).

Figure 2–10 Archive and hot backup Configuration Screen

This is the Archive and Hot Backup screen. You can choose
to enable the individual type of backups.

Enable Archive

When this box is selected (default), csstored will take a snapshot of your calendar databases every 24 hours. Throughout the day, at regular intervals, it stores the transaction log files for that day with the snapshot in the archive backup directory.

If this box is not checked, the Archive Directory input field is greyed out.

Archive Directory

Choose the backup directory by clicking Browse, or accept the default.

Enable Hot Backup

When this box is selected (default), csstored takes a snapshot of your calendar databases every 24 hours, then applies the transaction logs to the snapshot at a set interval (default is two minutes), throughout the day, ensuring a nearly complete duplicate of your live database.

If this box is not checked, the Hot Backup Directory input field is greyed out.

Hot Backup Directory

Choose the backup directory by clicking Browse, or accept the default.

Keep Archives for (in days)

This field is only active if the Enable Archive box is selected; otherwise, it is greyed out.

Click the up or down arrows in the Minimum and Maximum fields to select range of days of archival backups to keep in the backup directory.

Keep Hot Backups for (in days)

This field is only active if the Enable Hot Backup box is selected; otherwise, it is greyed out.

You can set the number of hot backups to keep in two ways:

  • Click the up or down arrows in the Minimum and Maximum fields to select the range of days of hot backups to keep in the directory.

    The number of copies actually stored at any one time depends on the size of the files and the size of the directory. When either the size limits, or maximum number of copies exceeds the limit, the oldest copies are purged down to the minimum number specified on this configuration screen.

  • If you want the same settings for Hot Backups as for Archival Backups, you can check the Same As Archive box.

Click Next to continue, Back to return to the previous screen, or Cancel to quit the configuration program.

2.11 Ready to Configure Screen for Calendar Server 6.3

Up to now the screens have been gathering data needed for the configuration and performing some validity checking. You can go back and redo the configuration information at this point, or start the configuration.

Figure 2–11 Ready to Configure Screen

This is the Ready to Configure screen. You click Configure
Now to start the configuration program running.

Click Configure Now to configure Calendar Server, Back to return to the previous screen, or Cancel to exit.

2.12 Sequence Completed Screen for Calendar Server 6.3

Figure 2–12 Sequence Completed Screen

This is the Sequence Completed screen. You can see the
tasks complete as the configuration program executes.

This panel provides a running update of all the tasks and the disposition (passed or failed). When the message “All Tasks Passed”, the configuration has finished. Check the log files indicated to see if there are any error messages.

Click Next when the configuration program completes.

2.13 Configuration Summary Screen for Calendar Server 6.3

Figure 2–13 Configuration Summary Screen

This is the Configuration Summary panel. You can choose
to view details or to exit.

Click Details to view the details of the configuration log or Close to exit the configuration program.

Chapter 3 Database Migration Utilities for Calendar Server 6.3

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:


Tip –

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.


3.1 An Overview of Calendar Server Database Migration Utilities

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.


Tip –

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:

3.5 csmig Utility

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.

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

3.4 cs5migrate Utility

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.

3.3 csmigrate Utility

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.

3.7 commdirmig

Migrates LDAP data from Schema version 1 to Schema version 2 in preparation for use with Access Manager (in Legacy mode).

3.2 Choosing the Right Calendar Server Utilities

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:


Note –

Run the utilities in the order given.


Table 3–1 Choosing the Right Utilities

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.  

3.3 csmigrate Utility

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:

3.3.1 csmigrate Utility Syntax

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:

-q (optional)

Specifies quiet mode and no print instructions.

-d (optional)

Specifies dry run mode and no new database written.

-l min|max (optional)

Specifies log level. The migration logs are written to csmigrate.log and errors are written to csmigrateError.log in the default logs directory.

-b backup_dir (optional)

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.

-source_dbdir (mandatory)

The directory where pre-migration database files are located.

-target_dbdir (mandatory)

The directory where post-migration files are created.

-V (other supported option)

To print the version information of the tool.

-? (other supported option)

To print the usage information of the tool.


Note –

The exit codes for the program are 255 on failure and 0 on success.


3.3.2 csmigrate Example

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

ProcedureHow to Run the Calendar Server csmigrate Utility

  1. Log in with root privileges.

  2. Stop all services.

    For example, issue the following command:

    stop-cal
  3. 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
  4. 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/
  5. 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
  6. Restart calendar services.

    For example, use the following command:

    stop-cal

3.4 cs5migrate Utility

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:


Note –

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.

3.5 csmig Utility

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:

3.5.1 csmig Utility Functions

The csmig migration utility performs the following functions:

3.5.1.1 Migrates Calendars

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.

3.5.1.2 Assigns Owners to Calendars

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:

3.5.1.3 Updates LDAP Attributes

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.

3.5.2 csmig Utility Requirements

The requirements for using csmig are:

3.5.3 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 }

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.

3.5.4 csmig Utility Migration Steps

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:

ProcedureHigh Level Steps for Using csmig

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

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

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

ProcedureTo Perform a Test Dry Run

  1. Install Calendar Server 6.3 (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 comm_dssetup.pl to configure the staging Directory Server.

  5. Run csconfigurator.sh 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:


    ./csuser -g orphan -s adminuser -y password -l en -c orphan create orphan
  10. Stop the Calendar Server using the stop-cal command (if necessary).

    cal-svr-base/SUNWics5/cal/sbin/stop-cal

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

  12. Check the output mapping file (csmig.map). The mapping file lists entries that need to be updated in the LDAP schema.

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

  14. 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
  15. 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 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.

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

    cal-svr-base/SUNWics5/cal/sbin/stop-cal

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

  5. 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
  6. 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.

  7. Run the csdb check command to check your migrated database. If any corruption is indicated, run csdb rebuild to rebuild the database.

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

  9. 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 = "59779"

    • csapi.plugin.calendarlookup = "yes"

    • 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 /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.

  10. Restart Calendar Server using the start-cal command.

  11. 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":

    • 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"

3.5.5 csmig Tips and Troubleshooting

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.

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.

3.5.5.2 The LDAP calendar search doesn’t work correctly.

Example Problem

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

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

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

3.5.5.4 How do I assign orphan calendars to different owners?

Example Problem

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

Example Solution

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.

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

Example Problem

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

Example 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 instructions on how to move calendars, see 15.6 Managing User Calendars.

3.6 csvdmig

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.


Note –

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:

3.6.1 csvdmig Functions

The csvdmigutility performs the following changes to your databases and LDAP entries:


Caution – Caution –

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.


3.6.2 csvdmig Syntax

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

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

user1 user1@sesta.com
user2 user2@siroe.com
user3 user3@sesta.com
 ...
usern usern@siroe.com

3.6.2.2 Destination DB

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.

3.6.3 csvdmig Examples

The following are csvdmig examples

3.7 commdirmig

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.

3.7.1 Who Should Run the commdirmig Utility

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.


Note –

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


3.7.2 When to Run the commdirmig Utility

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.

3.7.3 Where to Find Documentation on the commdirmig Utility

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.

3.7.4 Where to Find the Utility

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.