Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Calendar Server 6 2005Q1 Administration Guide 

Chapter 15
Administering Calendars

This chapter contains the following topics, which describe how to use Calendar Server command-line utilities to create and manage calendars:


Calendar Administration Overview

This section contains the following topics:

Calendar Types

There are two basic calendar types. This and other information about the two types follows:

Schema 1 Tools for Calendars

There are three utilities to use when you are in Schema 1 mode:

To run csuser, 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.

See the command-line utilities reference in Appendix D, "Calendar Server Command-Line Utilities Reference".

Schema 2 Tools for Calendars

Use cscal to create and administer both user and resource calendars when you are in Schema 2 mode.


Note

The commadmin utility has no commands for calendar administration.


To run cscal, 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.

See the command-line utilities reference in Appendix D, "Calendar Server Command-Line Utilities Reference".


Creating Calendar Unique Identifiers (calids)

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:

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:

Calendar ID Creation Rules

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

Examples of proper calendar IDs are:
jsmith
jsmith:private_calendar
jsmith@calendar.sesta.com:new-cal

Converting Non-Hosted Calids to Hosted Domain Format Calids

If you have calids that were created before you had hosted domains, and you now want to convert the non-hosted domain calids to hosted domain calids, there is a utility, csvdmig, that can be used to add the domain part to your existing calids. See csvdmig for instructions on how to use the utility.


Automatic Creation of User Calendars

This section covers the following topics:

Automatic Calendar Creation Feature

Calendar Server automatically creates a default calendar for a user the first time the user logs in. This feature is called auto-provisioning. Auto-provisioning is enabled by default. However, auto-provisioning is available for user calendars only; resource calendars must be explicitly created.

Calendar Server creates the calendar ID (calid) for this new default calendar from the user ID, unless a calendar by that name already exists.

For example, if John Smith, with a user ID of jsmith, logs into Calendar Server for the first time, Calendar Server automatically creates a default calendar with jsmith as the calid. Each subsequent calendar John Smith creates has a calid with jsmith: prepended to the calendar name. For example, if John Smith later creates a new calendar named meetings, the calid for the new calendar (in a non-hosted environment) is jsmith:meetings.


Note

Calendar Server returns the “Calendar not found” error when a user without a default calendar is specified as an attendee.


To Enable Auto-Provisioning

Auto-provisioning is enabled by default. However, if you need to turn it on again after disabling it, perform the steps that follow:

  1. Log in as an administrator with permission to change the configuration.
  2. Change to the /etc/opt/SUNWics5/cal/config directory.
  3. Save your old ics.conf file by copying and renaming it.
  4. Edit one or more of the following parameters in the Calendar Server configuration file, ics.conf, as shown in Table 15-1:

    Table 15-1  ics.conf Parameter Used to Configure Auto-Provisioning

    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. Auto-provisioning is enabled by default.

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

  5. Verify that the user’s LDAP entry is enabled for calendar.
  6. The entry must contain the icsCalendarUser object class. Add the class to the user’s LDAP entry if it is not there.

  7. If your site is using hosted domains, the user’s domain must also be calendar enabled before auto-provisioning will work. The domain entry must contain the icsCalendarDomain object class.
  8. Save the file.
  9. Restart Calendar Server.
  10. cal_svr_base/SUNWics5/cal/sbin/start-cal

To Disable Auto-provisioning

  1. Log in as an administrator with permission to change the configuration.
  2. Change to the /etc/opt/SUNWics5/cal/config directory.
  3. Save your old ics.conf file by copying and renaming it.
  4. Edit one or more of the following parameters in the Calendar Server configuration file, ics.conf, as shown in Table 15-1:

    Table 15-2  ics.conf Parameters Used to Disable Auto-Provisioning 

    Parameters

    Description and Default Value

    local.autoprovision

    Setting the parameter to “no” disables auto-provisioning of user calendars.

  5. Save the file.
  6. Restart Calendar Server.
  7. cal_svr_base/SUNWics5/cal/sbin/start-cal


    Note

    If auto-provisioning is disabled, calendars must be explicitly created for users before they can successfully log in.



Calendar Access Control

Sun Java™ 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:

Configuration Parameters for Access Control

