|
| |
| Sun Java System Calendar Server Administration Guide | |
Chapter 13
Administering CalendarsThis chapter contains the following topics, which describe how to use Calendar Server command-line utilities to provision and manage calendars:
Calendar Administration OverviewThis 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:
Schema 2 Tools for Calendars
Use cscal to create and administer both user and resource calendars when you are in Schema 2 mode.
To run cscal, you must log in as a user who has administrative rights to the system where Calendar Server is running. See also the non-commadmin command-line utilities reference 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:
With no hosted domains, the domain part is optional since there is no ambiguity about which domain the user is in.
When you have hosted 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 hosted domains (also called virtual domains), see Chapter 5, "Setting Up Hosted Domains" and Chapter 11, "Administering 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 auxilliary 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.
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-calConverting 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.
Auto-Provisioning of User CalendarsAuto-provisioning works for user calendars only; resource calendars must be explicitly created.
It is not necessary to explicitly create user calendars if auto-provisioning is enabled. With auto-provisioning, a default calendar is created the first time the user logs in.
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, that is, the ics.conf parameter local.autoprovision is set to “yes” by default.
- 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 hosted domains, the user’s domain must also be calendar enabled for auto-provisioning to work, that is, the domain entry must contain the icsCalendarDomain object class.
To disable auto-provisioning:
Calendar Access ControlSun™ ONE 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 13-1 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".”
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 (confidential)—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.
Command-Line Utilities for Access Control
Table 13-2 describes the Calendar Server command-line utilities that allow you to set or modify ACLs for access control:
Creating CalendarsThis 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 12, "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 9, "Configuring Calendar Lookup Database Plug-in".
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 13-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. 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".
Creating a Resource Calendar
Calendar Server does not automatically provision resource calendars. For every resource required at your site, you must use the csresource utility create command to manually provision the resource LDAP entry and create its calendar in the calendar database. Several considerations for creating resource calendars are:
- 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.
- 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.
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 13-3:
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 CalendarsAfter your user calendars are created, use the cscal utility to perform the following administrative tasks:
Displaying 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
Deleting a Calendar
End users can unsubscribe from a calendar through Calendar Express, but an end user cannot delete a calendar from the Calendar Server database. Deleting a calendar must be done by an administrator who has administrative rights to the system.
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 15, "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
Disabling and Enabling 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
Modifying 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:
Removing 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
Recovering 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.
Managing Resource CalendarsDisplaying 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
Modifying 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).
Disabling and Enabling 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
Deleting 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.
Linking to a CalendarYou 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 DataTo 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
If the specified calendar ID (calid) already exists, its data is cleared before the new data is imported.