Sun Java System Calendar Server 6.3 Administration Guide

Part IV Calendar Server 6.3 Administration

This section contains chapters dealing with administration of your Calendar Server deployment.

This part contains the following chapters:

Chapter 12 Server Administration for a Calendar Server 6.3 Deployment

This chapter describes server administration for a Calendar Server deployment.

This chapter contains the following sections:

You manage Calendar Server by running either the Delegated Administrator utility (formerly the User Management Utility) or the Calendar Server command-line utilities and by editing the ics.conf configuration file.

To run the command-line utilities, you must log in as a user who has administrative rights to the system where Calendar Server is running.

For more information, see Appendix D, Calendar Server Command-Line Utilities Reference.

Note –

Additional administration topics are covered in separate chapters.

The chapters cover the following topics:

12.1 Starting and Stopping Calendar Server 6.3 Processes

This section contains conceptual information and instructions on how to use the start-cal and stop-cal commands.

This section contains the following topics:

12.1.1 About Calendar Server 6.3 Commands: start-cal and stop-cal

You can start and stop Calendar Server using the start-cal and stop-cal commands.The start-cal and stop-cal utilities are located in the cal-svr-base/SUNWics5/cal/sbin directory. You must run these utilities on the local machine where Calendar Server is installed.

Note –

Check your scripts to make sure you do not use the old csstart and csstop utilities. Use the start-cal and stop-cal utilities to start and stop Calendar Server.

The start-cal utility starts Calendar Server services in the following order:

watcher — Watcher, the process that monitors the system
enpd— Event Notification Service (ENS)
csstored— Automatic Backup Service
csnotifyd— Notification Service
csadmind— Administration Service
csdwpd— Database Wire Protocol (DWP) service, the distributed database service starts only if you have a remote Calendar Server database configuration
cshttpd— HTTP Service

For a description of these services, see1.10 Services Running As Daemons in Calendar Server Version 6.3

To Start Calendar Server 6.3 Services with start-cal

Verify that all Calendar Server services are stopped by issuing the stop-cal command.

Change to the directory.

cal-svr-base/SUNWics5/cal/sbin

Start Calendar Server.

./start-cal

To Stop Calendar Server with stop-cal

Change to the directory.

cal-svr-base/SUNWics5/cal/sbin

Stop Calendar Server.

./stop-cal

12.2 Enabling or Disabling Automatic Backups in Calendar Server Version 6.3

Automatic backups are managed by the csstored process that starts up automatically when start-cal is issued. However, you can either enable or disable automatic backups at will. The default is for automatic backups to be disabled. The csstored process runs even if automatic backups are not enabled.

There are two kinds of automatic backups: hot backups and archival backups. You enable or disable them separately.

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

The following is a list of tasks for enabling and disabling automatic backups:

To Enable Hot Backups in Calendar Server Version 6.3

Stop Calendar Server services by issuing the stop-cal command.

Change to the directory where the ics.conf file is located.

cd /etc/opt/SUNWics5/config

Enable hot backups by setting the following ics.conf parameter to “yes”:

caldb.berkeleydb.hotbackup.enable="yes"

Specify the directory path for the hot backup directory:
```
caldb.berkeleydb.hotbackup.path=
   /var/opt/SUNWics5/hotbackup_directory
```
The default is the current directory.

When you have completed editing the ics.conf file, restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

The calendar services do not need to be stopped to edit the ics.conf file, but you must restart the services in order for the changes to take effect.

To Enable Archive Backups in Calendar Server Version 6.3

Stop Calendar Server services by issuing the stop-cal command.

Change to the directory where the ics.conf file is located.

cd /etc/opt/SUNWics5/config

Enable archive backups by setting the following ics.conf parameter to “yes”:

caldb.berkeleydb.archive.enable=”yes”

Specify the directory path for the archive directory.
```
caldb.berkeleydb.archive.path=
   /var/opt/SUNWics5/hotbackup_directory
```
The default is the current directory.

When you have completed editing the ics.conf file, restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

The calendar services do not need to be stopped to edit the ics.conf file, but you must restart the services in order for the changes to take effect.

To Disable Hot Backups in Calendar Server Version 6.3

Backups are disabled by default. If you have previously enabled them and want to disable them, perform the following steps:

Stop Calendar Server services by issuing the stop-cal command.

Change to the directory where the ics.conf file is located.

cd /etc/opt/SUNWics5/config

Disable hot backups by setting the following ics.conf parameter to "no":

caldb.berkeleydb.hotbackup.enable="no"

When you have completed editing the ics.conf file, restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

The calendar services do not need to be stopped to edit the ics.conf file, but you must restart the services in order for the changes to take effect.

To Disable Archive Backups in Calendar Server Version 6.3

Backups are disabled by default. If you have previously enabled them and want to disable them, perform the following steps:

Stop Calendar Server services by issuing the stop-cal command.

Change to the directory where the ics.conf file is located.

cd /etc/opt/SUNWics5/config

Disable archive backups by setting the following ics.conf parameter to "no":

caldb.berkeleydb.archive.enable="no"

When you have completed editing the ics.conf file, restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

The calendar services do not need to be stopped to edit the ics.conf file, but you must restart the services in order for the changes to take effect.

12.3 Managing the Group Scheduling Engine Queue for Calendar Server Version 6.3

This section contains conceptual information and instructions for managing the Group Scheduling Engine (GSE)

The GSE keeps a queue of events that will be used to update the component database. An administrator can change the timeout value to adjust the time between Calendar Server scans of the queue. Events in the queue can also be listed and specific events deleted if necessary.

This section contains the following topics:

12.3.1 About GSE for Calendar Server Version 6.3

The GSE allows a Calendar Server user to create events and invite other attendees. If an attendee is on the same Calendar Server, the event is scheduled in the attendee’s calendar. If an attendee is not on the same Calendar Server, the invitation is sent via email. The attendee can then accept or decline the invitation and the GSE will update the event with the reply.

12.3.2 About the Calendar Server 6.3 GSE Queue

The GSE queue is in reality a separate database managed by the csadmind process Calendar Server scans the queue for updates that need to be made to the components database.

You can tune Calendar Server by adjusting the frequency of this scan. This is accomplished by changing the timeout value of gse.belowthresholdtimeout in the ics.conf file. See Chapter 21, Tuning Calendar Server Performance.

The GSE queue entries can be managed (listed and deleted) using csschedule. You must run csschedule on the local machine where Calendar Server is installed.

12.3.3 Listing Entries in the Calendar Server 6.3 GSE Queue

To list entries in the GSE queue, use the csschedule utility list command.

For example, to list all entries in the GSE queue:

csschedule list

To list the first ten entries stored in the GSE queue:

csschedule -c 10 list

To list all entries in the GSE queue for a calendar with the calid Holiday_Schedule:

csschedule -v list Holiday_Schedule

12.3.4 Deleting Entries in the GSE Queue in Calendar Server Version 6.3

To delete entries in the GSE queue, use the csschedule utility delete command.

For example, to delete all entries in the GSE queue:

csschedule -v delete

To delete the entry in the GSE queue for calendar calA with the first schedule time of 13:30:45 on 11/30/2001, an offset number of 1, the unique identifier 1111, the recurrence ID 0, and the sequence number 0:

csschedule -v -t 20011130T133045Z -o 1 -u 1111 -r 0 -n 0 delete calA

12.4 Monitoring Calendar Server 6.3 Processes

Calendar Server and Messaging Server now use the same stop and start mechanism, as part of the Sun Java^TM Enterprise System Monitoring Framework (JESMF). The start-cal command starts the watcher process first, and then starts all other processes. The watcherprocess is aware of any dependencies the other services have, and in which sequence the services should be started.

Each registered service (process) opens a connection to the Watcher. If a process dies without properly disconnecting, the Watcher automatically restarts it. If the process dies twice in a defined interval, Watcher does not restart it. This timeout interval is configurable.

Watcher writes to a single log, cal-svr-base/data/log/watcher.log , which contains the following information:

Failure notices and non-response error messages that were sent to the administrative console.
Records of all server stops and starts.

For information on how to configure Watcher, seeTo Configure the Watcher Process for Calendar Server Version 6.3

12.5 Clearing the CLD Cache in Calendar Server Version 6.3

This section covers conceptual information and instructions on how to clear the CLD cache.

This section covers the following topics:

12.5.1 Why Clear the Calendar Server 6.3 CLD Cache?

If you have enabled the CLD Cache, you might need to clear the cache from time to time. The CLD cache can get out of sync (stale) with your system configuration for various reasons.

The following are a few reasons the CLD cache might become stale.

You add, delete or rename a server.
You move a server from one function to another in your configuration.
You move one or more calendars to different back-end servers.

If any of these things happen, in order to refresh the CLD cache, you must clear it.

To Clear the CLD Cache

Stop Calendar Server.

Remove all files in the /var/opt/SUNWics5/csdb/cld_cache directory, but do not remove the cld_cache directory itself.

Restart Calendar Server.

12.6 Changing a Server Name

If you add, delete or change a server name in your configuration, there are several “housekeeping” steps you should perform to avoid errors.

The following steps are useful to keep your CLD uptodate:

Clear the CLD Cache
If an old server is taken out, delete it from the ics.conf parameters where it appears.

12.7 Configuring Anonymous Access for Calendar Server Users

This sections contains instructions on how to enable and disable anonymous access (login).

Anonymous access is a special login that does not require authentication. With anonymous login enabled, read and write access to public calendars is enabled by default. It is possible to deny write access to the public calendars.

This section covers the following topics:

Note –

Communications Express expects anonymous logins to be allowed for writing as well as reading. See 4.1 Configuring for Communications Express.

To Enable Anonymous Access

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit the following parameters in the ics.conf to enable anonymous access:

Parameters	Description and Default Value
`service.http.allowanonymouslogin`	Enable anonymous access (login) by setting this parameter to `“yes”`, if necessary. The default value is `“yes”`.
`service.calendarsearch.ldap`	For security purposes with anonymous logins enabled, you might want to disable searching through the LDAP first when doing calendar searches, by setting this parameter to `“no”`, which is the default.

Note –

Communications Express expects the value of the service.calendarsearch.ldap parameter to be “no”. This conflicts with instructions given for tuning your system for best performance in a DWP environment. (Your database is distributed across multiple back-ends.) See 21.2 Improving Calendar Search Performance in a DWP Environment.

Save the file as ics.conf.

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

To Disable Anonymous Users from Writing to Public Calendars

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit the following ics.conf parameter as shown in the following table:

Parameter	Description and Default Value
`service.wcap.anonymous.` `allowpubliccalendarwrite`	Enables or disables allowing anonymous access users to write to public calendars. Enable access by setting the value to `“yes”`, which is the default.

Parameter

Description and Default Value

service.wcap.anonymous.

allowpubliccalendarwrite

Enables or disables allowing anonymous access users to write to public calendars. Enable access by setting the value to “yes”, which is the default.

Save the file as ics.conf.

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

12.8 Enabling Proxy Administrator Logins

Proxy administrator logins (proxy authentication) must be enabled for Communications Express. For instructions on configuring proxy authentication for Communications Express, see 4.1 Configuring for Communications Express.

However, proxy authentication can be enabled even if you are not using Communications Express. This section contains the procedure for enabling proxy authentication without Communications Express:

To Enable Proxy Authentication without Communications Express

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit the ics.conf file, confirming that the following parameter is set as shown:

service.http.allowadminproxy = "yes"

If not, change it to "yes".

Save the file as ics.conf.

Restart Calendar Server for the new value to take effect.

To Verify Proxy Authentication is Working

Verify that administrator proxy logins are working by using the following WCAP command:
```
http://server[:port]/login.wcap?
user=admin-user&password=admin-password
&proxyauth=calendar-user&fmt-out=text/html
```
This list defines the variables in the previous example:
- server– The name of the server where Calendar Server is running.
- port– The Calendar Server port number. The default port is 80.
- admin-user – The Calendar Server administrator. For example, calmaster.
- admin-password – The password for admin-user.
- calendar-user – The calid of the Calendar Server user.
If the command is successful, the system displays the calendar for calendar-user. If problems occur, the system displays Unauthorized.

The following is a list of some reasons the command might fail:
- The admin-user does not have Calendar Server administrator privileges.
- The admin-password is incorrect.
- The calendar-user is not a valid Calendar Server user.

12.9 Refreshing the Calendar Server Configuration

In the Calendar Server 6.3 release, use the stop-cal and start-cal commands to refresh a configuration. For more information, see 12.1 Starting and Stopping Calendar Server 6.3 Processes.

Chapter 13 Administering Calendar Server Domains

This chapter contains conceptual information and instructions on how to administer domains in your Calendar Server deployment.

This chapter contains the following sections about administering multiple domains:

13.1 Choosing the Correct User Management Tool

There are two ways to administer Calendar Server domains.

Use one of the two following set of tools:

Delegated Administrator Console or Utility (for Schema version 2 environments).

Delegated Administrator is a separately installable component in the Java Enterprise System installer. For more information on the Utility, see the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide. For more information on the Console, use the Delegated Administrator Console online help.
Calendar Server Utilities: csdomain and csattribute (for Schema version 1 environments.)

Installed with Calendar Server. You can add or delete attributes with csdomain, but there is no modify command. Use csattribute to modify the value of an existing attribute. In addition, should the need arise, use ldapmodify to add or delete object classes in domains created with csdomain.

For information about csdomain and csattribute, see Appendix D, Calendar Server Command-Line Utilities Reference.

For information about particular object classes and attributes, see theSun Java System Communications Services 6 2005Q4 Schema Reference.

For an overview of multiple domains and other introductory material, see Chapter 10, Setting Up a Multiple Domain Calendar Server 6.3 Environment.

Caution –

Calendar Server does not support using the Access Manager Console for domain administration.

13.2 Creating New Calendar Server Domains

This section contains conceptual information and instructions for adding domains to your Calendar Server deployment. You can use either schema with multiple domains. However, if you have the choice, use Schema version 2 to take advantage of the superior tool set.

This section contains the following topics:

13.2.1 Overview of Creating Calendar Server Domains

Calendar Server software has multiple domains enabled by default. Do not change the value of the following ics.confparameter: service.virtualdomain.support="yes".

Once you have completed the preparation work described in Chapter 10, Setting Up a Multiple Domain Calendar Server 6.3 Environment, you can add new domains.

Each domain has a set of attributes and preferences that you can set. These attributes are part of the icsCalendarDomain object class. The attributes include preferences such as access rights, access control lists (ACLs), domain searches, access rights for domain searches, user status, and proxy logins.

13.2.2 To Add a Domain in Schema Version 2 Mode

This section contains instructions on how to add a domain in Schema version 2 mode.

You can use either the Delegated Administrator Console or Utility:

Console — Use the Create New Organization wizard on the Organization List page.

For more information, see the Delegated Administrator Console online help.
Utility — Use the commadmin domain create command.

For example, to create the domain sesta.com, issue the following command:
```
commadmin domain create -D calmaster
    -d sesta.com -w calmasterpassword -S cal 
    -B backend.sesta.com
```
For information about the Delegated Administrator Utility, see the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.

13.2.3 To Add a Domain in Schema Version 1 Mode

This section contains a simplified sample instruction for using the csdomain utility.

Use csdomain create when creating a domain in Schema version 1. For example, to create west.sesta.com, use the following command.

csdomain create west.sesta.com

For instructions on how to configure for multiple domains, see Chapter 10, Setting Up a Multiple Domain Calendar Server 6.3 Environment.

13.3 Enabling Cross Domain Searches

This section contains the instructions for enabling cross domain searches.

This section covers the two tasks you must do to enable cross domain searches:

13.3.1 Adding Names of Domains Allowed to Search This Domain in the LDAP entry for each of the domains allowed to search this domain.
13.3.2 Adding Names of Domains to be Searched by This Domain when users in this domain send invitations to events.

This can be done using either of the following tools: ldapmodify (for either Schema mode), or Delegated Administrator Console or Utility (for Schema version 2).

13.3.1 Adding Names of Domains Allowed to Search This Domain

Each domain LDAP entry specifies access permissions in ACE's, which are defined in the domainAccess parameter of the icsExtendedDomainPrefs attribute. Two different ways to allow external domains to search this domain are:

The construction of ACI's is explained more fully in 1.8 Access Control for Calendar Server Version 6.3.

13.3.1.1 To Allow Specific Domains to Search This Domain

This can be done three ways:

Using ldapmodify, create the following ACE string in the domainAccess preference of the icsExtendedDomainPrefs:

@domain_being_allowed^a^lsfr^g

Form the ACE by specifying the domain allowed to search this domain, followed by sufficient permissions to allow the search.

Caution –
Only one instance of the domainAccess property is allowed. If you change the value using ldapmodify, you must ensure that you do not inadvertently create a duplicate of this property.

Unlike how the system reads the ics.conf file sequentially, and honors the value of the attribute that it finds last, for LDAP entries, the system uses the first instance it finds. Since the LDAP search mechanism does not guarantee the entry contents will be served in any specific order, an older version of the property might be retrieved first and Calendar Server software wouldn't look any farther.
Using Delegated Administrator Utility command commadmin domain modify, add ACE strings specifying the domainAccess preference in icsExtendedDomainPrefs attribute.

For example, in a Schema version 2 environment, sesta.com allows searches from siroe.com:
```
commadmin domain modify -D admin
   -w adminpassword -X hostmachine_1 -d sesta.com 
   -A +icsextendeddomainprefs:"domainAccess=@@d^a^slfrwd^g;
      @siroe.com^a^lsfrwd^g;anonymous^a^r^g;@^a^s^g"
```
Using Delegated Administrator Console, when creating or editing an organization's properties, you can add domains to the Allow Invitations From Users in These Organizations list.

This updates the domainAccess preference in the icsExtendedDomainPrefs attribute.

Note –

While you can specify the exact permissions given to the domains in the first two methods just listed, the last one, using the Delegated Administrator Console, does not allow the administrator as much control. The list of permissions is preset. The permissions given are: free-busy access, and event scheduling access. The user can't see event details unless the owner of that calendar has set permissions to allow all users to read it.

13.3.1.2 To Allow All External Domains to Search This Domain

There are three ways to allow all external domains to search this domain:

Using ldapmodify, create the following ACE string in the domainAccess preference of the icsExtendedDomainPrefs:

@^a^slfr^g

Form the ACE by specifying that all domains have sufficient access to perform searches.
Using Delegated Administrator Utility command commadmin domain modify, add ACE strings specifying the domainAccess preference in icsExtendedDomainPrefs attribute.

For example, in a Schema version 2 environment, sesta.com allows searches by all domains:
```
commadmin domain modify -D admin 
   -w adminpassword -X hostmachine_1 -d sesta.com 
   -A +icsextendeddomainprefs:"domainAccess=@@d^a^slfrwd^g;
      anonymous^a^r^g;@^a^slfr^g"
```
Note –
The characters @@d refer to the domain of the primary owner.
Using Delegated Administrator Console, when creating or editing an organization's properties, you can add domains to the Allow Invitations From Users in These Organizations list.

This updates the domainAccess preference in the icsExtendedDomainPrefs attribute.

Note –

13.3.2 Adding Names of Domains to be Searched by This Domain

This section contains instructions for adding names of domains to be searched.

There are three ways to do add external domains to be searched by this domain:

Using ldapmodify, add one instance of icsDomainNames for each external domain that can be searched by users in this domain.

For example, sesta.com searches in both siroe.com and example.com when performing cross domain searches. Use ldapmodify (for either Schema version 1 or Schema version 2) to create the following LDIF:
```
dn: dc=sesta, dc=com, o=internet
changetype: modify
add: icsDomainNames
icsDomainNames:siroe.com
icsDomainNames:example.com
```

Using Delegated Administrator Utility command commadmin domain modify, specify the option -A to add names of domains to be searched.

For example:

commadmin domain modify -D admin 
   -w adminpassword -X hostmachine_1 -d sesta.com 
   -A +icsDomainNames:siroe.com 
   -A +icsDomainNames:example.com

Using Delegated Administrator Console, when creating or editing an organization's properties, you can add domains to the Invite Calendars in These Organizations list.