Table 15-3 describes the configuration parameters in the ics.conf file that Calendar Server uses for access control. For more information see Appendix E, "Calendar Server Configuration Parameters".”

Table 15-3  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"

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

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.

Command-Line Utilities for Access Control

Table 15-4 describes the Calendar Server command-line utilities that allow you to set or modify ACLs for access control:

Table 15-4  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

If you are creating resource calendars with csresource (you are in Schema 1 mode), use the csresource utility with the -a option to set ACLs for resource calendars.

commadmin user

csuser

Use the Schema 2 commadmin utility to change the default ACL used when a user creates a calendar.

Use the Schema 1 csuser utility with the -a option to change the default ACL used when a user creates a calendar.


Creating Calendars

This section contains the following topics:

Creating a User Calendar Using cscal

To create a new calendar, use the cscal utility create command. The user or resource entry must already exist in the LDAP directory. Refer to Chapter 14, "Administering Users and Resources" for information about 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 6, "Configuring Calendar Database Distribution Across Multiple Machines".

For example, to create a new calendar with the calendar ID (calid) jsmith:

cscal -o jsmith -n JohnSmithCalendar create jsmith

where:

To create a calendar with the viewable name Hobbies that is owned by John Smith and uses the default access control settings for group scheduling:

cscal -n Hobbies -o jsmith create Personal

where:

The following example creates a new calendar 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

where:

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

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

Preparing to Create Resource Calendars

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.

Two configuration parameters in the ics.conf file apply to resource calendars:

To change the default values for these parameters (shown in Table 15-5), 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. If you want to change values for existing resource calendars, you need to use the cscal utility, or the commadmin resource modify command. The csresource utility does not have a modify command.

For more information, see Appendix E, "Calendar Server Configuration Parameters".

Table 15-5  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 double-booking. Double-booking allows a resource calendar to have more than one event scheduled for the same time.

The default is"no" — Do not allow double-booking.

To allow double-booking for a resource calendar, use the -k option when you create the calendar using the csresource utility create command.

Creating a Resource Calendar

Calendar Server does not automatically create resource calendars. For every resource required at your site, you must use the csresource utility create command to create the resource LDAP entry, and create its calendar in the calendar database. Several considerations for creating resource calendars are:

For example, to create a resource calendar with the calendar ID aud100, viewable name Auditorium (LDAP cn attribute), and the default settings shown in Table 15-5:

csresource -c aud100 create Auditorium

The following command performs the same action as the previous example, 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 as another owner:

csresource -c aud100 -k yes -o bkamdar -y jsmith create Auditorium

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


Note

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



Managing User Calendars

After your user calendars are created, use the cscal utility to perform the following administrative tasks:

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.

For example, 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

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.


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


The cscal utility lets you delete a single calendar or multiple calendars.

For example, to delete a specific calendar with the calendar ID jsmith:meetings:

cscal delete jsmith:meetings

To delete all calendars whose primary owner is jsmith:

cscal -o jsmith delete

To Remove Calendars of Deleted Users

If you have deleted one or more users with csuser delete, or commadmin user delete, calendars owned by that user might still be present in the database.

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

To Remove All Calendars of a User Deleted with csuser

  1. Run cscal list to find all of the calendars for the deleted owner’s uid.
  2. cscal -o owner list

  3. Use cscal to remove all the calendars for this owner.
  4. cscal -o owner delete

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

This utility removes all calendars for any users marked as deleted, but not yet purged, within the specified time span. For example, to remove all the calendars for user’s 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


Note

If the user has already been purged from the LDAP, then you must use the other procedure To Remove All Calendars of a User Deleted with csuser.


To Disable or Enable 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:meetings:

cscal disable jsmith:meetings

To enable a calendar to allow users to access the calendar, use the cscal utility enable command. For example, to enable calendar jsmith:meetings using the default configuration settings:

cscal enable jsmith:meetings

To enable the calendar jsmith:meetings but not allow double booking:

cscal -k no enable jsmith:meetings

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 as another owner:

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

where:

To Remove Properties From a Calendar

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

For example, to remove a description from jsmith:meetings:

cscal -d "" modify jsmith:meetings

To remove all categories from jsmith:meetings:

cscal -g "" modify jsmith:meetings

To remove “other owners” from jsmith:meetings:

cscal -y "" modify jsmith:meetings

To Recover a “Lost” Calendar

If a user’s default calendar does not appear in the Calendar Express View tab or Calendars tab but still exists in the database, you can recover the calendar by updating the following attributes in the user’s LDAP entry:

where default_calid is the user’s default calendar ID (calid).

You can use the ldapmodify Directory Server utility, the csuser reset command, or commadmin user modify. For Schema 1, you can 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:

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

  3. On the original server, export each of the user’s calendars from the calendar database to a file using the csexport utility. For example:
  4. csexport -c bkamdar calendar bkamdar.ics

  5. Copy the exported calendar (*.ics) files from the original server to the new server.
  6. On the new server, for each of the calendars exported, import the calendar from the file to the calendar database using the csimport utility. For example:
  7. csimport -c bkamdar calendar bkamdar.ics

  8. On the LDAP directory server, update the calendar owner’s icsDWPHost LDAP attribute to point to the new back-end server using the 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:
  9. csattribute -a icsDWPHost delete bkamdar
    csattribute -a icsDWPHost=sesta.com add bkamdar

  10. On the new server, enable the calendar user using the csuser utility for a user calendar. For example:
  11. csuser enable bkamdar

  12. 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:
  13. cscal -v -o bkamdar list bkamdar
    ...
    csattribute -v list bkamdar

  14. On the original server, delete each calendar you just moved. For example:
  15. 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.


Managing Resource Calendars

After a resource calendar is created, administer it using the csresource utility. The following are procedures for administering resource calendars:

To Display Resource Calendars and Attributes

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

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

To Modify a Resource Calendar

To modify a resource calendar, use the cscal utility modify command (csresource does not have a modify command).

For example, to set the owner as tchang and add another owner named mwong to the resource calendar named Auditorium:

cscal -o tchang -y mwong modify aud100

In this example, the cscal utility requires the calid (aud100) rather than the calendar name (Auditorium).

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

To Delete a Resource Calendar

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

For example, to delete the Auditorium resource calendar:

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:

  1. On the original server, disable the calendar resource using the csresource utility. For example to disable the resource user ID and calid bkamdar:
  2. csresource disable bkamdar

  3. On the original server, export each of the resources calendars from the calendar database to a file using the csexport utility. For example:
  4. csexport -c bkamdar calendar bkamdar.ics

  5. Copy the exported calendar (*.ics) files from the original server to the new server.
  6. On the new server, for each calendar exported, import the calendar from the file to the calendar database using the csimport utility. For example:
  7. csimport -c bkamdar calendar bkamdar.ics

  8. On the LDAP directory server, update the calendar owner’s icsDWPHost LDAP attribute to point to the new back-end server using the 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:
  9. csattribute -a icsDWPHost delete bkamdar
    csattribute -a icsDWPHost=sesta.com add bkamdar

  10. On the new server, enable the calendar resource using the csresource utility. For example:
  11. csresource enable bkamdar

  12. 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:
  13. cscal -v -o bkamdar list bkamdar
    csattribute -v list bkamdar

  14. On the original server, delete each calendar you just moved. For example:
  15. 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.


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://hostname:port/[command.shtml]?calid=calid-1;calid-2; ... ;calid-n&view=viewname

Separate each calendar ID (calid) with a semicolon (;).

viewname can be overview, dayview, weekview, or monthview. (View can also be yearview, but it is not as useful.)

Note: If you are linking to only one calendar without the view (or another) option, omit command.shtml.

For example, to link to the default calendar for jsmith, enter:

http://calendar.sesta.com:8080/?calid=jsmith

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

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

However, to link to the default calendars for jsmith and tchang and display the calendars in day view, enter:

http://calendar.sesta.com:8080/command.shtml?calid=jsmith;tchang&
view=dayview


Importing and Exporting Calendar Data

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

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

Exporting Calendar Data

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

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

csexport -c jsmithcal calendar jsmith.ics

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

csexport -c jsmithcal calendar jsmith.xml

Importing Calendar Data

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

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

csimport -c jsmithcal calendar jsmith.ics

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

csimport -c jsmithcal calendar jsmith.xml



Previous      Contents      Index      Next     


Part No: 819-0024-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.