This adds icsDomainNames attributes to the domain LDAP entry. Add one attribute for each external domain to be searched when users in this domain send invitations to an event.

For more information, see the Delegated Administrator Console online help.

Chapter 14 Administering Users, Groups, and Resources

This chapter describes how to use Delegated Administrator and the Calendar Server utilities to manage users, groups, and resources.

This chapter contains the following sections:

14.1 Creating Calendar User LDAP Entries

This section contains instructions for creating new user entries.

This section contains the following topics:

14.1.1 To Create New Calendar Users in Schema Version 2 Mode

This section describes how to create new calendar users for Schema version 2 LDAP entries.

You can use either the Delegated Administrator Console or Utility:

Delegated Administrator Console

In the Delegated Administrator Console, use the Create New User wizard. (Click New in the User List page for the organization where the user is to reside.) For more information, see the Delegated Administrator Console online help.
Delegated Administrator Utility

Use the commadmin utility user create command. For example, to add user jdoe in the sesta.com domain:
```
commadmin user create -D calmaster -F John -n sesta.com 
   -k hosted -l jdoe -w calmasterpassword -W jdoepassword -L Doe -S cal
   -B red.sesta.com -E jdoe@sesta.com
```
For details on all the available options for the commadmin utility, refer to the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide

14.1.2 To Create New Calendar Users For Schema Version 1 Mode

Use the csuser utility. For example, to add user jdoe in the sesta.com domain:

csuser -m jdoe@sesta.com -d sesta.com create jdoe

14.2 Creating Calendar Group LDAP Entries

This section describes how to create new group LDAP entries

This section contains the following instructions:

14.2.1 To Create New Calendar Groups for Schema Version 2 Mode

Groups are named lists of users, resources, or other groups (nested groups). Groups can be either static or dynamic.

Tip –

Groups do not contain both static and dynamic members. If an empty group is created, the default is a static group.

You can use one of the following tools:

Delegated Administrator Console — From the Groups page, click New. The Create New Group wizard appears. The Calendar Service Details screen follows the Mail Service Details screen. You can also assign a service package to the group on the Calendar Service Details screen.

For more information on the Console, see the Delegated Administrator Console online help.
Delegated Administrator Utility — Use commadmin group create.

For example:
```
commadmin group create -D chris -n sesta.com -w bolton 
-G testgroup -d sesta.com -m lorca@sesta.com -S mail -M achiko@varrius.com
```
For details on all the available options for the commadmin utility, refer to the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide

14.2.2 To Create New Calendar Groups for Schema Version 1 Mode

Add the group LDAP entry directly. Use the Directory Server LDAP commands found in Sun ONE Directory Server Resource Kit 5.2 Tools Reference.

The group LDAP entry should include the icsCalendarGroup object class, which is an extension of the GroupofUniqueNames object class. The following are attributes that can be included:

Attribute	Description
`groupid`	The is the only required attribute for a group. It is the unique identifier for the group, similar to the `uid` for a user.
`icsSecondaryowners`	Co-owners of the group.
`icsDefaultacl`	ACL string for the new group calendar.
`icsCalendar`	The `calid` of the default calendar for this group. It is not required for a group to have a default calendar.
`icsStatus`	The status of the group calendar. Possible values are: `active`, `inactive`, `deleted`.
`icsTimezone`	Time zone for the group.
`icsDWPHost`	The name of the back-end host where the default calendar resides.
`icsDoublebooking`	Whether or not the default calendar allows multiple events to be scheduled in the same time period. This overrides the domain level preference, bit 15 of `icsAllowRights`. See To Configure Calendar Server for Groups for domain level defaults for groups.
`icsAutoaccept`	Whether or not invitations will automatically be accepted for the default calendar.
`mail`	The email address for this group.
`owner`	Distinguished Name for the owner's LDAP entry of the group. Must be single valued.

Note –

The primary owner is specified by the attribute owner from the GroupOfUniqueNames object class.

For example, a group LDAP entry might contain:

dn: groupid=mygroup, ou=group, o=sesta.com
objectclass:groupofuniquenames
objectclass:icsCalendarGroup
groupid:mygroup
owner:uid=jdoe, ou=people, o=sesta.com
icsSecondaryowners:uid=pfox, ou=people, o=sesta.com
icsStatus:active
uniqueMember: uid=wsmith, ou=people, o=sesta.com

For more information about object classes and attributes, see the Sun Java System Communications Services 6 2005Q4 Schema Reference.

14.3 Creating Calendar Resource LDAP Entries

This section describes how to create new resources.

Use one of the following ways to create a calendar resource entry:

14.3.1 To Create New Calendar Resources for Schema Version 2 Mode

This section contains instructions for creating new resource LDAP entries in Schema version 2 mode.

You can use either the Delegated Administrator Console or Utility:

Delegated Administrator Console

In the Delegated Administrator Console, use the Create New Resource wizard. (Click New in the Calendar Resources tab for the organization where the resource is to reside.) For more information, see the Delegated Administrator Console online help.
Delegated Administrator Utility

Use the commadmin utility rescource create command to create an LDAP entry. For example, to add the conference room Conference_Room_100, use the following command:
```
commadmin resource create -D calmaster 
   -w calmasterpassword -n sesta.com -c room100 
   -N Conference_Room_100
```
You must then use csresource to create the actual resource calendar. For information on how to create a resource calendar, see 15.5 Creating Calendars

For details on all the available options for the commadmin utility, refer to the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide

14.3.2 To Create New Calendar Resources for Schema Version 1

Use the csresource utility to create both the LDAP entry and the resource calendar. For example, to add a projector, p101, use the following command:

csresource -m p101@siroe.com -c p101 create Projector_101

For more information on csresource, see the D.15 csresource.

14.4 Adding the mail Attribute to User, Group and Resource LDAP Entries

This section contains conceptual information and instructions for enabling LDAP entries for mail service.

This section covers the following topics:

14.4.1 Overview of Adding Mail Service to Calendar Server LDAP entries

Calendar Server requires users, groups and resources to have the mail attribute, which contains the email address of the user, group or resource. This enables people to search for calendars using either an email address or a calid. When you create new users with Delegated Administrator, it adds the mail attribute automatically. This happens even if the user has not been assigned mail service. However, if your users and resources were created in a version of Calendar Server when the mail attribute was not required, you might have to add the mail attribute to your existing user and resource LDAP entries.

Note –

Adding the mail attribute does not enable email notifications for user calendars.

Calendar Server does not support email notifications for group, or resource calendars.

To enable email notification for user calendars, add the following two attributes to the user’s LDAP entry:

icsExtendedUserPrefs:ceNotifyEnable=1
icsExtendedUserPrefs:ceNotifyEmail=jdoe@sesta.com

14.4.2 To Check if the mail Attribute Exists in the LDAP Entry

If you do not know if your users, groups and resources have the mail attribute, for Schema version 2 environments, use Delegated Administrator to check for mail services.

For Schema version 1 environments, use the csattribute list command with the -v (verbose) option.

For example, to check if the conference room resource Room100 has the mail attribute, you would issue the following command:

csattribute -v list Room100

The output tells if the mail attribute is present:

cn=Room 100,ou=conferenceRooms,dc=sesta,dc=com
 has mail: Room100@sesta.com

If the mailattribute exists, you do not have to add it. If the attribute does not exist, then add it as shown in the section that follows.

14.4.3 To Add the Mail Attribute to Existing User, Group and Resource LDAP Entries for Calendar Server Version 6.3

If you are converting existing LDAP entries to calendar enabled entries, you must add the mail attribute to each user, group and resource LDAP entry that does not contain it.

To add the mail attribute to existing users, groups and resources, use one of the following methods:

Use Delegated Administrator Utility for a Schema version 2 Environment.

Use the commadmin user|resource|group modify -A option.

For example: commadmin group modify -A +mail:jdoe@sesta.com
Use the Calendar Server D.3 csattribute utility for a Schema version 1 environment.

The following example adds the LDAP mail attribute for an existing conference room named Room100 on the sesta.com server:
```
csattribute -a mail=Room100@sesta.com add Room100
```
Use ldapmodify to add the attribute directly to the LDAP entries for either Schema version.

14.5 Administering Existing Users

This section contains conceptual information and instructions for administering user entries in an LDAP database. It does not include creating user entries. For information on creating user entries, see14.1 Creating Calendar User LDAP Entries.

Administer users with either the Delegated Administrator Utility or Console for Schema version 2 LDAP user entries, or the csuser utility for Schema version 1 LDAP user entries.

The administrative tasks covered in this section are the following:

14.5.1 Displaying Calendar User Information

This section shows two command examples using the Calendar Server utilities command, csuser list, to obtain a list of all calendar users, or to display a particular user's calendar attributes (from the LDAP user entry).

This section contains the following topics:

14.5.1.1 To Display All Users Enabled for Calendaring

To display all users enabled for calendaring, issue the following command-line utility:

csuser list

14.5.1.2 To Display a Particular User's Calendar Attributes

To display all of the calendar attributes for a single user, issue the following command-line utility:

csuser -v list fully-qualified-user-name

For example, if the user is jsmith who belongs in the sesta.com domain, the command-line would be the following:

csuser -v list jsmith@sesta.com

14.5.2 Disabling a Calendar User

The purpose of disabling a user is to prevent the user from logging into Calendar Server. This is handled differently depending on which user management tool you used to create the user. Users created in the Delegated Administrator Console should be administered using it also. Likewise, if you assigned calendar service to the user with Delegated Administrator Utility, use it to remove the service. Each handles the situation a bit differently.

This section contains the following topics:

14.5.2.1 To Disable a User with Delegated Administrator Console

In the Delegated Administrator Console, it is not possible to merely temporarily inactivate a user. You must remove calendar services from the user. To do this, select the user from the User List page. In the Properties for this user, delete the service package with calendar service in it. This disables the user for calendar, including setting the user's icsStatus to inactive.

Note –

If the package also contains other services, you will have to reassign those services using another package that does not contain calendar.

14.5.2.2 To Disable a User with Delegated Administrator Utility (`commadmin user delete`)

To prevent a user from accessing calendar services, remove the service from the user’s LDAP entry, as shown in the example that follows:

commadmin user delete jsmith -S cal

This removes calendar service from the user without completely removing the LDAP entry. In addition, this command changes the user's icsStatus to inactive.

14.5.2.3 To Disable a User with Calendar Server Utilities (`csuser disable`)

The disable command prohibits a user from accessing calendar data, but it does not remove calendar service from the user’s LDAP entry or the Calendar Server database. The utility signals the user being disabled by adding icsAllowedServiceAccess="http" to the user LDAP entry.

For example, to disable jsmith from accessing Calendar Server:

csuser disable jsmith

If jsmith is currently logged into Calendar Server, jsmith retains access to calendar data until he logs off.

14.5.2.4 To Remove Calendar Service from a User with Calendar Server Utilities

To remove calendar service from a user, use the csuser utility reset command.

For example, to remove calendar service from jsmith:

csuser reset jsmith

Doing this removes all of the calendar attributes from the user’s LDAP entry, including icsCalendarUser (object class), icsSubscribed, icsCalendarOwned, icsCalendar, and icsDWPHost (if using LDAP CLD). A Calendar Server administrator will not be able to create calendars on the user’s behalf.

Note –

Calendar Service is restored to the user when one of the following happens:

The user logs back into Calendar Server (with autoprovisioning turned on).
The Calendar Server administrator issues a csuser enable command. In this case, the icsDWPHost attribute is not restored with the command. You must add it separately.
The Calendar Server administrator specifically adds the object class and attributes to the user LDAP entry.
You have recently migrated to Schema version 2 and use the Delegated Administrator to add calendar service.

14.5.3 Enabling a Calendar User

This section contains information about how to enable calendar service for a user.

When users are created, they are normally enabled for calendar service. However, it is possible that a user can be disabled. To re-enable the user for calendar services, you must use one of the methods in this section.

Caution –

Enabling a user is implemented slightly differently, between the Delegated Administrator Console and the Utility. Thus, you should use the same tool for both enabling and disabling a user. Do not disable using one tool and re-enable using another.

This section covers the following methods of enabling a user:

14.5.3.1 To Enable a User with Delegated Administrator Console

You can not disable a user from the Console. You can remove calendar service and then re-add them. To re-add the service, select the user from the User List page and use the Assign Service Package wizard to add the calendar service package to the user's LDAP entry. The user is automatically enabled.

Note –

This is the same procedure used to add calendar service (14.5.4 Adding Calendar Service to a User).

14.5.3.2 To Enable a User with Delegated Administrator Utility

Delegated Administrator Utility can enable a user with either one of the following choices:

Enabling the user by changing the icsStatus to active.

commadmin user modify -A icsStatus:active to enable the user.
Adding the calendar service to the user LDAP entry.

commadmin user modify -S cal

Caution –

Be sure to use the same method to enable and disable a user. If you tried to enable a user with Delegated Administrator Console, after having disabled the user with Delegated Administrator Utility (changing the icsStatus only), the system will not be able to add service since the user already has service and the user will still be disabled.

14.5.3.3 To Re-Enable a User with Calendar Server Utilities

To re-enable a user for calendar service, use csuser enable to remove icsAllowedServiceAccess="http" from the user's LDAP record.

14.5.4 Adding Calendar Service to a User

It is not necessary to add calendar service to a user created with the old (Schema version 1) Calendar Server utilities. However, with (Schema version 2) Delegated Administrator, calendar service can be added and removed from a user's LDAP entry.

To add calendar service to an existing user, use one of the following tools:

14.5.4.1 To Add Calendar Service to a User with Delegated Administrator Console (for Schema version 2)
14.5.4.2 To Add Calendar Service to a User with Delegated Administrator (commadmin user create)(for Schema version 2)
14.5.4.3 To Add Calendar Service with Calendar Server Utilities (for Schema version 1).

14.5.4.1 To Add Calendar Service to a User with Delegated Administrator Console

You can add calendar services to both a new user and an existing user:

When a new user is created, using the New User wizard, it assigns the user a service package that includes calendar service. The user is automatically enabled.
For an existing user, select the user from the User List page and use the Assign Service Package wizard to select a service package with calendar service. The user is automatically enabled.

14.5.4.2 To Add Calendar Service to a User with Delegated Administrator (`commadmin user create`)

When creating a new user, add calendar services as illustrated in the example that follows:

commadmin user create jsmith -S cal

If you did not add calendar services when the user was created, you can add calendar services to the user later, using a modify command, as illustrated in the following example:

commadmin user modify jsmith -S cal

14.5.4.3 To Add Calendar Service with Calendar Server Utilities

If you used csuser create when you created the user entry, the utility gives calendar service to the user by adding icsCalendarUser and its attributes to the user LDAP entry.

14.5.5 Deleting Calendar Service from a User LDAP Entry

One way to deny calendar service to a user is to remove the service from the user entry. Another way is to disable the user temporarily. These are covered in the earlier section titled 14.5.2 Disabling a Calendar User.

14.5.6 Setting Up Email Aliases for a Calendar User

If you need to setup email aliases for a calendar user, add the mailalternateaddress attribute to the user's LDAP entry. The mail attribute provides the primary mail address, and the mailalternateaddress attribute is used for email aliases. Both attributes map the mail addresses to the user’s calendar ID (calid).

You can add the attribute in the following three ways:

, using commadmin user modify -A or by directly updating LDAP with ldapmodify.

Note –

To enable these changes, you might also need to rebuild alias tables or configurations. Refer to the documentation for Messaging Server (or your email product) as well as your site's own documentation and procedures regarding changes to mail services. Messaging Server documentation is available on this at: http://docs.sun.com/coll/1312.2.

To Set Up Email Aliases with Delegated Administrator Console

Choose the organization where the user resides.

Search for the user.

Display the user's properties by clicking the user's name.

Edit the Mail Services Details to add aliases.

14.5.6.1 To Set Up Email Aliases with Delegated Administrator Utility

Email aliases can be set up for calendar users, just like messaging users, by adding mailalternateaddress to the user's LDAP entry. To add the attribute using Delegated Administration Utility, use commadmin user modify -A mailalternateaddress:value.

14.5.6.2 To Set Up Email Aliases with Calendar Server Utility csattribute

To add email aliases to a user, use the csattribute add -a command to add mailalternateaddress attributes to the user entry.

For example, to add two aliases for a user named John Smith with these values:

With a mail attribute of: johnsmith@sesta.com
Email aliases: johns@sesta.com and jsmith@sesta.com

The commands would look like the following examples:

csattribute -a mailalternateaddress=johns@sesta.com add johnsmith@sesta.com

csattribute -a mailalternateaddress=jsmith@sesta.com add johnsmith@sesta.com

14.5.7 Verifying that a User has Calendar Service

This section provides instructions for verifying calendar service.

Use the following tools to verify that a user has calendar service.

14.5.7.1 To Check if a User has Calendar Service with Delegated Administrator Console

If there is a Calendar Service Details page, then they have calendar services. Or, look in the service package details to see what kinds of services are listed.

14.5.7.2 To Check if a User has Calendar Service with Delegated Administrator Utility

Use the following command to list all the directory properties associated with the user:

commadmin user search

14.5.7.3 To Check if a User has Calendar Service with Calendar Server Utility `csuser`

Use the following command to check if the user is enabled for calendar service:

csuser check

14.5.8 Deleting Users from the LDAP Database

Use either Delegated Administrator or the Calendar Server Utilities to delete a user from LDAP.

Use one of the two methods that follow to delete users from the LDAP database:

Caution –

There is no undelete command.

Once users in a domain are deleted using Delegated Administrator, they must be purged and re-added from scratch. User names can not be reused until the purge happens.

Deleting Users in Schema Version 2 Using Delegated Administrator

You can mark users for deletion with either Delegated Administrator interface. However you can not actually remove users from LDAP (purge) using the Delegated Administrator Console. You must use the Delegated Administrator Utility for that. The following task lists the steps for deleting a user from LDAP. The user is not actually removed from LDAP until the last step is complete.

Mark a user entry for deletion.

For Delegated Administrator Console: Select the users to delete in the User List page and click Delete.

For Delegated Administrator Utility: Use the commadmin user delete command. For example:
```
commadmin user delete -D chris -n siroe.com 
-w bolton -l jsmith
```
In both cases the icsStatus attribute in the user LDAP entry is changed from active to deleted.

Use the Calendar Server Utility csclean to remove all calendars belonging to all deleted users in one or all domains, as shown in the following example:

csclean clean “*”

Or to remove calendars belonging to all deleted users in one domain, specify the actual domain, as shown in the following example: csclean clean sesta.com

Tip –
If you inadvertently purge the users from LDAP before deleting the users' calendars, you can remove them later using the cscal utility, as described in 15.6 Managing User Calendars.

Purge the domain of all users marked for deletion, using Delegated Administrator Utility command commadmin domain purge.

For example:

commadmin domain purge -D chris -d sesta.com -n siroe.com -w bolton

In this example, all users in sesta.com that are marked as deleted will be purged, that is, permanently removed.

Tip –
Run this utility manually from time to time to clean up your LDAP directory. For more information about this command, see the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.

14.5.8.1 Deleting Users in a Schema Version 1 Environment

To remove the specified user’s LDAP entry and the user’s default calendar, use the Calendar Server utility csuser with the delete command.

For example, to delete the LDAP entry and the default calendar for user jsmith use the following command:

csuser delete jsmith

If you wish to remove the other calendars belonging to this user, you must use cscal as described in 15.6 Managing User Calendars.

14.5.9 Renaming Calendar Users

If one or more user ID's need to be changed, run the csrename utility.

This utility performs the following steps:

Converts the user ID's in the Calendar Server LDAP attributes (the ones with the ics prefix). The LDAP directory is updated in place.
Renames the users in events and tasks on the Calendar Server database files. It writes the new database to a destination directory. Existing database files are not modified.

Note –

Be aware that changing even one user ID causes the whole database to be rewritten. So this is a “costly” utility to run.

For further information on the csrename utility, see Appendix D, Calendar Server Command-Line Utilities Reference.

14.5.10 Turning the Publicly Writable Calendars Feature Off

Publicly Writable Calendars is a Calendar Server feature. You can turn this feature on or off. It is enabled by default. The following task shows how to edit the configuration file to change the setting.

With this feature enabled, calendars can be scheduled (written to) when an invitation is generated. The event will automatically be added to the attendees' calendars.

With this feature disabled, calendar owners will get an email notification only when an invitation is generated. The event will not be automatically added to the attendees' calendars. Only the owners are allowed to add events and tasks to the calendar.

To Disable Users from Having Publicly Writable Calendars

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit the following ics.conf parameter as shown in the following table:

Parameter	Description and Default Value
`service.wcap.` `allowpublicwritablecalendars`	Enables users to have publicly writable calendars. This is enabled by default (set to `“yes”`).

Parameter

Description and Default Value

service.wcap.

allowpublicwritablecalendars

Enables users to have publicly writable calendars. This is enabled by default (set to “yes”).

Save the file as ics.conf.

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

14.6 Administering Calendar Server Resources

This section contains conceptual information and instructions on administering calendar resources.

After your resources are added, you can administer them using Delegated Administrator or csresource.

This section contains the following topics:

14.6.1 Retrieving LDAP Information for Resources

This section contains instructions for retrieving resource LDAP information.

You can retrieve resource properties from the LDAP resource entry with one of three tools:

To Retrieve Resource Information Using Delegated Administrator Console

In the Delegated Administrator Console, click the Calendar Resources tab.

Use the Search Results drop-down box to select one of the following options:
- Search Calendar Resource by Resource ID
- Search Calendar Resource by Calendar Resource Name

Type the value you want to search for.

Click Search.

14.6.1.1 To Retrieve Resource Information Using Delegated Administrator Utility

Use the commadmin resource search command to retrieve LDAP information for a resource.

For example, to search for the resource CF101 in the sesta.com domain, use the following command:

commadmin resource search -D serviceadmin -w serviceadmin -n sesta.com \s
-d sesta.com -u CF101

To Retrieve Resource Information Using `csresource`

You can retrieve the LDAP entry information for a resource or for all resources using the csresource utility.

Change to the sbin directory.

Use the csresource list command to list one or all resources.

For example, list all the information about all the resources:

./csresource -v list

Or, list all the information about a specific resource, CF101:

./csresource

To Enable Resources

Change to the sbin directory.

Use the csresource enable command to enable one or more resources.

For example, to enable the ConfRm12 resource:

./csresource -v enable ConfRm12

To Disable Resources

Change to the sbin directory.

Use the csresource disable command to disable one or more resources. For example, to disable the ConfRm12 resource:

./csresource -v disable ConfRm12

To Delete Resources

Change to the sbin directory.

Use the csresource delete command to delete one or more resources. For example, to delete the ConfRm12 resource:

./csresource -v delete ConfRm12

14.6.2 To Set Up a Bitbucket Channel for Resource Email

This section contains directions for setting up a bitbucket channel for both Messaging Server and Sendmail. The bitbucket channel is a way to discard the email generated for resource calendars. These examples use a resource named Room100 on the sesta.com server. If you don’t set up the bitbucket channel (or equivalent), you will need to periodically delete the email messages sent to the resource calendar.

This section contains the following procedures:

To Set up the Messaging Server Bitbucket Channel

Ensure the bitbucket channel is defined in the imta.cnf file.

To direct messages to the bitbucket channel, create the email address for the resource using the csattribute utility:
csattribute -a mail=Room100@bitbucket.sesta.com add Room100

To Set up a Sendmail Bitbucket Channel

In the /etc/aliases file on the appropriate host, add an entry such as:

Resource/Conference room aliases Room100: /dev/null

Add the email address for the resource to the LDAP directory using the csattribute utility:

csattribute -a mail=Room100@sesta.com add Room100

14.7 Managing User and Resource LDAP Attributes

Manage LDAP attributes used by Calendar Server, with the D.3 csattribute utility, or ldapmodify. Attributes can be listed, added, or deleted with csattribute. To modify an attribute, use ldapmodify.

This section contains the following topics:

To List LDAP Entry Attributes

Log in as the user or group under which Calendar Server is running (such as icsuser and icsgroup) that was specified during installation, or as root

Change to the sbin directory.

Use the csattribute list command to list the attributes for a user or a resource. For example, to list the attributes for tchang@sesta.com, issue the following command:

./csattribute -t user -d sesta.com list tchang

To Add an LDAP Entry Attribute

Log in as the user or group under which Calendar Server is running (such as icsuser and icsgroup) that was specified during installation, or as root

If you want this attribute change to be recognized immediately, stop Calendar Server. Otherwise, you do not have to stop Calendar Server.

Change to the sbin directory.

Use the csattribute add command to add an attribute to a user or a resource. For example, to add the LDAP attribute icsCalendar with the value Conference_Schedule to the user tchang:

./csattribute -a icsCalendar=Conference_Schedule add tchang@sesta.com

To Delete an LDAP Entry Attribute

Log in as the user or group under which Calendar Server is running (such as icsuser and icsgroup) that was specified during installation, or as root

If you want this attribute change to be recognized immediately, stop Calendar Server. Otherwise, you do not have to stop Calendar Server.

Change to the sbin directory.

Use the csattribute delete command to delete an attribute from a user or a resource. For example, to delete the LDAP attribute icsCalendar with the value Conference_Schedule from the user tchang:

./csattribute -a icsCalendar=Conference_Schedule -t user -d sesta.com delete tchang

14.7.1 To Modify an LDAP Entry Attribute

To modify an LDAP entry attribute, use ldapmodify. For example, to change the status of user with uid=tchang, use ldapmodify as shown:

dn:uid=tchang,ou=people,o=sesta.com
 changetype: modify
 add: objectclass
 objectClass: icsCalendarUser
 add: icsStatus
 icsStatus: active

Note –

If your site is using the LDAP CLD plug-in, do not attempt to move a user’s calendars from one back-end host to another by changing the value of icsDWPHost, using csattribute. Modifying icsDWPHost does not cause the calendar to be moved to the new back-end host. For instruction on how to move a calendar from one back-end server to another, see 15.6 Managing User Calendars.

Chapter 15 Administering Calendars

This chapter contains topics with instructions on how to use Calendar Server command-line utilities to create and manage calendars.

This chapter contains the following topics:

15.1 Calendar Administration Overview for Calendar Server Version 6.3

The Delegated Administrator does not create or manage calendars. You must use the Calendar Server utilities described in Appendix D, Calendar Server Command-Line Utilities Reference.

Before creating calendars, you must know the following information:

There are three types of calendars, user calendars, resource calendars and group calendars.

User calendars are for scheduling human activity. Resource calendars are for scheduling the use of inanimate objects, such as conference rooms, or video equipment. Group calendars are for scheduling activities for a group of users.
All types of calendars are identified by a unique calendar identifier (calid).
Create user calendars with cscal. (Alternately, you can allow autoprovisioning at login time. See 15.3 Automatic Creation of Calendars.
Create resource calendars with csresource. (There is no autoprovisioning of resource calendars.)
Create group calendars

To run cscal or csresource, you must log in as a user who has administrative rights to the system where Calendar Server is running. You must run these commands from the /opt/SUNWics5/cal/sbin directory. That is, you must change to the sbin directory; you can not run them from another directory by specifying the path.

15.2 Creating Calendar Unique Identifiers (calid's)

Each calendar in the Calendar Server database is identified by a unique calendar identifier (ID) or calid. When creating calendars, you are required to specify the calid.

This section contains the following topics:

15.2.1 Calid Syntax

Each calendar in the database is identified by a unique calendar ID (calid). The following calid syntax has three parts:

userid[@domain][:calendar-name]

The three parts are:

userid

A user ID that is unique for the domain in this Calendar Server instance.

domain

The name of the user’s domain.

With a single domain, the domain part is optional since there is no ambiguity about which domain the user is in.

With multiple domains, if the domain part is not specified, then Calendar Server uses the value specified in the ics.conf parameter service.defaultdomain for the domain. If the user is not in the default domain, the domain part must be specified.

For more information about multiple domain environments, see Chapter 10, Setting Up a Multiple Domain Calendar Server 6.3 Environment and Chapter 13, Administering Calendar Server Domains.

calendar-name

An optional calendar name that is unique to the specific user. Although an owner has only one default calendar, it is possible to have other calendars for various purposes. Each of these non-default calendars is distinguished by its calendar name. For example, if user John Doe has a uid jdoe, his default calendar might be jdoe@sesta.com. An auxiliary calendar he uses to keep track of baseball games for the Little League team he coaches might be identified with the following calid: jdoe@sesta.com:baseball.

15.2.2 Calendar ID Creation Rules

This section describes the rules for creating a calendar ID (calid).

When creating a calid, keep in mind the following rules:

Calendar ID's are case sensitive. For example, JSMITH is not equivalent to jsmith. (This differs from email addresses, which are not case sensitive. For example, jsmith@sesta.com is equivalent to JSMITH@SESTA.COM.)
A calendar ID cannot contain spaces and is limited to the following characters:
- Alphabetic (a-z, A-Z) and numeric (0-9) characters (non-ASCII characters are not allowed)
- Special characters: period (.), underscore (_), hyphen or dash (-), at sign (@), apostrophe ('), percent sign (%), slash (/), or exclamation point (!)
  
  Because the user ID is part of the calid, the user ID should not contain spaces (for example, j smith). While a user with a user ID that contains a space can log into Calendar Server, the space can cause subsequent problems.
  
  Examples of proper calendar ID's are:
```
jsmithjsmith:private_calendar
jsmith@calendar.sesta.com:new-cal
```

15.2.3 Converting Non-Domain calid's to Multiple Domain Format calid's

If you have calid's that were created before you had domains, and you now want to convert them to domain specific calid's, there is a utility, csvdmig, that can be used to add the domain part to your existing calid's. See 3.6 csvdmig for instructions on how to use the utility.

If you do not add domain names to the existing calid's, the system will assume they belong to the default domain.

15.3 Automatic Creation of Calendars

This section contains conceptual information and instructions for using the Calendar Server feature for automatically creating calendars upon a user's first login.

Automatic calendar creation is enabled by default. With it enabled, the system automatically creates calendars under two circumstances:

The first time a user logs in, the user's LDAP entry in updated to add calendar service, and a default calendar is created. The user entry must already exist in the LDAP directory. If it does not, an error is returned.
If appropriately configured, the first time a user, group, or resource is invited to an event and there is no existing default calendar, a default calendar is created.

For the configuration information necessary to implement automatic creation of calendars in this circumstance, see To Configure Calendar Server for Groups.

This section covers the following topics:

15.3.1 Creating calids

Calendar Server creates the calendar ID (calid) for new default calendars from the user ID and the domain name.

For example, John Smith's user ID is jsmith, and his LDAP entry resides in the sesta.com domain. The first time he logs into Calendar Server, the system automatically creates a default calendar with jsmith@sesta.com as the calid. Each subsequent calendar John Smith creates has a calid with jsmith@sesta.com: prepended to the calendar name. For example, if John Smith later creates a new calendar named meetings, the calid for the new calendar is jsmith@sesta.com:meetings.

If a user, group, or resource without a default calendar is listed in the attendee list of an event, the system looks up the uid in LDAP in the event owner's domain as the event owner. If no domain is assigned to the owner, the default domain is assumed. The system constructs a calid by appending the domain to the uid.

If the system can't find the uid in the event owner's domain, it will search any other domains the event owner is allowed to search. For more information, see 11.2 Cross Domain Searching in Calendar Server 6.3 Systems.

To Enable Autoprovisioning of Calendars

The auto-creaton of calendars is enabled by default. However, if you need to turn it on again after disabling it, perform the steps that follow:

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit one or more of the following parameters in the Calendar Server configuration file, ics.conf, as shown in the following table:

Parameters	Description and Default Value
`local.autoprovision`	Set to “yes”, allows default calendar creation to occur automatically when the user logs in the first time. autoprovisioning is enabled by default. To turn this feature off, set the value to “no”.

Parameters

Description and Default Value

local.autoprovision

Set to “yes”, allows default calendar creation to occur automatically when the user logs in the first time. autoprovisioning is enabled by default.

To turn this feature off, set the value to “no”.

Verify that the user’s LDAP entry is enabled for calendar.

The entry must contain the icsCalendarUser object class. Add the class to the user’s LDAP entry if it is not there.

If your site is using multiple domains, the user’s domain must also be calendar enabled before autoprovisioning will work. The domain entry must contain the icsCalendarDomain object class.

Save the file.

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

To Disable Autoprovisioning of Calendars

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit one or more of the following parameters in the Calendar Server configuration file, ics.conf, as shown in the following table:

Parameters	Description and Default Value
`local.autoprovision`	Setting the parameter to `no` disables autoprovisioning of user calendars.

Save the file.

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

Note –
If autoprovisioning is disabled, calendars must be explicitly created for users before they can successfully log in.

15.4 Calendar Access Control

Calendar Server uses Access Control Lists (ACLs) to determine the access control for calendars, calendar properties, and calendar components such as events and todos (tasks).

This section covers the following topics:

15.4.1 Configuration Parameters for Access Control

The following table describes the configuration parameters in the ics.conf file that Calendar Server uses for access control.

Table 15–1 Access Control Configuration Parameters


Parameter	Description
`calstore.calendar.default.acl`	Specifies the default access control settings used when a user creates a calendar. The default is: `"@@o^a^r^g;@@o^c^wdeic^g;` `@^a^fs^g;@^c^^g;@^p^r^g"`
`calstore.calendar.owner.acl`	Specifies the default access control settings for owners of a calendar. The default is: `"@@o^a^rsf^g;@@o^c^wdeic^g"`
`resource.default.acl`	Specifies the default access control settings used when a resource calendar is created. The default is: `"@@o^a^r^g;@@o^c^wdeic^g;` `@^a^rsf^g"`

15.4.2 Public and Private Events and Tasks Filter

When creating a new event or task, a user can specify whether the event or task is Public, Private, or Time and Date Only (confidential):

Public: Anyone with read permission to the user’s calendar can view the event or task.
Private: Only owners of the calendar can view the event or task.
Time and Date Only: These are confidential events and tasks. Owners of the calendar can view the event or task. Other users with read permission to the calendar can see only “Untitled Event” on the calendar, and the title is not an active link.

The calstore.filterprivateevents determines whether Calendar Server filters (recognizes) Private, and Time and Date Only (confidential) events and tasks. By default this parameter is set to "yes". If you set calstore.filterprivateevents to "no", Calendar Server treats Private and Time and Date Only events and tasks as if they are Public.

15.4.3 Command-Line Utilities for Access Control

The following table describes the Calendar Server command-line utilities that allow you to set or modify ACLs for access control.

Table 15–2 Command-Line Utilities for Access Control


Utility	Description
`cscal`	Use the `create` and `modify` commands with the `-a` option to set ACLs for specific user or resource calendars.
`csresource`	Use the `csresource` utility with the `-a` option to set ACLs for resource calendars.
`commadmin user` `csuser`	For Schema version 2, use Delegated Administrator Console, or Delegated Administrator Utility, `commadmin`, to change the default ACL used when a user calendar is created. For Schema version 1, use the `csuser` utility with the `-a` option to change the default ACL used when a user creates a calendar.

Note –

To set access rights in the Delegated Administrator Console, from the Organization Properties page (also from the Create New Organization wizard), click the Advanced Rights button to see the list of access rights that can be administered from the console.

15.5 Creating Calendars

This section contains conceptual information and instructions on how to create calendars.

This section contains the following topics:

15.5.1 Creating a User Calendar with the `cscal`Utility

This section contains the following topics and examples:

The following example creates a calendar similar to the previous example, but it also sets specific access control settings for group scheduling:

cscal -n Hobbies -o jsmith -a "@@o^a^sfr^g" create Personal

The string -a "@@o^a^sfr^g" grants other owners schedule, free/busy, and read access privileges to both the components and calendar properties of this calendar for group scheduling.

15.5.1.1 Overview of Creating a New Calendar

To create a new calendar, use the cscal utility with the create command. The user or resource entry must already exist in the LDAP directory. Refer to Chapter 14, Administering Users, Groups, and Resourcesfor information on adding users and resources to your LDAP directory.

If your site is using the LDAP Calendar Lookup Database (CLD) plug-in, you must create all of the calendars for a particular user or resource on the same back-end server, as indicated by the icsDWPHost LDAP attribute in the user or resource entry. If you try to create a calendar on a different back-end server, the cscal utility returns an error. For information about the LDAP CLD plug-in, see Chapter 5, Configuring Calendar Database Distribution Across Multiple Machines in Calendar Server Version 6.3.

15.5.1.2 Creating New Calendars

To create a new calendar, the minimal command is the following:

cscal -o uid  create calid

For example, for the user John Smith with a unique ID and calendar ID of jsmith the command would look like the following:

cscal -o jsmith create jsmith

The command has the following parts:

cscal: The name of the utility.
-o: The unique ID (uid) of the primary owner for this calendar.
create: The command to create the new calendar.
calid: The calendar ID to be assigned to this calendar.

For more information about the cscal utility, see D.5 cscal also located in this guide.

Tip –

The default access control settings are defined by calstore.calendar.default.acl in the ics.conf file.

15.5.1.3 Creating Another Calendar for a User

You can create multiple calendars for any user. However, they are always identified as sub-calendars of the default calendar. The fully qualified name of the new calendar will have the default calendar name on the left of a colon separator and the new calendar's name on the right of the colon separator.

The following example demonstrates how to create another (non-default) calendar for a user, John Smith, with the name of the new calendar as Personal:

cscal -o jsmith@sesta.com create Personal

The parts of the command are as follows:

cscal

The name of the utility.

-o jsmith@sesta.com

The unique ID (uid) of the primary owner for this calendar.

create

The command to create the new calendar.

Personal

The second half of the calendar ID (calid) to be assigned to this calendar.

The fully qualified calendar ID is jsmith@sesta.com:Personal.

15.5.1.4 Creating a Calendar with a Viewable Name

This example shows how to give a separate viewable name, “Hobbies”, to the Personal non-default calendar created in the previous example.

cscal -o jsmith@sesta.com -n Hobbies create Personal

-o

jsmith@sesta.com Specifies the user ID of the primary owner.

-n

Hobbies Specifies the viewable name of the calendar.

Personal

The name of this new additional calendar for John Smith.

The entire calid becomes: jsmith@sesta.com:Personal.

15.5.1.5 Creating a Calendar with Other Properties

The following example creates a new calendar, Personal, similar to the previous example, but it also associates the calendar with the category named sports, enables double booking, and specifies Ron Jones as another owner:

cscal -n Hobbies -o jsmith -g sports -k yes -y rjones create Personal

The command has the following parts:

cscal

The name of the utility.

-o jamsith@sesta.com

The unique ID (uid) of the primary owner for this calendar.

-g sports

This option associates the calendar, Personal, with a category named sports.

-y

The value rjones@sestas.com specifies another owner of the calendar.

-k yes|no

This option enables or disables double booking of events in one time slot.

A value of yes enables double booking. A value of no would disable double booking.

create

The command to create the new calendar.

Personal

The calendar ID to be assigned to this calendar.

15.5.2 Configuring the Calendar Server for Resources

A resource calendar is associated with things that can be scheduled, such as meeting rooms, notebook computers, overhead projectors and other equipment. Resource calendars require access control lists.

As shown in table Table 15–3, two configuration parameters in the ics.conf file apply to resource calendars:

resource.default.acl: A default access control list.
resource.allow.doublebook: A parameter that allows or disallows doublebooking.

To change the default values for these parameters (shown in table Table 15–3), edit the ics.conf file. Changes to the default values will apply only to new resource calendars; it will not change the values for existing resources.

For Schema version 1, use the Calendar Server Utility cscal to change values for an existing resource calendar. The csresource utility does not have a modify command.

For Schema version 2, use the Delegated Administrator Utility command commadmin resource modify. The Delegated Administrator Console does not allow you to change these values for calendar resources.

Note –

The Calendar Server notification software is not programmed to send notifications to resources, only to users.

Table 15–3 Resource Calendar Configuration Parameters in the ics.conf file


Parameter	Description and Default Value
`resource.default.acl`	This parameter determines the default access control permissions used when a resource calendar is created. The default permissions are specified by the following Access Control List (ACL): `"@@o^a^r^g;@@o^c^wdeic^g;@^a^rsf^g"` This ACL grants all calendar users read, schedule, and free/busy access to the calendar, including both components and properties. To change the permissions for a resource, use the`-a` option when you create the calendar using the `csresource` utility create command.
`resource.allow.doublebook`	This parameter determines if a resource calendar allows doublebooking. Doublebooking allows a resource calendar to have more than one event scheduled for the same time. The default value is `"no"`— Do not allow doublebooking. To allow doublebooking for a resource calendar, use the `-k` option when you create the calendar using the `csresource` utility create command.
`resource.invite.autoprovision`	The default value is `"yes".`
`resource.invite.autoaccept`	The default value is `"yes"`.

15.5.3 Creating Resources and Resource Calendars

Tip –

If the value of the ics.conf parameter resource.invite.autoprovision is "yes", the resource calendar will be created upon first invitation. That is, if this resource does not already have a default calendar, the first time its scheduled in an invitation, a resource calendar will be created.

To create a resource, use one of the following methods:

Calendar Server Utility (Schema version 1)

Use csresource create

This utility creates both the LDAP entry and the default calendar for the resource.

If there is an existing LDAP entry for the resource, csresource creates only the calendar. It will not create a duplicate LDAP entry.

For example, to create a resource LDAP entry and calendar with the calendar ID aud100, viewable name Auditoriumwith the default settings, use the following command:

csresource -m aud100@siroe.com -c aud100 create Auditorium

Delegated Administrator Utility and Calendar Server utility

Use a combination of two commands:

The Delegated Administrator Utility command commadmin resource create to create the LDAP entry.
The Calendar Server Utility command csresource create to create the default calendar.

Delegated Administrator Console

To create the LDAP resource with the Console, select the organization where this resource will reside from the Organizations List. From the Calendar Resources page for this organization, click New to bring up the Create New Calendar Resource Wizard.

For more information about the Delegated Administrator Utility, see Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.

For more information about the Delegated Administrator Console, see the online help.

For more information about csresource, see Appendix D, Calendar Server Command-Line Utilities Reference.

15.5.4 Allowing Double Booking of Resource Calendars

By default, Calendar Server does not allow double booking for a resource calendar (resource.allow.doublebook parameter). This default prevents scheduling conflicts for resources such as rooms and equipment. However, if you want to allow double booking for a resource calendar, set the csresource -k option to “yes” when you create the calendar.

The following command creates a resource LDAP entry and calendar, but the -k option allows double booking on the calendar, the -o option specifies bkamdar as the owner of the calendar, and the -y option specifies jsmith@sesta.com as another owner:

csresource -m aud100@siroe.com -c aud100 -k yes
    -o bkamdar -y jsmith@sesta.com create Auditorium

15.5.5 Limiting Access to Resource Calendars

To control who can schedule a specific resource, consider limiting the users who have write access to the resource calendar. For example, you might want to allow only certain users to schedule meeting rooms or reserve equipment.

If you do not specify an owner for a resource calendar, the value is taken from the service.siteadmin.userid parameter in the ics.conf file.

15.6 Managing User Calendars

This section contains instructions on how to manage user calendars using the Calendar Server utility D.5 cscal.

This section covers the following administrative tasks:

15.6.1 To Display Calendars

To display all calendars, all calendars owned by a user, or the properties of a specific calendar, use the cscal utility list command.

The following examples demonstrate three different tasks using cscal.

To list all calendars in the calendar database:

cscal list
To list all calendars owned by jsmith:

cscal -o jsmith list
To list all the properties of a calendar with the calendar ID jsmith:meetings:

cscal -v list jsmith:meetings

15.6.2 To Delete a Calendar

To delete one or more calendars from Calendar Server, use the cscal utility delete command. This utility deletes the calendar, but it does not delete the user from the directory server.

The following two examples demonstrate different tasks you can accomplish with cscal delete:

To delete a specific calendar with the calendar ID jsmith@sesta.com:meetings:

cscal delete jsmith@sesta.com:meetings
To delete all calendars whose primary owner is jsmith@sesta.com:

cscal -o jsmith@sesta.com delete

Caution –

The delete command removes all of the calendar information from the calendar database and cannot be undone. After you delete a calendar, you can recover the calendar data only if it was backed up. For more information, see Chapter 17, Backing Up and Restoring Calendar Server Data.

15.6.3 To Remove Calendars of Deleted Users

If you have deleted one or more users with the Calendar Server Utility command csuser delete, or with Delegated Administrator Console or Utility, calendars owned by that user might still be present in the database.

There are two ways to remove users’ calendars. The method to use depends on the tool you used to delete the user:

Calendar Server utility csuser

The csuser utility removes the user from the LDAP directory and removes the user’s default calendar, but not any other calendars the user might own. For instructions on how to use cscal to remove these calendars, see To Remove All Calendars of a User Deleted with csuser in Calendar Server Version 6.3.

Delegated Administrator Console and Utility

Delegated Administrator does not remove any calendars. Use Delegated Administrator to mark users for deletion and then use Calendar Server Utility csclean to remove calendars for user's marked for deletion.

For instructions on how to remove deleted users’ calendars using csclean, see To Remove All Calendars for Users Deleted by Delegated Administrator.

For instructions on using Delegated Administrator Utility, see the Sun Java System Communications Services 6 2005Q4 Delegated Administrator Guide.

For instructions on using Delegated Administrator Console, see the online help.

To Remove All Calendars of a User Deleted with csuser in Calendar Server Version 6.3

Run the cscal list command to find all of the calendars for the deleted owner’s uid.

cscal -o owner list

Use the cscal command to remove all the calendars for this owner.

cscal -o owner delete

Verify that all the calendars have been removed by running csuser list again.

Note –
Use this procedure if you used commadmin to mark the user as deleted, and the user’s LDAP entry has already been purged.

To Remove All Calendars for Users Deleted by Delegated Administrator

Delegated Administrator does not remove calendars. Use the csclean utility to remove all calendars for any users marked as deleted with Delegated Administrator.

Use csclean to remove all calendars for users marked as deleted but not yet purged.

For example, to remove all the calendars for users marked as deleted in the sesta.com domain in the last 10 days, the command would be as follows:

csclean -g 10 clean sesta.com

If the user has already been purged from the LDAP, then you must use cscal.

For instructions, see To Remove All Calendars of a User Deleted with csuser in Calendar Server Version 6.3.

15.6.4 To Enable a Calendar

To allow users to access their calendars, you must first enable the calendars using the cscal enable command.

The following examples, demonstrate how to enable calendars:

To enable calendar jsmith@sesta.com:meetings using the default configuration settings:

cscal enable jsmith@sesta.com:meetings
To enable the calendar jsmith@sesta.com:meetings but not allow doublebooking:

cscal -k no enable jsmith@sesta.com:meetings

15.6.5 To Disable a Calendar

To prevent users from accessing a calendar, use the cscal utility disable command. The disable command prohibits users from accessing the calendar, but it does not remove the information from the calendar database.

For example, to prevent users from accessing jsmith@sesta.com:meetings, use the following command:

cscal disable jsmith@sesta.com:meetings

15.6.6 To Modify Calendar Properties

To modify the properties of a calendar, use the cscal utility modify command.

For example, to change the group scheduling access control settings of AllAdmins and specify RJones@sesta.com as another owner:

cscal -a "@@o^c^wd^g" -y RJones@sesta.com modify AllAdmins

The following explains the two command variables used in the preceding example:

-a "@@o^c^wd^g" grants owners write and delete access to the components (events and tasks) of AllAdmins.
-y RJones@sesta.com specifies the user ID of the other owner.

15.6.7 To Remove Properties From a Calendar

To remove a property value from a calendar, use the cscal modify command and specify the value of the option with two double quotes ("").

The three examples that follow show how to remove different properties:

To remove a description from jsmith@sesta.com:meetings:

cscal -d "" modify jsmith@sesta.com:meetings
To remove all categories from the jsmith@sesta.com:meetings calendar:

cscal -g "" modify jsmith@sesta.com:meetings
To remove “other owners” from jsmith@sesta.com:meetings:

cscal -y "" modify jsmith@sesta.com:meetings

15.6.8 To Recover a “Lost” Default Calendar

If a user’s default calendar is not visible to the Communications Express user interface client, but still exists in the database, you can recover the calendar and make it visible again by updating two attributes in the user’s LDAP entry.

To recover a calendar, make sure the value of the following attributes in the user's LDAP entry is the user's fully qualified calid:

icsCalendar
icsSubscribed

For Schema version 2, use one of the following methods to update the attributes:

Use the ldapmodify Directory Server utility.
Use the Calendar Server Utility command csuser reset.
Use the Delegated Administrator Utility command commadmin user modify.
Use the Delegated Administrator Console to add the default calendar name by editing the User Properties page.

For Schema version 1, use the csattribute add command to update the attributes.

To Move a User Calendar to a Different Back-End Server

To move a user calendar from one back-end server to another back-end server, follow these steps:

On the original server, disable the calendar user using the D.19 csuser utility. For example to disable the user with the user ID and calid bkamdar:

csuser disable bkamdar

On the original server, export each of the user’s calendars from the calendar database to a file using the D.10 csexport utility. For example:

csexport -c bkamdar calendar bkamdar.ics

Copy the exported calendar (*.ics) files from the original server to the new server.

On the new server, for each of the calendars exported, import the calendar from the file to the calendar database using the D.11 csimport utility. For example:

csimport -c bkamdar calendar bkamdar.ics

On the LDAP directory server, update the calendar owner’s icsDWPHost LDAP attribute to point to the new back-end server using the D.3 csattribute utility. To update an attribute, you must first delete the attribute and then add it with the new value. For example, to set the new server name to sesta.com:
csattribute -a icsDWPHost delete bkamdar csattribute -a icsDWPHost=sesta.com add bkamdar

On the new server, enable the calendar user using the D.19 csuser utility for a user calendar. For example:

csuser enable bkamdar

On the new server, use the following commands to verify that the attributes are correct and that each calendar has been moved correctly. For example:
cscal -v -o bkamdar list bkamdar ... csattribute -v list bkamdar

On the original server, delete each calendar you just moved. For example:

cscal -o bkamdar delete bkamdar

The -o option deletes all calendars whose primary owner is bkamdar.

Note –
If you are using the CLD cache option, after moving a calendar to a different back-end server, you should clear the CLD cache to remove the server names. An out-of-date entry in the CLD cache can prevent a front-end server from finding a calendar after it has been moved.

To clear the CLD cache, follow these steps:
- Stop Calendar Server.
- Remove all files in the /var/opt/SUNWics5/csdb/cld_cache directory, but do not remove the cld_cache directory itself.
- Restart Calendar Server.

15.7 Administering Resource Calendars

This section describes how to administer resource calendars using the csresource utility.

The following are procedures for administering resource calendars:

15.7.1 To Display Resource Calendars and Attributes

To display a resource calendar, use the csresource utility list command.

For example, use the utility to perform the following tasks:

For example, to display a list of all Calendar Server resource calendars and their corresponding LDAP attributes:

csresource list
To display a list of all LDAP attributes for a specific resource calendar named Auditorium:

csresource -v list Auditorium

15.7.2 To Modify a Resource Calendar

This section describes how to modify a resource calendar. You must use the D.5 cscal utility command because the csresource utility does not have a modify command.

For example, the following command performs two tasks simultaneously:

It sets the owner uid to tchang.
It specifies another owner whoseuid is mwong.

cscal -o tchang -y mwong modify aud100

In this example, the cscal utility requires that resource's calid (aud100) is specified rather than the calendar name (Auditorium).

15.7.3 To Disable or Enable a Resource Calendar

You might need to disable a resource calendar to prevent users from scheduling events. For example, a conference room might be unavailable during remodeling, or an overhead project might be out for repair.

To disable or enable a resource calendar, use the csresource utility enable or disable command.

For example, to disable the resource calendar named Auditorium:

csresource disable Auditorium

Then, to enable the resource calendar later:

csresource enable Auditorium

15.7.4 To Delete a Resource Calendar

To delete a resource calendar, use the csresource utility delete command.

For example, to delete the Auditorium resource calendar, issue the following command:

csresource delete Auditorium

Calendar Server displays the following message:

Do you really want to delete this resource (y/n)?

Enter y to delete the calendar or n to cancel the operation.

If you enter y, Calendar Server deletes the calendar and displays a message that it has been deleted.

To Move a Resource Calendar to a Different Back-End Server

To move a user or resource calendar from one back-end server to another back-end server, follow these steps:

On the original server, disable the calendar resource using the D.15 csresource utility. For example to disable the resource with the common name Auditorium:

csresource disable Auditorium

On the original server, export each of the resources calendars from the calendar database to a file using the D.10 csexport utility. For example:

csexport -c aud100 calendar aud100.ics

Copy the exported calendar (*.ics) files from the original server to the new server.

On the new server, for each calendar exported, import the calendar from the file to the calendar database using the D.11 csimport utility. For example:

csimport -c bkamdar calendar bkamdar.ics

On the LDAP directory server, update the calendar owner’s icsDWPHost LDAP attribute to point to the new back-end server using the D.3 csattribute utility. To update an attribute, you must first delete the attribute and then add it with the new value. For example, to set the new server name to sesta.com:

csattribute -a icsDWPHost delete bkamdar csattribute -a icsDWPHost=sesta.com add bkamdar

On the new server, enable the calendar resource using the D.15 csresource utility. For example:

csresource enable bkamdar

On the new server, use the following commands to verify that the attributes are correct and that each calendar has been moved correctly. For example:

cscal -v -o bkamdar list bkamdar csattribute -v list bkamdar

On the original server, delete each calendar you just moved. For example:

cscal -o bkamdar delete bkamdar

The -o option deletes all calendars whose primary owner is bkamdar.

Note –
If you are using the CLD cache option and you have moved a calendar to a different back-end server, you should clear the CLD cache to remove the server names. An out-of-date entry in the CLD cache can prevent a front-end server from finding a calendar after it has been moved. To clear the CLD cache, follow these steps:
- Stop Calendar Server.
- Remove all files in the /var/opt/SUNWics5/csdb/cld_cache directory, but do not remove the cld_cache directory itself.
- Restart Calendar Server.

15.8 Linking to a Calendar

You can create a link to one or more user or resource calendars, as long as each calendar has the permissions set to allow read access. For example, you can embed a calendar link in a web page or email message. Other users can then view the calendar anonymously without having to log into Calendar Server.

To create a link to one or more user calendars, use this syntax:

http://CommunicationsExpresshostname:
CommunicationsExpressport/uwc/
   ?calid=calid-1[; ... ;calid-n]

For multiple calendars, separate each calendar ID (calid) with a semicolon (;).

For example, to link to the default calendar for jsmith@sesta.com, and jdoe@siroe.com, enter:

http://calendar.sesta.com:8080/uwc/?calid=jsmith@sesta;jdoe@siroe.com

To link to a resource calendar for an overhead projector with the calid overhead_projector10:

http://calendar.sesta.com:8080/uwc/?calid=overhead_projector10

15.9 Importing and Exporting Calendar Data in Calendar Server 6.3 Databases

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.

15.9.1 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@sesta.com from the file jsmith.ics that was saved in iCalendar (text/calendar MIME) format:

csimport -c jsmithcal@sesta.com calendar jsmith.ics

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

csimport -c jsmithcal@sesta.com calendar jsmith.xml

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

The following examples show how to use the export utility:

To export the calendar with the calendar ID (calid) jsmithcal@sesta.com in iCalendar (text/calendar MIME) format to a file named jsmith.ics:

csexport -c jsmithcal@sesta.com calendar jsmith.ics
To export the calendar jsmithcal@sesta.com in XML (text/xml MIME) format to a file named jsmith.xml:

csexport -c jsmithcal@sesta.com calendar jsmith.xml

Chapter 16 Administering Calendar Server Databases with the csdb Utility

Calendar Server keeps many database files in multiple directories. You must protect your database files either by implementing the automatic back up process described in Chapter 9, Configuring Automatic Backups (csstored), or by implementing your own system of backups. You can administer the database files using the csdb utility.

This chapter describes how to manage Calendar Server databases using the csdbutility, and includes the following sections:

16.1 Using the csdb Utility to Manage Calendar Databases

To administer database files, use the Calendar Server utility csdb. This section contains topics:

16.1.1 Identifying the Three Logical Database Groups

The calendar database utility csdb treats the database files as three logical databases (groups):

16.1.1.1 Calendar Database Group (csdb)

The caldb database consists of all the .db files and the _db.* files found in the database directory. The following is the default location for the calendar database files (as well as the cld_cache and ldap_cache subdirectories):

/var/opt/SUNWics5/csdb

If you prefer, you can specify a different directory when running the Calendar Server configuration program (csconfigurator.sh). For information about the configuration program, refer to Chapter 2, Initial Runtime Configuration Program for Calendar Server 6.3 software (csconfigurator.sh)

The following table describes the various calendar database (caldb) files.

Table 16–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 18, Administering the Delete Log Database

16.1.1.2 Session Database Group (`sessdb`)

The session database consists of all files located in the following directories: /opt/SUNWics5/cal/lib/admin/session/ and /opt/SUNWics5/cal/lib/http/session/

16.1.1.3 Statistical Database Group (`statdb`)

The statistical database consists of all files found in the counter directory:

/opt/SUNWics5/cal/lib/counter/

16.1.2 Targeting Specific Database Groups with the csdb Utility

The csdb utility -t option allows you to specify a target database:

-t caldb: The calendar database group.
-t sessdb: The session database group.
-t statdb: The statistics database group.

Tip –

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

16.2 Administering Databases with the csdb Utility

This section describes how to use the D.8 csdb utility to perform the following administrative tasks:

Note –

To run the csdb utility, you must log in as a user who has administrative rights to the system where Calendar Server is running. For more information, see Appendix D, Calendar Server Command-Line Utilities Reference.

To List Status for a Database Group

To view the status of a database group (caldb, sessdb, statdb), use the csdb utility list command.

To list database status:

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

Change to the /sbin directory. For example, on Solaris Operating Systems, enter:

cd /opt/SUNWics5/cal/sbin

Run the list command against one or all of the database groups. For example, to list the status and statistics for all three database groups:

./csdb list

The code that follows shows sample output:

Sleepycat Software: Berkeley DB 4.1.25: (December 19, 2002)

Calendar database version: 3.0.0 [BerkeleyDB]
Total database size in bytes: 57344

Session database version: 1.0.0 [BerkeleyDB]
Total database size in bytes: 0

Counter database version: 1.0.0 [Memory Mapped Files]
Total database size in bytes: 118792

Or, you can choose to use the verbose mode. For example:

./csdb -v list

The following sample code shows the verbose output:

Sleepycat Software: Berkeley DB 4.1.25: (December 19, 2002)

Calendar database version: 3.0.0 [BerkeleyDB]
Total database size in bytes: 57344
Total number of calendars:    2
Total number of events:       0
Total number of tasks:        0
Total number of alarms:       0
Total number of gse entries:  0
Total number of master component entries:  0
Total number of deletelog entries:  0
Total logfile size in bytes:  5779919

Session database version: 1.0.0 [BerkeleyDB]
Total database size in bytes: 0
Total logfile size in bytes:  0

Counter database version: 1.0.0 [Memory Mapped Files]
Total database size in bytes: 118792

Or, use the -t option to specify one target database group (caldb, sessdb, or statdb). For example, to view database status and statistics for only the calendar database:

csdb -t caldb list

To Check for Corruption in the Calendar Database Group

Use the check command to scan for corruptions in the calendar database, including calendar properties (calprops) and events and todos (tasks). If the check command finds an inconsistency that cannot be resolved, it reports the situation in its output.

The check command does not check for corruption in the alarm or group scheduling engine (GSE) databases.

To check for database 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.*) or log (log.*) files.

Change to the cal-svr-base/SUNWics5/cal/sbin directory. For example, on Solaris Operating 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).

After you run the check command, review the output file.

If your database is corrupted, you can choose to replace it with your hot backup copy. Alternately, you can choose to try to rebuild the corrupted one by running the rebuild command.

To Rebuild the Calendar Database Group (caldb), Without the GSE Database

To recover a damaged calendar database (caldb), use the csdb utility rebuild command. The rebuild command scans all of the calendar databases for corruption. If the rebuild command finds an inconsistency, it generates a rebuilt calendar database (.db files) in the cal-svr-base/SUNWics5/cal/sbin/rebuild_db directory.

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

In the instructions that follow, the rebuild command does not rebuild the group scheduling engine (GSE) database.

To rebuild the calendar databases without the GSE database:

Stop Calendar Server.

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

Change to the cal-svr-base/SUNWics5/cal/sbin directory. For example, on Solaris Operating Systems, enter:

cd /opt/SUNWics5/cal/sbin

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 you made of your calendar database:

./csdb rebuild /tmp/db /tmp/

If you don’t specify a database directory, the rebuild command uses the database

in the current directory. In the preceding example, the /tmp/ parameter specifies the destination directory for the rebuilt database.

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:
1. ./csdb rebuild db_0629
  
  Then check for corruption. If this backup copy is also corrupt, then run rebuild on the next backup copy.
2. ./csdb rebuild db_0615
  
  Then check for corruption. If this backup copy is also corrupt, then run rebuild on the next backup copy.
3. ./csdb rebuild db_0601
  
  ... etc.
The rebuild command writes the rebuilt database to the cal-svr-base/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, copy the rebuilt database (.db) files and the transaction log (log.*) file(s) from the rebuild_db directory to your production database.

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

Restart Calendar Server.

To Rebuild the Calendar Database Group, Including the GSE Database

If you have implemented group scheduling at your site, then you should include the GSE database in the rebuild.

To rebuild both the calendar databases and the GSE database:

Determine if the GSE database has any entries by running the csschedule -v list command and then let the GSE finish processing the entries.

Stop Calendar Server.

Make a copy of your calendar database, if you haven’t already done so.

Copy the database (.db) files and the log (log.*) files. You don’t need to copy any share (__db.*) files.

Change to the cal-svr-base/SUNWics5/cal/sbin directory.

For example, on Solaris Operating Systems, enter:

cd /opt/SUNWics5/cal/sbin

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 -g rebuild /tmp/db /tmp/

If you don’t specify a database directory, rebuild uses the database in the current directory. In the preceding example, the /tmp/ parameter specifies the destination directory for the rebuilt database.

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/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, copy the rebuilt database (.db) files from the rebuild_db directory to your production database.

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

Restart Calendar Server.

Example 16–1 Sample Rebuild Output

The sample output shows the events and the todos databases scanned twice each. This is not an error. It scans the first time to verify the information in the calprops database and then scans again to make sure calprops is accessible from the calendar database.

The following example shows the command and the output that it generated:

# ./csdb -g rebuild
Building calprops based on component information.
Please be patient, this may take a while...
Scanning events database...
512 events scanned
Scanning todos database...
34 todos scanned
Scanning events database...
512 events scanned
Scanning todos database...
34 todos scanned
Scanning deletelog database...
15 deletelog entries scanned
Scanning gse database...
21 gse entries scanned
Scanning recurring database...
12 recurring entries scanned
Successful components db scan
Calendar database has been rebuilt
Building components based on calprops information.
Please be patient, this may take a while...
Scanning calprops database to uncover events...
25 calendars scanned
Scanning calprops database to uncover todos...
25 calendars scanned
Successful calprops db scan
Calendar database has been rebuilt

16.2.1 To Delete a Database Group

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.

For example, to delete the calendar database:

csdb -t caldb delete

The csdb utility issues a warning before deleting the database.

Chapter 17 Backing Up and Restoring Calendar Server Data

If you have chosen not to use the automatic backup facility provided by Calendar Server (using csstored), then you need to implement a backup procedure to protect your data. This chapter describes how to use Calendar Server tools and other Sun tools to perform a manual backup and restore of calendar database files.

To back up and restore Calendar Server data in the /var/opt/SUNWics5/csdb directory, use these command-line utilities:

The csbackup command backs up the calendar database, a specific calendar, or a user’s default calendar. The directories to be backed up must be owned by the runtime user (icsuser), or you will receive an error message when you attempt to restore the data.
The csrestore command restores the calendar database, individual calendars, or a user’s default calendar that was saved using csbackup.

Note –

If you have an existing custom script that uses the Berkeley database tools (such as, db_recover), you might find that the tools do not work after upgrading to Calendar Server version 6.3. In earlier versions of Calendar Server software, the tools were compiled with a static library. They are now compiled with a dynamic library.

To accommodate this change, alter your custom script to use the dynamic link library, as follows: Change the global variable LD_LIBRARY_PATH to the name of the dynamic library (libdb-4.2.so).

This chapter includes these sections:

Caution –

Calendar Server version 2 data is not compatible with the current product. Do not try to restore calendar data backed up by the Calendar Server version 2 backup utility, because data loss can occur.

If you have version 2 calendar data that you want to move to the current release, you must contact technical support for the appropriate migration utilities.

17.1 Backing Up Calendar Server Data

The csbackup utility can back up the calendar database, a specified calendar, or a user’s default calendar. This section describes:

To Back Up the Calendar Database to a Directory

Use the csbackup utility database command.

For example, to back up the calendar database to a directory named backupdir:

csbackup -f database backupdir

Verify the correct version of the database was backed up by checking the ics50caldb.conf version file in the backup directory.

Note –
The csbackup utility fails if the target backup directory already exists and you do not specify the -f option. For example, the following command fails if backupdir exists, even if the directory is empty:

csbackup database backupdir

Therefore, if you specify a target backup directory that already exists, include the -f option when you run csbackup.

You can also specify a nonexistent target backup directory and let csbackup create the directory for you.

To Back Up a Specific Calendar to a File

To backup a calendar to a file in iCalendar or XML format, use the csbackup utility calendar command.

The filename extension (.ics or .xml) of the backup file indicates the format.

For example, to backup the calendar jsmithcal@sesta.com in iCalendar format (text/calendar MIME) to the file jsmith.ics in the backupdir directory:

csbackup -c jsmithcal@sesta.com calendar backupdir/jsmith.ics

Or, to backup the calendar jsmithcal@sesta.com in XML format (text/XML) to the file jsmith.xml in the backupdir directory:

csbackup -c jsmithcal@sesta.com calendar backupdir/jsmith.xml

To Back Up a User’s Default Calendar to a File

To back up a user’s default calendar to a text file in iCalendar or XML format, use the csbackup utility defcal command. The filename extension (.ics or .xml) that you specify for the output file determines which format is used.

For example, to back up the fault calendar for user jsmith@sesta.com in iCalendar (text/calendar MIME) format to a file named jsmith.ics in the backup directory:

csbackup -a jsmith@sesta.com defcal backupdir/jsmith.ics

Or, to back up the default calendar for user jsmith@sesta.com in XML (text/xml MIME) format to a file named jsmith.xml in the backup directory:

csbackup -a jsmith@sesta.com defcal backupdir/jsmith.xml

17.2 Restoring Calendar Server Data

The csrestore utility restores the calendar database, individual calendars, or a user’s default calendar that was saved using csbackup. You must run the csrestore utility on the local machine where Calendar Server is installed, and you must first stop Calendar Server. (Calendar Server can be running, however, when you backup the database.)

This section describes:

To Restore the Calendar Database

To restore a calendar database that was saved to a backup directory using the csbackup utility, use the csrestore utility database command.

For example, to restore the calendar database that was saved to a backup directory named backupdir:

csrestore database backupdir

To Restore a Calendar From a Backup Directory

To restore a specific calendar from a database that was saved to a backup directory using the csbackup utility, use the csrestore utility database command with the -c option.

For example, to restore the calendar jsmithcal@sesta.com from the backup database directory backupdir:

csrestore -c jsmithcal@sesta.com calendar backupdir

To Restore a Calendar From a File

To restore a specific calendar that was saved to a backup file using the csbackup utility, use the csrestore utility calendar command with the -c option.

The filename extension (.ics or .xml) of the backup file indicates the format in which the calendar was saved.

For example, to restore the calendar jsmithcal@sesta.com that was saved in iCalendar (text/calendar MIME) format to the file jsmith.ics located in the backupdir directory:

csrestore -c jsmithcal@sesta.com calendar backupdir/jsmith.ics

Or, to restore the calendar jsmithcal@sesta.com that was saved in XML (text/calendar MIME) format to the file jsmith.xml located in the bcakupdir directory:

csrestore -c jsmithcal@sesta.com calendar backupdir/jsmith.xml

To Restore a User’s Default Calendar

To restore a user’s default calendar that was saved to a backup file using the csbackup utility, use the csrestore utility defcal command.

The filename extension (.ics or .xml) of the backup file indicates the format in which the calendar was saved.

For example, to restore the default calendar for user jsmith@sesta.com that was saved in iCalendar (text/calendar MIME) format to a file named jsmith.ics located in the backup directory backupdir:

csrestore -a jsmith@sesta.com defcal backupdir/jsmith.ics

To restore the default calendar for jsmith default calendar that was saved in XML (text/xml MIME) format to a file named jsmith.xml located in the backup directory backupdir:

csrestore -a jsmith@sesta.com defcal backupdir/jsmith.xml

17.3 Using Sun StorEdge Enterprise Backup^TM or Legato Networker®

You can also use either Sun StorEdge Enterprise Backup software (formerly Solstice Backup) or Legato Networker to back up and restore Calendar Server data. The Sun StorEdge Enterprise Backup software and Legato Networker are similar, and the instructions in this section apply to both products.

Before attempting to backup Calendar Server, however, see the Sun StorEdge Enterprise Backup or Legato Networker documentation.

For the Sun StorEdge Enterprise Backup software documentation, see http://docs.sun.com.

This section describes:

17.3.1 StorEdge or Legato Tools

Calendar Server provides the following files in the /opt/SUNWics5/cal/sbin directory to use with the Sun StorEdge or Legato backup software:

icsasm: Calendar Server Application Specific Module (ASM). An ASM is a program that can be invoked by the Sun StorEdge or Legato backup software to back up and restore data.
legbackup.sh: Script that calls the csbackup utility.
legrestore.sh: Script that calls the csrestore utility.

To Back Up Calendar Data Using Sun StorEdge Enterprise Backup Software or Legato Networker

To backup the calendar database using the Sun StorEdge or Legato backup software:

Copy the Sun StorEdge or Legato nsrfile binary file to the /usr/lib/nsr directory.

Create these symbolic links in the /usr/lib/nsr directory:

icsasm -\> /opt/SUNWics5/cal/sbin/icsasm nsrfile -\> /usr/lib/nsr/nsrfile

Change to the /opt/SUNWics5/cal/sbin directory and run the csbackup utility with the -l option. For example:

cd /opt/SUNWics5/cal/sbin ./csbackup -l

The -l option creates a backup directory image under the current directory. The files in this directory are empty and are used only to provide information to the backup program about how calendars will be stored on the backup media. If the backup directory already exists, it is synchronized with the current directory structure.

Use the save command to back up calendar data. For example:

/usr/bin/nsr/save -s /opt/SUNWics5/cal/sbin/budir

You can also use the Sun StorEdge or Legato backup GUI to schedule backups by setting up a client save set to periodically backup the database.

Notes Do not modify the .nsr files. These generated files contain directives that are interpreted by the save command and the icsasm command during the backup process.

Calendar Server does not support the incremental backup feature. Do not use this feature because the backup directory is only an image of the folder structure and contains no actual data.

You cannot backup a calendar with a name that contains non-ASCII characters or the forward slash (/).

Automate the backup procedure.

The preceding steps describe how to run a backup manually. Set up the backup program’s backup command to run the Calendar Server csbackup command-line utility before the running the backup program’s save command to achieve an automated backup process.

To Restore Calendar Data Using Sun StorEdge Enterprise Backup Software or Legato Software

To restore calendar data:

Use the Sun StorEdge Enterprise Backup software nwrestore feature or the recover command to restore backed-up calendar information.

If you use nwrestore, you receive the message:
"File already exists. Do you want to overwrite, skip, backup, or rename?"

Choose overwrite.

This message appears because the backup tree is just the directory hierarchy. That is, it consists of empty files and stays that way permanently.

Chapter 18 Administering the Delete Log Database

Calendar Server includes the Delete Log database (ics50deletelog.db) to store deleted events and todos (tasks).

In early releases, Calendar Server did not maintain a database of deleted events and tasks. User interfaces that store a local copy of the calendar events and tasks had difficulty trying to determine which events had been deleted. Client software was forced to compare the unique identifiers (uid) or recurrence identifiers (rid) of all events or todos (tasks) with the Calendar Server copy of the data in order to determine which components had been deleted. This limitation directly affected installations that used WCAP commands to develop a client user interface (UI). To solve this limitation, the delete log database was created.

Delete logs need to be managed, as any database file must be. The following sections describe management of deletelog files:

18.1 Creating the Delete Log Database

Calendar Server automatically creates the Delete Log database (ics50deletelog.db) in the csdb directory along with the other Calendar Server database files. Calendar Server writes events and todos to the Delete Log database as follows:

Non-Recurring Events and Todos

When a non-recurring event or todo is deleted, Calendar Server removes it from the Events database (ics50events.db) or Todos database (ics50todos.db) and then writes it to the Delete Log database (ics50deletelog.db).
Recurring Events and Todos

When individual instances of a recurring event or task are deleted, Calendar Server writes each deleted instance of the event or task to the Delete Log database (ics50deletelog.db).

When all instances of a recurring event or todo are deleted, Calendar Server deletes the master component from the event or todo database and then writes it to the Delete Log database. A master component in the Delete Log database will contain the rrules, rdates, exrules, and exdates recurrence parameters.

18.2 Querying the Delete Log Database

This section describes how to query the delete log database.

To return entries from the Delete Log database, use the fetch_deletedcomponents WCAP command in either Expanded Mode or Compressed Mode.

The following information explains when and how to specify each mode.

Expanded Mode (recurring = 0)

If the recurring parameter is 0, fetch_deletedcomponents returns all instances of recurring events that match the criteria, but it does not return the master component for recurring events.
Compressed Mode (recurring = 1)

If the recurring parameter is 1, fetch_deletedcomponents returns non-recurring events and the master components for any recurring events, but it does not return individual recurring events.

If all instances in a recurring chain are deleted, the master component returns the dtstart, dtend, rrules, rdates, exrules, exdates, and uid parameters.

Also, the fetch_deletedcomponents command does not return master components associated with the deleted recurring instances that are still active. To return active master components, use the fetchcomponents_by_lastmod WCAP command. The fetch_deletedcomponents command should be used in conjunction with the fetchcomponents_by_lastmod command.

For more about WCAP commands, see the Sun Java System Calendar Server 6.3 WCAP Developer’s Guide.

18.3 Purging the Delete Log Database

This section describes how to purge the delete log database. Calendar Server provides two types of purging of the delete log database, automatic and manual.

This section contains the following topics:

18.3.1 Tuning Delete Log Purging

Before purging the delete log database, you need to be very aware of the end users you are serving. If your end users are using Communications Express, the default parameter settings should be adequate. If , however, they are using client user interfaces that store a local copy of the events and tasks, such as the Connector for Microsoft Outlook, or the Sync Tool, then you must adjust the settings of the automatic purge configuration parameters to fit their needs. Typically, they need the delete log to include up to 30 days or more of entries. This will cause the size of the delete log to increase dramatically. A failure to make this adjustment could cause problems with the database. The purge interval should also be adjusted to fit the needs of the users. For instance, there might not be a point in running purge every minute when your Delete log database is holding 30 days of data before it will be allowed to be purged. Things will age out daily, though, so a daily purge would be reasonable.

Similar problems can occur running cspurge manually. If too much is removed from the Delete log, it can cause users of the Connector for Microsoft Outlook and the Sync Tool to get out of sync with the server database.

Waiting too long to purge the Delete log database can cause the files to grow very large. Then, when a giant purge occurs, daily transaction logs grow greatly, reflecting the fact that each item purged is a transaction recorded in those logs and then archived to the archive and hot backups. These large anomalies in the transaction logs can make it appear as if there is a system problem and cause time to be lost figuring out what happened.

18.3.2 Automatic Purge of the Delete Log Database

If you wish, you can have Calendar Server automatically purge entries in the Delete Log database at a specified interval. By default the automatic purge is disabled.

The following ics.confparameter controls the automatic purge feature.

Table 18–1 Configuration Parameters for Automatic Purge of the Delete Log Database


Parameter	Description
`service.admin.purge.deletelog`	Enables (`"yes"`) or disables (`"no"`) the automatic purge of Delete Log database (`ics50deletelog.db`) entries. The default is `"no"`.
`caldb.berkeleydb.purge.deletelog.interval`	Specifies the interval time in seconds to automatically purge entries in the Delete Log database (`ics50deletelog.db`). The default is `60` seconds.
`caldb.berkeleydb.purge.deletelog.beforetime`	Specifies a time in seconds before which to purge entries in the Delete Log database (`ics50deletelog.db`). The default is `518400` seconds (6 days).

For example, to have Calendar Server automatically purge Delete Log database entries every five minutes (600 seconds) that are more than 2 days old (172800 seconds), set parameters in 18.3.2 Automatic Purge of the Delete Log Database as follows:

service.admin.purge.deletelog="yes"
 caldb.berkeleydb.purge.deletelog.interval=600
 caldb.berkeleydb.purge.deletelog.beforetime=172800

After you set these parameters, restart Calendar Server for the new values to take effect.

18.3.3 Manual Purge of the Delete Log Database

You can choose to manually purge entries in the Delete Log database (ics50deletelog.db), using the cspurge utility:

Usage of this utility is as follows:

cspurge -e endtime -s starttime

The variables endtime and starttime specify the ending and starting times in Zulu time (also referred to as GMT or UTC).

To run cspurge, you must be logged in as the user and group under which Calendar Server is running (defaults are icsuser and icsgroup) or as root.

For example, to purge entries from July 1, 2003 through July 31, 2003:

cspurge -e 20030731T235959Z -s 20030701T120000Z

For more information, see D.13 cspurge.

18.4 Using Calendar Server Utilities for the Delete Log Database

The following table lists the Calendar Server utilities that support the delete log database (ics50deletelog.db).

Table 18–2 Utilities that Support the Delete Log Database


Utility	Description
`cspurge`	Allows the manual purge of entries in the Delete Log database.
`csbackup` and `csrestore`	Supports the backup and restore of the Delete Log database.
`csstats`	Reports Delete Log database statistics.
`csdb`	Supports the rebuild, recover, and check operations on the Delete Log database.
`cscomponents`	Lists (read-only) the number of entries in the Delete Log database.

For more information, including the syntax for these utilities, see Appendix D, Calendar Server Command-Line Utilities Reference.

Chapter 19 Administering Calendar Server Time Zones

This chapter describes how Calendar Server software defines and processes time zones.

This chapter contains the following sections:

For more information about time-zone properties and parameters, refer to the RFC 2445, Internet Calendaring and Scheduling Core Object Specification (iCalendar):

http://www.ietf.org/rfc/rfc2445.txt

19.1 Overview of Calendar Server Time Zones

This section contains an overview of time zones as implemented by Calendar Server software.

The timezones.ics file contains the representation of the time zones supported by Calendar Server. The file is located in the following directory:

/etc/opt/SUNWics5/config/

At startup, Calendar Server reads the timezones.ics file, generates time-zone data, and then stores the data in memory. Thus, time-zone data is kept in memory while Calendar Server is running. Consequently, if you add a new time zone or modify an existing one, you must stop and restart Calendar Server for the change to take effect.

Time zones in the timezones.ics file are identified by the TZID parameter. For example, Calendar Server identifies the Pacific Standard Time (PST/PDT) zone using the America/Los_Angeles TZID, as shown in Example 19–1. The TZNAME property is an abbreviated representation of the time zone, such as PST (Pacific Standard Time) for the America/Los_Angeles time zone.

Time zones such as America/Los_Angeles that recognize daylight savings time (DST) contain two subcomponents: STANDARD for standard time and DAYLIGHT for DST. The X-NSCP-TZCROSS list contains a series of dates that indicate when the time zone changes to and from DST (DAYLIGHT) and standard (STANDARD) time.

The RRULE property defines the pattern of the STANDARD and DAYLIGHT rules. The TZOFFSETFROM and TZOFFSETTO properties define the offset from GMT before and after the DST to standard or standard to DST change occurs. The Communications Express user interface uses the dates in X-NSCP-TZCROSS to determine when to display a change in the time zone.

A WCAP command that includes the time zone ID (tzid) parameter should refer to a valid time zone defined in the timezones.ics file. Calendar Server then returns data using that time zone. If a WCAP command specifies an unrecognized time zone, Calendar Server returns data in the GMT time zone by default. For more information about WCAP, refer to theSun Java System Calendar Server 6.3 WCAP Developer’s Guide.

Example 19–1 America/Los_Angeles Time-Zone Representation in the `timezones.ics` File

The following example shows the America/Los_Angeles time zone representation in the timezones.ics file.

19.2 Managing Calendar Server Time Zones

This section contains conceptual information and instructions on how to manage time zones.

This section contains the following topics:

19.2.1 Adding a New Time Zone

This section describes how to add a new time zone to Calendar Server, so that it is available in the Communications Express user interface. For example, you might want to add a new time zone for America/Miami.

The simplest way to add a new time zone is to copy and edit time-zone entries that are similar to the time zone you want to add in each of the files described in the following steps. For example, if you want to add a time zone for America/Miami, copy and edit the time-zone entries in each file for America/New_York. If your new time zone has Daylight Savings Time (DST), try to find a similar block to copy.

19.2.2 Modifying an Existing Time Zone

This section describes how to modify an existing time zone. For example, you might want to change the name of a time zone, such as “America/Phoenix” to “US/Arizona”.

To Modify an Existing Time Zone

Modify the time-zone block for the time zone you want to change in the following file:

/etc/optSUNWics5/config/timezones.ics

If you are changing a time-zone name, change the TZID entry to the new name.

Modify the getDisplayNameofTZID template in the following file:

cal-svr-base/SUNWics5/cal/html/language/i18n.xsl

where: language specifies the directory for the language your site is using. For example: en for English or fr for French.

If you are changing the name, change the existing time-zone name to the new name.

Modify the following XML files for changes to the time zone:

cal-svr-base/SUNWics5/cal/html/change_timezone.xml

cal-svr-base/SUNWics5/cal/html/new_cal.xml

cal-svr-base/SUNWics5/cal/html/new_group.xml

For information about the entries in these files, see 19.2.1 Adding a New Time Zone.

If the change affects the default time zone for user preferences, modify the “icsTimeZone” entry in the following file:

cal-svr-base/SUNWics5/cal/html/default_user_prefs.xml

Note –
Steps 2, 3, and 4 are required only if you use the Calendar Express user interface.

Stop (if necessary) and then restart Calendar Server for your time zone changes to take effect.

Chapter 20 Using Instant Messaging Pop-up Reminders

Calendar Server is integrated with Sun Java System Instant Messaging 6.0 (or later) to provide automatic pop-up reminders for both calendar events and tasks.

This chapter contains conceptual information and instructions on how to configure pop-up reminders.

This chapter contains the following sections:

20.1 Pop-up Reminders Overview

This section contains the conceptual information you need to understand how pop-up reminders work in Calendar Server software.

This section contains the following topics:

20.1.1 Configuration Concepts for Calendar Pop-up Reminders

This section describes what must be configured to make pop-up reminders work.

Users can receive Instant Messenger pop-up reminders for upcoming events and tasks on their calendars.

To enable these pop-up reminders, two things must happen:

The administrator must configure Calendar Server and Instant Messaging Server to allow pop-up notifications.
The end user must specify email reminders in the Options tab of Communications Express, which sets an alarm in the Event Notification System.
The end user must enable calendar reminders in Instant Messenger.

With pop-ups enabled, when an impending event or task nears, the alarm set in the Event Notification System causes Calendar Server to send an email notification and Instant Messaging to display a pop-up reminder.

A Calendar Server administrator can choose to configure either email notifications or pop-up reminders or both for end users. For example, to turn email reminders off, set the following parameter in the ics.conf file:

caldb.serveralarms.binary.enable= "no"

20.1.2 How Pop-up Reminders Work

This section describes how pop-up reminders work.

If configured, Instant Messaging pop-up reminders follow this architectural flow:

The Instant Messaging JMS subscriber subscribes to Calendar Server events and notifications in the Event Notification Service (ENS).
Calendar Server publishes an event or task notification in text/xml or text/calendar format to ENS.
The Instant Messaging JMS subscriber receives the calendar event or task notification and then generates a message in text/calendar format.
The Instant Messaging server sends the message to the calendar owner, if the end user is online.
If the recipient is available, Instant Messenger generates an HTML pop-up reminder on the end user’s desktop based on the message.

20.2 Configuring Pop-up Reminders

This section contains instructions for configuring pop-up reminders for Calendar Server software.

This section includes the following configuration instructions:

To Configure Instant Messaging Server

The high level list of tasks necessary to configure Instant Messaging for Pop-ups that follows is for your convenience. To configure Instant Messaging, refer to the Instant Messaging documentation available at:

http://docs.sun.com/coll/1309.2

Install the new package SUNWiimag.

Before you can use Instant Messaging for Pop-ups, the Instant Messaging package must be installed using the Java Enterprise System installer.

On the machine where Instant Messaging is installed, change to the following directory:

cd /etc/opt/SUNWiim/default/config

Edit one or more of the parameters in the iim.conf file as shown in the following table.

The parameter values shown assume you want pop-up reminders for both events and tasks. If these parameters do not already exist in your iim.conf file, add them.

Parameter	Description and Appropriate Value to Use
JMS Consumers Section
`jms.consumers`	Name of alarm. Set the value to `cal_reminder`.
`jms.consumer.cal_reminder.destination`	Destination of the alarm. Set the value to enp:///ics/customalarm
`jms.consumer.cal_reminder.provider`	The name of the provider. Set to `ens`. This must be the same as the name in `jms.providers` in the JMS Providers section.
`jms.consumer.cal_reminder.type`	The type of alarm to set. Set the value to `topic.`
`jms.consumer.cal_reminder.param`	The alarm parameter. Set the value to `"eventtype=calendar.alarm" (including the quotes)`
`jms.consumer.cal_reminder.factory`	C++ factory name. Set the value to: com.iplanet.im.server. JMSCalendarMessageListener
JMS Providers Section
`jms.providers`	The name of the provider. Set value to `ens`. This must be the same as the value listed in the JMS Consumers Section for `jms.consumer.cal_reminder.provider.`
`jms.provider.ens.broker=cal.example.com`	Port number that ENS listens on. Set to the port specified in the `ics.conf` file parameter `service.ens.port`. The default is 57997.
`jms.provider.ens.factory`	C++ factory to use. Set to `com.iplanet.ens.jms.EnsTopicConnFactory`
Calendar Server General Parameters
`iim_agent.enable`	Enables the Calendar agent. Set the value as follows including the quotes: `iim_agent.enable="true"`
`iim_agent.agent-calendar.enable`	Loads a component that enables the Calendar agent. Set the value as follows including the quotes: `iim_agent.agent-calendar.enable="true"`
`agent-calendar.jid`	The JID of the Calendar agent. Set this value as follows: `agent-calendar.jid=calimbot.server.domain`
`agent-calendar.password`	The Calendar agent password. Set this value as follows: `agent-calendar.password=password`
`iim_server.components`	Set this value as follows: `iim_server.components=agent-calendar`

Change to the directory where the imadmin command-line utility is located:

cd /opt/SUNWiim/sbin

Start the Calendar agent using imadmin:

imadmin start agent-calendar

The Calendar agent is an Instant Messaging component that provides pop-up functionality to Calendar Server users. Using tools provided with Instant Messaging, you can start, stop, restart, or check the status of the Calendar agent as well as monitor its activity through log files.

Note –
If you have scripts that include the stop, start, and refresh commands, add the calendar agent to them.

For more information about imadmin and the Calendar agent, see the Sun Java System Instant Messaging 7 2005Q1 Administration Guide.

To Configure Calendar Server

Before You Begin

Confirm that the ics.conf parameters shown in the following table have the values shown. If they do not, or you wish to customize them, perform the following steps:

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit the ics.conf parameters as shown in the following table:

Parameter	Description and Default Value
`caldb.serveralarms`	Enables calendar alarms to be queued. The default is `“yes”` (enabled).
`caldb.serveralarms.contenttype`	Output format for alarm content. The default is `"text/xml"`.
`caldb.serveralarms.dispatch`	Enables calendar alarms to be dispatched. The default is `“yes”.`
`caldb.serveralarms.dispatchtype`	The type of server alarm to dispatch. The default is `"ens"`.
`caldb.serveralarms.url`	This is the URL for alarm retrieving alarm contents. The default is `"enp:///ics/customalarm"`.

Save the file as ics.conf.

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

To Configure Instant Messenger

To receive pop-up reminders for Calendar Server events and tasks, end users must configure their Instant Messenger as follows:

On the Main window, from the Tools menu, select Settings.

On the Settings window, click the Alerts tab.

Check the Show Calendar Reminders option.

Click OK.

Chapter 21 Tuning Calendar Server Performance

This chapter contains conceptual information and instructions for tuning Calendar Server performance.

To improve the performance of Calendar Server, consider the following options:

21.1 Indexing the LDAP Directory Server

To improve performance when Calendar Server accesses the LDAP directory server, add indexes to the LDAP configuration file for the following attributes.

icsCalendar: This attribute is used to search for the default calendar for a calendar user or resource. Specify presence (pres), equality (eq), and substring (sub) index types.
icsCalendarOwned: This attribute is used to search for other calendars owned by the user. Specify presence (pres), equality (eq), and substring (sub) index types. See also 21.2 Improving Calendar Search Performance in a DWP Environment.
mail, mailAlternateAddress: These attributes specify a user’s primary and alternate email addresses. See also 14.1 Creating Calendar User LDAP Entries and 14.5.4.3 To Add Calendar Service with Calendar Server Utilities.

For information about adding directory server indexes, refer to Directory Server documentation found at:

http://docs.sun.com/coll/1316.1

21.2 Improving Calendar Search Performance in a DWP Environment

When you are in a DWP environment, that is, the calendar database is distributed across multiple back-end servers, searching for a calendar in the calendar database can be time consuming. It can be faster to look in the LDAP entry first and find out directly which DWP host the calendar resides on.

This section contains the following topics:

To Enable Calendar Searches to Look at LDAP

To enable calendar searches to look at the LDAP directory first, and the calendar database second, perform the following steps:

Stop Calendar Server services by issuing the stop-cal command.

Change to the configuration directory, /etc/opt/SUNWics5/cal/config.

Set the service.calendarsearch.ldap parameter in the ics.conf file to "yes", which is the default, as shown below:

service.calendarsearch.ldap="yes"

Restart Calendar Services as follows:

start-cal

Note –
If you are allowing anonymous access to public calendars, you might prefer to disable calendar searches from looking at LDAP. In fact, Communications Express expects the parameter value to be “no”.

To Improve Search Performance by Indexing

To determine if the calendar search performance can be improved by indexing, try the following LDAP command:
ldapsearch -b "base" "(&(icscalendarowned=*user*) (objectclass=icsCalendarUser))"
where base is the LDAP base DN of the directory server where the user and resource data for Calendar Server is located, and user is the value that an end user can enter in a search dialog in .

Tests have shown that with 60,000 entries, the above search took about 50-55 seconds without indexing icsCalendarOwned. After indexing, the above search took only about 1-2 seconds.

Index appropriate LDAP attributes, or at least, icsCalendarOwned, by running comm_dssetup.pl.

The comm_dssetup.pl, indexes this attribute and many others to improve performance in various ways. If you have not run comm_dssetup.pl, or ran it but did not perform the indexing, you can run the utility again to do the indexing, or you can use Directory Server tools to perform the indexing.

For information on how comm_dssetup.pl does indexing, see Attribute Indexes in the Sun Java System Communications Suite 5 Installation and Configuration Guide.

For information about adding directory server indexes, refer to Directory Server documentation found at:

http://docs.sun.com/coll/1316.1

21.3 Improving Performance of Calendar Searching by Disabling Wildcard Searches

By default, wildcard searches are disabled in Calendar Server. That is, when you search for a calendar using the graphical user interface, or when you issue search_calprops.wcap in your custom interface, it searches for an exact match to the search string passed in with the WCAP command.

If you have enabled wildcard searches by uncommenting the following line in the ics.conf file (by removing the exclamation point (“!”) at the beginning), you may be experiencing a negative impact on performance.

!service.calendarsearch.ldap.primaryownersearchfilter = "(&(|(uid=*%s*)(cn=*%s*))(objectclass=icsCalendarUser))"

To test the impact of wildcard searches on performance, comment out the line again by inserting the exclamation point (“!”) in front of it.

21.4 Improving Performance of the CLD Plug-in

Before the system accesses a calendar from the calendar database, it must determine which back-end machine stores that user’s calendars. To find the appropriate back-end machine, the system searches the LDAP directory for the user’s entry and picks up the icsDWPHost attribute. This search is time consuming, and it must be performed for every access to the calendar data. Every user session can result in many accesses of the database and thus many searches of the LDAP. To save time and enhance performance, enable the CLD cache by editing the ics.conf file as follows:

caldb.cld.cache.enable="yes"

The LDAP data cache stores the user ID and its associated icsDWPHost attribute. Before searching the LDAP for a user’s entry, the system checks the cache for the user’s ID. If it is in the cache, it picks up the back-end host name from the icsDWPHost attribute stored there. If it is not in the cache, the system performs the LDAP search and copies the user ID and attribute into the CLD cache. Subsequently, accesses to the user’s calendar data will be faster, since it will now find the user ID in the cache.

21.5 Improving Performance of the LDAP Data Cache

With the LDAP data cache enabled, you can tune it using the ics.conf parameters, adjust one or more of the parameters found in the following table.

Note –

The LDAP data cache is enabled by default. You can disable it by setting: local.ldap.cache.enable="no"

Table 21–1 ics.conf Parameters Used to Customize LDAP Data Caching


Parameter	Description/Value
`local.ldap.cache` `.checkpointinterval`	The number of seconds for the checkpoint thread to sleep between checkpoints. The default is `“60”`. In a high activity LDAP, you might want to decrease the interval to keep the cache as current as possible. At the same time, remember that the more often you refresh the cache, the more system overhead you introduce.
`local.ldap.cache.` `circularlogging`	Specifies whether to remove the LDAP data cache database log files after they have been processed. The default is `“yes”`. Do not change this parameter unless you have a custom clean up routine that will remove the old log files.
`local.ldap.cache.` `logfilesizemb`	Specifies the maximum size in megabytes of checkpoint file. The default is `"10”` megabytes. If you have a high activity LDAP, this file could fill up before the checkpoint interval is over. Try to set the value to a number that is close to the actual size of the logs according to your experience
`local.ldap.cache.` `maxthreads`	Specifies the maximum number of threads for the LDAP data cache database. The default is `“1000”`. In a high activity LDAP, you might want to increase the number of threads. This could cause increased CPU utilization. Decrease the number of threads only if your LDAP activity is minimal.
`local.ldap.cache.` `mempoolsizemb`	Specifies the number of megabytes of shared memory. The default is `“4”` megabytes.
`local.ldap.cache.` `entryttl`	Specifies the “time to live” (TTL) in seconds for an LDAP data cache entry. The default is `“3600”` seconds (1 hour). If your cache is filling up too fast (high activity), you can decrease the TTL time. However, this could increase the overall number of LDAP database accesses, which could slow the system down overall.
`local.ldap.cache.` `cleanup.interval`	Specifies the interval in seconds between each cache database cleanup. The default is `“1800”` seconds (30 minutes). The system removes expired entries. The time interval does not have to be the same as the entry TTL time. But synchronizing them can make it more efficient.
`local.ldap.cache.` `stat.enable`	Specifies whether or not to log the access to the LDAP data cache and to print statistics in the log file. The default is `“no”`. For performance enhancement, use this only in debug mode.
`local.ldap.cache.` `stat.interval`	Specifies the interval in seconds when each statistics report is written to the log file. The default is `“1800”` seconds (30 minutes). This is only active if `local.ldap.cache.stat.enable` is enabled. Decreasing the interval can help you pinpoint problems. Increasing the interval helps decrease system load.

Note –

Communications Express expects data caching to be disabled.

21.6 Tuning the LDAP SDK Cache

There are a couple of parameters that control how long an item stays in the cache, and how large the cache can be.

To tune the cache, edit one or more of the parameters as shown in the following table.

Table 21–2 ics.conf Parameters for Configuring the LDAP SDK Cache


Parameter	Description and Default Value
`service.ldapmemcachettl`	This is not currently implemented. You must manually remove the contents of the `ldap_cache` directory and then restart Calendar Server. If `service.ldapmemcache` is `"yes"`, this parameter is used to set the maximum number of seconds that an item can be cached. If `“0”`, there is no limit to the amount of time that an item can be cached. The default is `“30”`.
`service.ldapmemcachesize`	If `service.ldapmemcache` is `"yes"`, this parameter is used to set the maximum amount of memory in bytes that the cache will consume. If `“0”`, the cache has no size limit. The default is `“131072”`.

21.7 Tuning Automatic Backups

You must balance the number of backups you keep on disk with the need to not exceed available disk space. To help manage the amount of disk space your archival and hot backups take, you can change the settings of various ics.conf parameters that determine how many copies of the backups you keep at one time and where the disk space threshold is that will trigger clean up of the older copies.

There are three types of parameters that can be adjusted for the each backup type, archival and hot backup:

mindays – The minimum number of days worth of backups held on disk.
maxdays – The maximum number of days worth of backups held on disk.
threshold – The percentage of disk space used. This is used as a trigger point.

Calendar Server keeps backups for the maximum number of days possible without going over the threshold on disk space. So if the current backup is going to push the disk usage above the threshold, the system will purge the oldest backup copy and see if disk space usage goes below the threshold. It will continue to purge old backup copies until either of the following conditions is met: removing another backup copy would bring the number of backups on disk below the minimum number of backup copies, or the disk space usage falls below the threshold.

Therefore, you can manage the amount of disk space backups use with the threshold parameter. And conversely, you can manage how many backups you keep on disk by adjusting the amount of disk space and copies allowed.

The following table lists the ics.conf parameters that control the disk space and number of backups kept on disk.

Table 21–3 ics.conf Parameters Used to Set Number of Backups Held on Disk


`ics.conf` Parameters	Default Setting	Description
`caldb.berkeleydb.hotbackup.mindays`	3	Minimum number of days of hot backups held on disk.
`caldb.berkeleydb.hotbackup.maxdays`	6	Maximum number of days of hot backups held on disk.
`caldb.berkeleydb.hotbackup.threshold`	70	Percent of disk space used for hot backups. Triggers purge of oldest copies when exceeded.
`caldb.berkeleydb.archive.mindays`	3	Minimum number of days of archival backups held on disk.
`caldb.berkeleydb.archive.maxdays`	6	Maximum number of days of archival backups held on disk.
`caldb.berkeleydb.archive.threshold`	70	Percent of disk space used for archival backups. Triggers purge of oldest copies when exceeded.

21.8 Using Load Balancing Across Multiple CPU's

By default, load balancing is enabled in Calendar Server. Calendar Server achieves load balancing using the following algorithm: Processes accept one connection out of every n connections, where n is the number of processes.

To disable load balancing, add the service.http.loadbalancing parameter to the ics.conf file and set it to "no". Then restart Calendar Server for the change to take effect.

21.9 Controlling the Number of Processes Running for Each Service

If a server has multiple CPU's, by default Calendar Server distributes the HTTP Service (cshttpd processes) and Distributed Database Service (csdwpd processes) across the CPU's.

If you want to control the number of processes that run for each service, you can edit the service.http.numprocesses and service.dwp.numprocesses parameters. By default, these parameters are set to the number of CPU's for the server during installation, but you can reset these values. For example, if a server has 8 CPU's, but you want a cshttpd and csdwpd process to run in only 4 CPU's, set the parameters as:

service.http.numprocesses="4"
 service.dwp.numprocesses="4"

21.10 Using Timeout Values

This section contains conceptual information and instructions for tuning Calendar Server performance using timeout values for various ics.conf parameters.

The following types of timeouts exist:

Timeout Values for csadmind
21.10.2 HTTP Timeout Values for End Users
21.10.3 GSE Queue Timeout Value

For information about editing ics.conf parameters, see E.1 Editing the ics.conf Configuration File.

21.10.1 Timeout Values for `csadmind`

The following table describes the Calendar Server timeout parameters in the ics.conf file used by the Administration (csadmin) service.

Table 21–4 HTTP Timeout Values for the Administration Service (csadmin)


Parameter	Description
`service.admin.idletimeout`	Specifies the number of seconds the `csadmind` service waits before timing out an idle HTTP connection. The default is 120 seconds (2 minutes).
`service.admin.resourcetimeout`	Specifies the number of seconds the `csadmind` service waits before timing out an HTTP session for a resource calendar. The default is 900 seconds (15 minutes).
`service.admin.sessiontimeout`	Specifies the number of seconds the `csadmind` service waits before timing out an HTTP session. The default is 1800 seconds (30 minutes).

21.10.2 HTTP Timeout Values for End Users

The following table describes the Calendar Server HTTP timeout parameters in the ics.conf file that apply to end users.

Table 21–5 HTTP Timeout Values in ics.conf for End Users (cshttpd Service)


Parameter	Description
`service.http.idletimeout`	Specifies the number of seconds the `cshttpd` service waits before timing out an idle HTTP connection. The default is `"120"` seconds (2 minutes).
`service.http.resourcetimeout`	Specifies the number of seconds the `cshttpd` service waits before timing out an HTTP session for a resource calendar. The default is `"900"` seconds (15 minutes).
`service.http.sessiontimeout`	Specifies the number of seconds the `cshttpd` service waits before timing out an HTTP session. The default is `"1800"` seconds (30 minutes).

21.10.3 GSE Queue Timeout Value

The following ics.conf file parameter specifies the time in seconds to wait before Calendar Server scans the Group Scheduling Engine (GSE) queue for incoming jobs:

gse.belowthresholdtimeout="3"

If there are more jobs in the queue than the maximum threads allocated, the last thread always scans the queue again. Therefore, this setting only takes effect when the number of jobs is below the maximum threads allocated.

The default is "3". Increasing this number reduces the frequency the server scans the queue and can improve overall performance. However, if the queue is getting too large because of an increased volume of events, the time can be decreased to allow the queue to be processed faster. This may serve to slow down overall performance, but events will be updated sooner.

Chapter 22 Troubleshooting Calendar Server 6.3 Software

This chapter covers how to set up logging and what to do for some common problems.

The chapter contains the following topics:

22.1 Turning on Debugging Information for Calendar Server 6.3 Software

This section contains conceptual information and instructions on using logs and debugging to troubleshoot problems with your Calendar Server deployment.

While there is no one ics.conf parameter that puts the whole system in “debug mode”, this section describes some ways to get useful debug information:

Note –

Be sure to turn off excess logging and monitoring when not needed as it will negatively impact performance.

22.1.1 Increase Logging Level

Use the parameter shown in the following table to increase the verbosity of logging:

Parameter	Description and Default Value
`logfile.loglevel`	Set to `DEBUG` to get all levels logged, including `CRITICAL`, `ALERT`, `ERROR`, `WARNING`, `NOTICE`, and `INFORMATION`. This applies to all logs.

22.1.2 Enable Logging Access to the LDAP Cache

To log all accesses of the LDAP data cache and print out the log (report) set the ics.conf parameters shown in the following table:

Parameter	Description and Default Value
`local.ldap.cache.stat.enable`	Specifies whether or not to log the access to the LDAP data cache and to print statistics in the log file. The default is `“no”` (no statistics logged). Set to `“yes”` to enable logging of statistics. For performance enhancement, use this only in debug mode.
`local.ldap.cache.stat.interval`	Specifies the interval in seconds when each statistics report is written to the log file. The default is `“1800”` seconds (30 minutes). This is only active if logging is enabled. Decreasing the interval can help you pinpoint problems. Increasing the interval helps decrease system load.

Parameter

Description and Default Value

local.ldap.cache.stat.enable

Specifies whether or not to log the access to the LDAP data cache and to print statistics in the log file. The default is “no” (no statistics logged). Set to “yes” to enable logging of statistics.

For performance enhancement, use this only in debug mode.

local.ldap.cache.stat.interval

Specifies the interval in seconds when each statistics report is written to the log file. The default is “1800” seconds (30 minutes).

This is only active if logging is enabled. Decreasing the interval can help you pinpoint problems. Increasing the interval helps decrease system load.

22.1.3 Clearing the LDAP Cache

There is currently no logic in Calendar Server to expire LDAP cache data. You must manually remove the contents of the ldap_cache directory and restart Calendar Server.

To Clear the LDAP Cache

Stop Calendar Server.

Remove all files in the /var/opt/SUNWics5/csdb/ldap_cache directory, but do not remove the ldap_cache directory itself.

Restart Calendar Server.

22.1.4 WCAP Command and HTTP Access Logging

Two configuration parameters that facilitate debugging enable logging of incoming commands and HTTP accesses. Add one or both of these parameters to the ics.conf file to activate the logging:

service.http.commandlog = "yes" — The cshttpd process creates a file, http.commands, in the logs directory. The log contains each .shtml or .wcap command received by the server, including all parameters of each command.
service.http.commandlog.all = "yes" — The cshttpd process creates a file, http.access, in the logs directory. The log contains each HTTP request received by the system.

Caution –

The log files can grow very quickly and fill the available disk space. Monitor them carefully to avoid problems. Choose a period of low activity on your systems to run with these commands enabled. Performance will drop noticeably if run during peak hours. Always disable the two commands when you are finished troubleshooting.

22.1.5 Monitor the System Using the Calendar Server 6.3 csstats Utility

Use the csstats list command to display statistical information from counter objects defined in the counter.conf file.

For more information on the csstats utility, see Appendix D, Calendar Server Command-Line Utilities Reference.

22.2 Troubleshooting LDAP Issues

This section contains conceptual information on troubleshooting LDAP issues.

If you are creating a multiple domain environment for the first time, you must create the DC tree in LDAP by adding the appropriate entries for domains, containers, users, groups and resources. If the DC tree does not already exist when using a Calendar Server utility, such as cscal, you might see the following error message: "Initialization failed .... exiting".

Be sure that your DC tree contains at least one (default) domain under the DC tree root. Create the DC tree structure using instructions found in 13.2 Creating New Calendar Server Domains.

22.3 Troubleshooting Migration Utilities

Calendar Server offers several utilities for migrating calendar databases and LDAP directories.

This section contains the following topics:

22.3.1 What to do Before Calling Technical Support

In general, if you have trouble using the migration utilities, you should contact technical support.

Before calling, gather the following information:

Back-up copies of the databases in question.
Copies of all the pertinent logs.
Any error output messages, including cores.

22.3.2 Where to Find the Migration Utilities

The various migration utilities and their documentation can be found at the locations indicated in the list that follows:

Schema Migration Utility (commdirmig

This utility is bundled with Delegated Administrator, which is a separately installable component. It migrates your LDAP directory from Schema version 1 to Schema version 2. For information about this utility, see theSun Java Communications Suite 5 Schema Migration Guide.

Calendar Server 6.2 to 6.3 migration utilitycsmigrate

This utility can be found in the sbin directory after the software is installed.

Calendar Server 5 to Calendar Server 6.2 migration utility (cs5migrate

This utility can be found in the sbin directory after the software is installed.

Calendar Server multiple domain database preparation utility (csmig)

This utility can be found in the sbin directory after the software is installed.

Documentation for this utility can be found in Chapter 3, Database Migration Utilities for Calendar Server 6.3, which includes a troubleshooting section.

Calendar Server non-domain to multiple domain migration utility (csvdmig)

This utility can be found in the sbin directory after the software is installed.

Documentation for this utility can be found in Chapter 3, Database Migration Utilities for Calendar Server 6.3. Use this utility to prepares your calendar database and LDAP directory entries for multiple domains.

Note –

Always run csmig before csvdmig.

Calendar Server 2 to Calendar Server 6 Migration Utility (ics2migrate)

This utility is installed with Calendar Server. Documentation can be found in Chapter 3, Database Migration Utilities for Calendar Server 6.3. Use this utility to migrate your Calendar Server 2 databases to be compatible with Calendar Server 5.

Netscape Calendar Server 4 to Calendar Server 5 Migration Utility (ncs4migrate)

This utility is available only from technical support. The utility package includes documentation. This utility migrates Netscape Calendar Server 4 to Calendar Server 5. These migrations tend to require special attention because of the lack of uniformity in the source database. It is not unusual for a lot of manual This utility is available only from technical support. The utility package includes documentation. This utility migrates Netscape Calendar Server 4 to Calendar Server 5. These migrations tend to require special attention. It is not unusual for a lot of work on the source file to be necessary before the utility can be run. You might consider using Professional Services to help you plan your migration.

22.4 Non-Database Troubleshooting for Calendar Server

This section covers various troubleshooting ideas for non-database problems.

The following topics are covered in this section:

Tip –

In addition, there is a trouble shooting section for SSL in the SSL chapter:

7.2 Troubleshooting SSL for Calendar Server 6.3 Software

22.4.1 One cshttpd Process is Accepting Too Many Connections and Taking 100% of CPU Time

If one cshttpd process is accepting too many connections and taking 100% of CPU time, you might have disabled load balancing. To re-enable it, change the value of ics.conf parameter service.http.loadbalancing to "yes".

Fixing start-cal Problems

If not all of the calendar services started when you issued start-cal, the ones that did start must be stopped before restarting. For example, if enpd, csnotifyd, and csadmind started, but not cshttpd, then enpd,, csnotifyd, and csadmind must be stopped.

To start calendar services:

Issue the stop-cal command.

If the stop-cal command fails to stop all Calendar Server services, there might be some child processes still running. To handle this, see 22.4.2 Fixing stop-cal Problems.

Once you are sure all Calendar Server processes are stopped, use the start-cal command to start all services. For example:

cal-svr-base/SUNWics5/cal/sbin/start-cal

22.4.2 Fixing stop-cal Problems

This section contains some conceptual information and instructions for fixing stop-cal problems.

There are two separate issues to consider when Calendar Server shuts down:

To Stop Child Processes

After issuing stop-cal, it is possible that some child processes were not stopped. For example, stop-cal might stop the cshttpd parent process but not any cshttpd child processes. In this situation, you must stop the remaining Calendar Server processes individually, using the following procedure:

Determine the process ID (PID) of the remaining Calendar Server processes by entering a ps command for each service:

ps -elf | grep cs-process

where cs-process is enpd, csnotifyd, csdwpd, csadmind, or cshttpd. For example:

ps -elf | grep cshttpd

Using the PID of each process that is still running, enter a kill -15 command to kill the process. For example: kill -15 9875

Enter each ps command again to make sure that all Calendar Server processes are stopped.
If a Calendar Server process is still running, enter a kill -9 command to kill it. For example: kill -9 9875
Note –
On Linux systems with Calendar Server running, if you search for calendar processes using the ps command, the results might appear confusing. In Linux, the ps command returns the list of threads running rather than the list of processes. There is no known workaround to display only the processes.

To Recover After an Improper Shutdown

If Calendar Server was not properly shutdown, perform the following steps:

Perform the steps in the previous procedure, 22.4.2 Fixing stop-cal Problems.

Manually delete all files in the LDAP data cache database directory.

These left over files could cause database corruptions. To delete the files:
1. Change to the LDAP data cache directory.
  
  The default is /opt/SUNWics5/csdb/ldap_cache, but use the directory pointed to by the local.ldap.cache.homedir.path parameter in the ics.conf file.
2. Remove all files in the directory.
  
  For example: rm *.*
3. Check to make sure all files were removed.
  
  For example: ls

Restart Calendar Server.

cal-svr-base/SUNWics5/cal/sbin/start-cal

For instructions on how to configure LDAP data caching, see 4.8 Configuring LDAP for Calendar Server Version 6.3. For more information about the LDAP data cache, see theSun Java Communications Suite 5 Deployment Planning Guide.

22.4.3 Can't Connect to Back-End Server

Ping the back-end server to see if it is responding.

If it is not responding, determine why it is failing. When it is functioning again, proceed to the next step in this task.
Clear the CLD cache. See 12.5 Clearing the CLD Cache in Calendar Server Version 6.3.

If you are using the CLD cache option and you have updated a server name for an ics.conf parameter, you should clear the CLD cache to remove the server names. An out-of-date entry in the CLD cache can prevent a front-end server from establishing a connection to the correct back-end server or cause Calendar Server not to find a calendar after it have been moved.
Stop the server with the stop-cal command.
Restart Calendar Server using start-cal.

22.4.4 Can’t Find Calendar

If you are using the CLD cache option and you have moved one or more calendars to different back-end servers (or changed the name of the back-end server), might not be able to see the calendars on the new server.

If this happens, perform the following steps:

Clear the CLD cache. See 12.5 Clearing the CLD Cache in Calendar Server Version 6.3.

The CLD cache will be out of date if you moved one or more calendars to different back-end servers. To refresh it, you need to clear the cache so it will be rebuilt.
If that fails, confirm that you followed the correct procedure for moving calendar. This information can be found at:

15.6 Managing User Calendars.

Then, clear the cache.

22.4.5 Can't Create Calendar on Back-End Machine

If you try to create a calendar on a designated back-end machine, and you get the following error message: Invalid DWP Host Server, it means one of two things. Either your server is not configured properly, or the calendar owner has already been assigned to a different back-end server.

This section contains information on how to fix these two problems:

22.4.5.1 Back-End Machine Not Configured Properly

Look at the ics.conf file for the back-end server in question.

Verify that the following settings exist:

service.dwp.enable = "yes"
caldb.cld.type = "directory"
local.hostname = "back-end hostname"

22.4.5.2 Calendar Owner Assigned to a Different Back-End Machine

Look at the user's LDAP entry and see if there is an icsDWPHost attribute present. The value of icsDWPHost must match the back—end server name on which you are attempting to create the calendar. You can not create a calendar for this user on a different back-end server.

22.4.6 Get “Unauthorized” When Trying to Log In Using Proxy Authentication

This section contains suggestions for possible reasons for failure. Follow the suggested steps and retry the login.

Perform one or more of the following steps to fix this error:
- Verify that service.http.allowadminproxy is set to “yes”.
- Verify that the admin-user has Calendar Server administrator privileges.
- Verify that the admin-password is correct.
- Verify that the calendar-user is a valid Calendar Server user.
Retry the log in.

22.4.7 Troubleshooting Searches that Don’t Complete Properly

This section contains conceptual information and instructions for troubleshooting searches that don't complete properly.

The nsslapd-sizelimit and nsLookthroughLimit attributes in your LDAP Directory Server configuration must be large enough so that searches complete properly. If nsSizeLimit is not large enough, truncation can occur and no results will be displayed. If nsLookthroughLimit is not large enough the search may not complete.

This section covers the following topics:

To Determine if Limit Attributes Have Appropriate Values

To determine if these attributes are set to appropriate values, try the following command:

ldapsearch -b "base" "(&(icscalendarowned=*user*)(objectclass=icsCalendarUser))"

where base is the LDAP base DN of the directory server where the user and resource data for Calendar Server is located, and user is the value that an end user can enter in the search dialog in the user interface.

If the LDAP server returns an error, the nsSizeLimit or the nsLookthroughLimit parameters might not be large enough.

To Set the Limit Attributes to Appropriate Values

The DN for these attributes is:

dn: cn=config,cn=ldbm databases,cn=plug ins,cn=config

Use ldapmodify to dynamically set the value of nsLookthroughLimit.

You do not have to stop and restart Directory Server to change this attribute.

The default value is 5000. You might want to increase this value if searches are not reporting results. However, this could slow down the LDAP server.

It is possible to set the limit to -1, which causes no limit to be used. However, do this with caution as it could conceivably cause the system to hang.

If you want to set nsslapd-sizelimit to a higher value, you must perform the following steps:
1. Stop the Directory Server.
2. Edit the dse.ldif file.
3. Restart the Directory Server.
  
  Note –
  For information on how to use ldapmodify and edit the dse.ldif file, see Directory Server documentation found at:
  
  http://docs.sun.com/coll/1316.1

22.5 Dealing with Calendar Server Database Issues

This section covers various issues involving the Calendar Server (Berkeley Database) databases:

This section contains the following topics:

22.5.1 Finding Berkeley Database Tools

Many of the troubleshooting steps you will want to take require having access to the Berkeley database utility programs. While a version of these utility programs is available in the Calendar Server bundle, they are not supported. You might want to obtain more information directly from Sleepycat Software (http://www.oracle.com/database/berkeley-db/index.html.

This section covers the following topics:

22.5.1.1 To Access the Berkeley Database Utilities

Set and export the LD_LIBRARY_PATH environment variable to reflect the following directory:

cal-svr-base/SUNWics5/cal/tools/unsupported/bin/

22.5.1.2 List of Available Tools

The following table lists some of the commonly used Berkeley database tools (utility programs).

Berkeley Database Tools	Description
`db_archive`	Writes the path names of log files that are no longer in use to the standard output, one pathname per line.
`db_checkpoint`	A daemon process that monitors the database log and periodically calls the checkpoint routine to checkpoint it.
`db_deadlock`	Traverses the database environment lock region and aborts a lock request each time it detects a deadlock or a lock request that has timed out.
`db_dump`	Writes the specified file to standard output in a flat-text format understood by the `db_load` utility.
`db_load`	Reads from the standard input and loads it into the database file specified. If the file does not already exist it creates it.
`db_printlog`	Debugging utility that dumps log files in human-readable format.
`db_recover`	Restores the database to a consistent state after an unexpected application, database, or system failure.
`db_stat`	Displays statistics for the database environment.
`db_verify`	Verifies the structure of one or more files and the databases they contain.

Detecting and Fixing Database Deadlocks

If the Berkeley database is in a deadlock state, you must reset the database. It is important to detect this condition as early as possible.

To enable the system to periodically check the databases to detect a deadlock state and inform the Administrator:

Stop Calendar Server services by issuing the stop-cal command.

Change to the /etc/opt/SUNWics5/cal/config directory.

Save your old ics.conf file by copying and renaming it.

Edit the ics.conf, if necessary, to have the following value:

local.caldb.deadlock.autodetect=”yes”

Note –
When this parameter is set to “yes”, the db_deadlock daemon is launched that will monitor the lock region.

22.5.2 Detecting 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:

22.5.2.1 Database Corruption Basics

No one can guarantee corruption free databases. But you can minimize data loss and operational downtime. Closely monitoring the database and calendar server is key to detecting corruption early. Frequent and complete backups are the key to recovering from corruption once it is found.

There are two levels of corruption possible in a calendar database:

Application level–Offending entries in one of more database files prevent the server from running when they are operated upon.
Database level–Corruptions in the Berkeley database pages cause various problems. One common symptom is looping while running csdb check. Another common symptom is an error message like the following:
```
“illegal page type or format”, 
or “page 97895 doesn’t exist, create flag not set.”
```

22.5.2.2 Monitoring Log Files

Monitor the Calendar Server log files, including the alarm logs, for any error messages that might indicate database corruption.

You should inspect the log files on a regular basis for ALERT, CRITICAL, ERROR, and WARNING level errors and, if found, examine the events for possible problems with the operation of Calendar Server. The NOTICE and INFORMATION level log events are generated during normal operation of Calendar Server and are provided to help you monitor server activity.

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.

Note –

When requesting technical support for Calendar Server, you might be asked to provide the log files for help in resolving problems.

To Check for Calendar Database Corruption

Use the check command to scan for corruptions in the calendar database, including calendar properties (calprops) and events and todos (tasks). If the check command finds an inconsistency that cannot be resolved, it reports the situation in its output.

The check command does not check for corruption in the alarm or group scheduling engine (GSE) databases.

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.*) or log (log.*) files.

Change to the cal-svr-base/SUNWics5/cal/sbin directory.

For example, on Solaris Operating Systems for the default directory, enter:

cd /opt/SUNWics5/cal/sbin

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

./csdb check dbdir /tmp/check.out

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.

(See 22.5.6 Rebuilding a Corrupted Calendar Database.)

22.5.3 Dealing with Transaction Log Files Suddenly Very Large and Numerous

It is possible that your automatic purge configuration settings do not properly account for the client user interface your end users prefer. The sudden appearance of large numbers of large transaction log files can be simply the result of a long delay in purging Delete log records. If this delay is purposefully done to accommodate users of the Connector for Microsoft Outlook or the Sync Tool, then the appearance of the large and numerous transaction log files is to be expected. No further action is required. Eventually the system will catch up. However, if your end users are using the Communications Express client, returning the automatic purge settings to their defaults should fix the problem.

22.5.4 Preventing Service Interruptions When Your Database is Corrupted (Read-only Mode)

This sections covers how to keep your corrupted database accessible while you are in recovery mode and includes the following topics:

22.5.4.1 Using Read-only Mode

If you are encountering database corruption, one way to prevent service interruptions is to put your database in read-only mode. This mode allows end users to read database entries, but does not allow additions, modifications, or deletions. If an end user attempts to add, modify or delete any calendar data, the system gives an error message. In addition, administrator tools that add, modify or delete calendar events and todos will not work while the database is in read-only mode.

Note –

If the database is corrupted to the point that it can’t be read, you must interrupt service long enough to restore a backup. The quickest way to restore a backup is to have a good hot backup. See 22.5.8.1 Before You Restore.

To Put a Database in Read-only Mode

Stop Calendar Server services by issuing the stop-cal command.

At a command line, change to the directory where the ics.conf is located:

cd /etc/opt/SUNWics5/config

Specify read-only mode for the calendar, by setting the parameter as follows:

caldb.berkeleydb.readonly=”yes”

Restart Calendar Server by issuing the start-cal command.

cal-svr-base/SUNWics5/cal/sbin/start-cal

You must restart the services in order for the ics.conf changes to take effect.

22.5.5 Handling Common Database Failures

This section covers a few of the common database failures and includes some suggested remedies. It contains the following topics:

`csadmind` Won’t Start or Crashes During Startup

Since csadmind is the service that handles both the group scheduling engine (GSE) and the alarm dispatch engine, this could have been caused by offending entries in the GSE queue or the alarm queue.

Remedies:

If csadmind is not running, issue the stop-cal command immediately.

Leaving calendar server running could cause transaction logs to accumulate, which could further corrupt the database, and could take much longer to reconcile the transaction log files to the database.

Verify that all Calendar Server processes are stopped.

For instructions on how to verify that all processes are stopped, see To Stop Child Processes.

Try restarting csadmind again by issuing the start-cal -csadmind command.

If it starts successfully, make sure the two queues are functioning by performing the following steps:
1. Checking the GSE queue using csschedule.
2. Checking the alarm queue using dbrig.
  
  For instructions on running csschedule and dbrig, see Appendix D, Calendar Server Command-Line Utilities Reference.

If csadmind crashes with a dump, analyze the pstack.

If you notice any GSE related functions in the trace (they will have the letters GSE in them), look at the first entry in the GSE queue and the referenced entry in the events database. Most of the time, the event referred to in the GSE entry is the offending entry. To fix this problem:
1. Remove the GSE entry using csschedule.
2. Remove the offending event from the database using cscomponents.
  
  For instructions on running csschedule and cscomponents, see Appendix D, Calendar Server Command-Line Utilities Reference.

If the entries are not corrupted, then it could be a special case that the calendar server could not handle.

Take the following steps:
1. Take a calendar environment snapshot of the corrupted database, and contact customer support.
  
  To create an environmental backup:
  1. Use the db_checkpoint utility found at:
    
    cal-svr-base/SUNWics5/cal/tools/unsupported/bin/db_checkpoint
  2. Run db_archive -s.
    
    Use the -s option to identify all the database files and copy them to a removable medium, such as CD, or DVD, or tape.
  3. Run db_archive -l.
    
    Use the -l option to identify all the log files and copy unapplied log files to a removable-medium device.
2. To avoid service interruptions, place your calendar database into a read-only state temporarily, and revert to a hot backup copy.
  - Placing your calendar database into a read-only state temporarily prevents any add, modify or delete transactions from taking place. End users will get an error message when they try to add, modify or delete any calendar data. Administrator tools that add, modify or delete calendar events and todos also will not work while the database is in read-only mode.
    
    To put your calendar database in read-only mode, edit the ics.conf file and set the following parameter to “yes”, as shown:
    
    caldb.berkeleydb.readonly=”yes”
  - Revert to a hot backup copy, using the instructions found in 22.5.8 Restoring an Automatic Backup Copy.
    
    With csstored configured and enabled, a hot backup is available that should be within minutes of being uptodate. You should always verify your hot backup copy to make sure it is not corrupt also. (Run db_verify.)

If all else fails, perform the dump and reload procedure to see if it can salvage the database.

This procedure is described in 22.5.7 Using the Dump and Load Procedure to Recover a Calendar Database.

Services Hung, and End Users Can’t Connect–Orphaned Locks

This condition may be caused by a control thread, which holds a Berkeley DB database page lock, quitting without releasing the lock. To confirm the problem, run pstack on cshttpd processes and csadmind. (pstack is a standard UNIX utility found at: /usr/bin/pstack) It should show threads that are waiting to acquire a lock.

To fix the problem, restart Calendar Server, as follows:

Change to the directory where start-cal resides.

cd cal-svr-base/SUNWics5/cal/sbin

Issue the start-cal command.

./start-cal

`csdb` rebuild Never Finishes–Database Looping

Database looping is usually caused by corruption in the database files. Since it is a database corruption, it can be unrecoverable. There are several options:

Revert to the hot backup.

If the corruption occurred recently, you can use one of your hot backups.

Use your catastrophe archival recovery process.

For a suggested process, see 22.5.8 Restoring an Automatic Backup Copy.

Use the dump and reload procedure, 22.5.7 Using the Dump and Load Procedure to Recover a Calendar Database.

22.5.6 Rebuilding a Corrupted Calendar Database

This section describes how to use the csdb rebuild command and contains the following topics:

22.5.6.1 `rebuild` Overview

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/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 databases, placing them into the /tmp/db directory.

Copy the database (.db) files and the log (log.*) files. You don’t need to copy any share (__db.*) files.

Change to the cal-svr-base/SUNWics5/cal/sbin directory.

For example, on Solaris Operating Systems, for the default directory, 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 path, rebuild uses 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/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.*) or log (log.*) files from the corrupted database, move them to another directory.

Restart Calendar Server.

22.5.6.2 Sample Rebuild Output

The following example shows the command and the output that it generated:

# ./csdb -g rebuild
Building calprops based on component information.
Please be patient, this may take a while...
Scanning events database...
512 events scanned
Scanning todos database...
34 todos scanned
Scanning events database...
512 events scanned
Scanning todos database...
34 todos scanned
Scanning deletelog database...
15 deletelog entries scanned
Scanning gse database...
21 gse entries scanned
Scanning recurring database...
12 recurring entries scanned
Successful components db scan
Calendar database has been rebuilt
Building components based on calprops information.
Please be patient, this may take a while...
Scanning calprops database to uncover events...
25 calendars scanned
Scanning calprops database to uncover todos...
25 calendars scanned
Successful calprops db scan
Calendar database has been rebuilt

Note –

The preceding sample output shows the events and the todos databases scanned twice each. This is not an error. It scans the first time to verify the information in the calendar properties database and then scans again to make sure calendar properties database is accessible.

22.5.7 Using the Dump and Load Procedure to Recover a Calendar Database

This sections contains the following topics:

22.5.7.1 Dump and Load Overview

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:

cal-svr-base/SUNWics5/cal/tools/unsupported/bin

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:

http://www.sleepycat.com/docs/utility/index.html

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 the last good hot backup or archive backup of your database.

Note –

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

For the most up to date version of cs5migrate, call Sun technical support.

To Perform the Dump and Load Procedure

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^TM software, or Legato Networker®.

For more information refer to Chapter 17, 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

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

Repeat the previous two steps for the other corrupted database files.

That is, run db_dump for the other corrupted database files.

Rebuild the recovered database files using the csdb rebuild command, as described in 22.5.6 Rebuilding a Corrupted 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, 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. In the meantime, you might need to revert to the last good backup of your database.

22.5.8 Restoring an Automatic Backup Copy

If you have used the automatic backup feature described in Chapter 9, Configuring Automatic Backups (csstored), you can use the hot backup copy when your live database is corrupted.

This sections covers how to restore the two different automatic backups:

22.5.8.1 Before You Restore

Before you restore a backup, be sure that you have:

Tried to diagnose which transaction caused the corruption of the live database.
Removed or corrected the corrupting transaction so the new archive will not be corrupted.
Preserved the corrupted database by copying it to another directory or removable media. This is necessary should you need to contact technical support.

To Restore a Hot Backup

Hot backups should be your first choice of backup when your live database is corrupted. To restore a hot backup, follow these steps:

Identify any log files that were unapplied or open for writing in the corrupted live database directory.

Close the log that was open for writing. It contains the most recent transactions.

Create a new (recovery) directory.

Copy the current hot backup copy into the new recovery database directory.

Copy the log.* files from your corrupted live database directory into your new recovery database directory.

If you are keeping an archive copy of the database, copy the logs that had not been applied to the live database into the archive directory, so your archive backup copy will be complete.

Run db_recover with the -c -h options specified against the new recovery database.

For example, if your new recovery directory is called recoverydb, then the command would be as follows:

db_recover -c -h recoverydb

Leave the log.* files in the new recovery directory.

The db_recover program applied the log files to the new recovery databases, but starting with version 42, the Berkeley DB expects them to remain.

Run db_verify against the database files in the new recovery directory. To run db_verify:

Stop the Calendar Server using these commands.

cd /opt/SUNWics5/cal/sbin

./stop-cal

Create another copy of the Calendar Server database (csdb) using this command.

cp -Rp /var/opt/SUNWics5/csdb /var/opt/SUNWics5/csdb.db_verify

Run db_verify on the copy of csdb.

Note –

Do not run db_verify on the original csdb.

LD_LIBRARY_PATH=/opt/SUNWics5/cal/lib
export LD_LIBRARY_PATH
cd /opt/SUNWics5/cal/tools/unsupported/bin
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50alarms.db
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50calprops.db
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50events.db
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50gse.db
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50journals.db
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50recurring.db
./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50todos.db
./db_verify -o -h /var/opt/SUNWics5/csdb.db_verify ics50deletelog.db

Note –

Run db_verify with -o option for ics50deletelog.db.

If db_verify completes running successfully, you will not get any error messages. If the database file gets corrupted, it throws error messages. For example:

./db_verify -h /var/opt/SUNWics5/csdb.db_verify ics50todos.db
db_verify:Page 612: last item on page sorted greater than parent entry
db_verify: Page 612: incorrect next_pgno 885 found in leaf chain (should be 501)
db_verify: Page 0: page 501 encountered a second time on free list
db_verify: DB->verify: ics50todos.db: DB_VERIFY_BAD: Database verification failed

Run csdb -v list against the new recovery directory.

If the new recovery directory passed all three preceding recovery steps, replace the old corrupted live database with the new recovery database.

Copy the new live database into your hot backup directory to function as the new snapshot.

All new logs will be applied to this copy until the next regular snapshot is taken.

Start Calendar Server.

If the new recovery directory failed any of the steps, identify an uncorrupted older hot backup as follows:
1. Working backward through your hot backups, find the most recent copy that is not corrupted by running db_verify and csdb -v list on each in turn.
2. The first hot backup copy that passes can be restored to your live database directory.
  
  Replace the corrupted live database with the clean hot backup, as described in To Restore a Hot Backup. (Be sure to read 22.5.8.1 Before You Restore first.)
3. If none of your hot backups work and you do not have archive backups to try, call technical support. If you do have archive backups, follow the procedure that followsTo Restore an Archive Backup. (See also, 22.5.8.1 Before You Restore.)

To Restore an Archive Backup

If you do not have an uncorrupted hot backup, but have archive backups and their transaction logs, you can restore the most current uncorrupted version of the archived database by performing the following steps:

Identify any log files that were unapplied or open for writing in the corrupted live database directory.

Close the log that was open for writing. It contains the most recent transactions.

Create a new (recovery) directory.

Copy the most recent archive copy and its log files into the new recovery database directory.

Copy any unapplied log.* files from your corrupted live database directory into your new recovery database directory.

Run db_recover with the -c-h options specified against the new recovery database.

For example, if your new recovery directory is called recoverydb, then the command would be as follows:

db_recover -c -h recoverydb

Leave the log.* files in the new recovery directory.

The db_recover program applied the log files to the new recovery databases, but starting with version 4.2, Berkeley DB expects the log files to still be there.

Run db_verify against the database files in the new recovery directory.

Steps in the To Restore a Hot Backup procedure, explains how to run db_verify.

Run csdb -v list against the new recovery directory.

If the new recovery directory passed all three preceding recovery steps, replace the old corrupted live database with the new recovery database.

Copy the new live database into your hot backup directory to function as the new snapshot.

Start Calendar Server.

If the new recovery directory failed any of the steps, identify an uncorrupted older archive backup as follows:
1. Working backward through your archive backup copies, find the most recent copy that is not corrupted by running the three recovery programs against each of them in turn: db_recover -c-h, db_verify, and csdb -v list.
2. The first archive copy that passes can be restored to your live database directory.
  
  Replace the corrupted live database with the clean archive backup, as shown in To Restore an Archive Backup.
3. If none of your archive backups work, call technical support.

22.5.9 Repairing Custom Backup Scripts

This section includes the following topics:

22.5.9.1 Berkeley Tools Now Compiled with a Dynamic Library

If you have created a custom backup script using the Berkeley database tools, such as db_recover, you may find that it will no longer work after upgrading to Calendar Server. The reason for this is that the earlier versions of Calendar Server compiled the tools with a static library. The tools are now compiled with a dynamic library, libdb-4.2.so.

22.5.9.2 To Repair a Custom Backup Script

To use the new dynamic library with your existing custom scripts, set the following global variable as shown:

LD_LIBRARY_PATH=libdb-4.2.so

Part IV Calendar Server 6.3 Administration

Chapter 12 Server Administration for a Calendar Server 6.3 Deployment

12.1 Starting and Stopping Calendar Server 6.3 Processes

12.1.1 About Calendar Server 6.3 Commands: start-cal and stop-cal

To Start Calendar Server 6.3 Services with start-cal

To Stop Calendar Server with stop-cal

12.2 Enabling or Disabling Automatic Backups in Calendar Server Version 6.3

To Enable Hot Backups in Calendar Server Version 6.3

To Enable Archive Backups in Calendar Server Version 6.3

To Disable Hot Backups in Calendar Server Version 6.3

To Disable Archive Backups in Calendar Server Version 6.3

12.3 Managing the Group Scheduling Engine Queue for Calendar Server Version 6.3

12.3.1 About GSE for Calendar Server Version 6.3

12.3.2 About the Calendar Server 6.3 GSE Queue

12.3.3 Listing Entries in the Calendar Server 6.3 GSE Queue

12.3.4 Deleting Entries in the GSE Queue in Calendar Server Version 6.3

12.4 Monitoring Calendar Server 6.3 Processes

12.5 Clearing the CLD Cache in Calendar Server Version 6.3

12.5.1 Why Clear the Calendar Server 6.3 CLD Cache?

To Clear the CLD Cache

12.6 Changing a Server Name

12.7 Configuring Anonymous Access for Calendar Server Users

To Enable Anonymous Access

To Disable Anonymous Users from Writing to Public Calendars

12.8 Enabling Proxy Administrator Logins

To Enable Proxy Authentication without Communications Express

To Verify Proxy Authentication is Working

12.9 Refreshing the Calendar Server Configuration

Chapter 13 Administering Calendar Server Domains

13.1 Choosing the Correct User Management Tool

13.2 Creating New Calendar Server Domains

13.2.1 Overview of Creating Calendar Server Domains

13.2.2 To Add a Domain in Schema Version 2 Mode

13.2.3 To Add a Domain in Schema Version 1 Mode

13.3 Enabling Cross Domain Searches

13.3.1 Adding Names of Domains Allowed to Search This Domain

13.3.1.1 To Allow Specific Domains to Search This Domain

13.3.1.2 To Allow All External Domains to Search This Domain

13.3.2 Adding Names of Domains to be Searched by This Domain

Chapter 14 Administering Users, Groups, and Resources

14.1 Creating Calendar User LDAP Entries

14.1.1 To Create New Calendar Users in Schema Version 2 Mode

14.1.2 To Create New Calendar Users For Schema Version 1 Mode

14.2 Creating Calendar Group LDAP Entries

14.2.1 To Create New Calendar Groups for Schema Version 2 Mode

14.2.2 To Create New Calendar Groups for Schema Version 1 Mode

14.3 Creating Calendar Resource LDAP Entries

14.3.1 To Create New Calendar Resources for Schema Version 2 Mode

14.3.2 To Create New Calendar Resources for Schema Version 1

14.4 Adding the mail Attribute to User, Group and Resource LDAP Entries

14.4.1 Overview of Adding Mail Service to Calendar Server LDAP entries

14.4.2 To Check if the mail Attribute Exists in the LDAP Entry

14.4.3 To Add the Mail Attribute to Existing User, Group and Resource LDAP Entries for Calendar Server Version 6.3

14.5 Administering Existing Users

14.5.1 Displaying Calendar User Information

14.5.1.1 To Display All Users Enabled for Calendaring

14.5.1.2 To Display a Particular User's Calendar Attributes

14.5.2 Disabling a Calendar User

14.5.2.1 To Disable a User with Delegated Administrator Console

14.5.2.2 To Disable a User with Delegated Administrator Utility (commadmin user delete)

14.5.2.3 To Disable a User with Calendar Server Utilities (csuser disable)

14.5.2.4 To Remove Calendar Service from a User with Calendar Server Utilities

14.5.3 Enabling a Calendar User

14.5.3.1 To Enable a User with Delegated Administrator Console

14.5.3.2 To Enable a User with Delegated Administrator Utility

14.5.3.3 To Re-Enable a User with Calendar Server Utilities

14.5.4 Adding Calendar Service to a User

14.5.4.1 To Add Calendar Service to a User with Delegated Administrator Console

14.5.4.2 To Add Calendar Service to a User with Delegated Administrator (commadmin user create)

14.5.4.3 To Add Calendar Service with Calendar Server Utilities

14.5.5 Deleting Calendar Service from a User LDAP Entry

14.5.6 Setting Up Email Aliases for a Calendar User

To Set Up Email Aliases with Delegated Administrator Console

See Also

14.5.6.1 To Set Up Email Aliases with Delegated Administrator Utility

14.5.6.2 To Set Up Email Aliases with Calendar Server Utility csattribute

14.5.7 Verifying that a User has Calendar Service

14.5.7.1 To Check if a User has Calendar Service with Delegated Administrator Console

14.5.7.2 To Check if a User has Calendar Service with Delegated Administrator Utility

14.5.7.3 To Check if a User has Calendar Service with Calendar Server Utility csuser

14.5.2.2 To Disable a User with Delegated Administrator Utility (`commadmin user delete`)

14.5.2.3 To Disable a User with Calendar Server Utilities (`csuser disable`)

14.5.4.2 To Add Calendar Service to a User with Delegated Administrator (`commadmin user create`)

14.5.7.3 To Check if a User has Calendar Service with Calendar Server Utility `csuser`

To Retrieve Resource Information Using `csresource`

15.5.1 Creating a User Calendar with the `cscal`Utility