Chapter 2   Managing Calendar Server Users and Calendars


This chapter describes how to use the Calendar Server command-line utilities to provision and manage users and calendars, including both user calendars and resource calendars.

This chapter contains these sections:

• Provisioning New Calendar Server Users

• Managing Calendar Server Users

• Managing User Calendars

• Creating and Managing Resource Calendars

• Linking to a Calendar

To provision and manage Calendar Server users and calendars, use the following command line-utilities:

• The csuser utility manages calendar user information stored in an LDAP directory server and the calendar database.

• The cscal utility manages calendars and their properties in the calendar database.

• The csresource utility manages calendars for resources such as conference rooms or equipment stored in the LDAP server and the calendar database.

To run the command-line utilities, you must log in as a user who has administrator rights to the system where the Calendar Server is running. For more information, see Chapter 7 "Calendar Server Command-Line Utilities."

Provisioning New Calendar Server Users

---

This section provides the following information about provisioning new Calendar Server users:

• Directory Server Requirements

• Calendar Identifiers (calids)

• Checking if a User is Enabled for Calendaring

• Provisioning a New User

• Creating a New Calendar

Directory Server Requirements

The Calendar Server requires that a calendar user be stored in a directory server. The Calendar Server then uses the directory server for user authentication and for the storage and retrieval of user preferences.

The Calendar Server default installation supports users defined in an LDAP directory, such as the Netscape Directory Server. If your users are already stored in an LDAP directory, you can simply upgrade your directory server to Netscape Directory Server 4.12 or later, which supports the schema extensions that allow users to access the Calendar Server.

For information about installing and configuring Netscape Directory Server, see:

http://docs.sun.com/db/prod/s1dirsrv

You can also modify your directory schema manually to allow your users to access the Calendar Server data. For information, see the Sun ONE Calendar Server Installation Guide.

Calendar Identifiers (calids)

Each calendar in the Calendar Server database is identified by a unique calendar identifier (ID) or calid. The format for a calid is:

userid[:calendar]

where userid is the user ID and calendar is the calendar name.

Calendar IDs are case sensitive. For example, JSMITH is not equivalent to jsmith. (This distinction differs from email addresses, which are not case sensitive. For example, jsmith@sesta.com is equivalent to JSMITH@SESTA.COM.)

A calid cannot contain spaces but can include the following characters:

• Alphabetic (a-z, A-Z) and numeric (0-9) characters

• Special characters: period (.), underscore (_), hyphen or dash (-), at sign (@), apostrophe (`), percent sign (%), slash (/), or exclamation point (!)

Examples of calendar IDs are jsmith, jsmith:new-cal, and jsmith:private_calendar.

Because the user ID is part of the calid, the user ID cannot contain spaces (for example, j smith). A user with a user ID that contains a space can log into the Calendar Server, but if the user then tries to create an event or task, the Calendar Server returns a Bad Request error.

Calendar Lookup Database (CLD) Plug-in

If the calendar database is distributed over several back-end servers (for example, see Figure 1-5), Calendar Server uses a plug-in to determine the actual server where a calendar is stored. Calendar Server accesses the calendar data on the back-end server using the Distributed Wire Protocol (DWP). DWP is an internal protocol that runs as the csdwpd service and provides the networking capability for the calendar database.

Calendar Server loads the specific plug-in, depending on the value of the caldb.cld.type parameter in the ics.conf file:

• local (the default) specifies that all calendars are stored on the local server where Calendar Server is running and no plug-in is loaded.

• algorithmic specifies the algorithmic CLD plug-in, which uses a regular expression in the ics.conf file to determine the server where a specified calendar is stored. This expression is specified with the parameter:

  caldb.cld.server.[hostname].regexpr = "expression"

  where hostname specifies the name of the server and expression identifies the calendar on the server. For more information, see "Configuring Calendar Lookup Database (CLD) Plug-ins".

• directory specifies the LDAP CLD plug-in, which uses a calendar owner's icsDWPHost LDAP attribute to determine the server where a specified calendar is stored.

Checking if a User is Enabled for Calendaring

To determine if a specific user exists in your directory server and is enabled to access Calendar Server data, use the csuser utility check command.

For example, to check if JSmith is enabled for calendaring:

csuser check JSmith

If the check command indicates that a user does not exist in your LDAP directory server, you must create a directory server entry for the user.

Provisioning a New User

The csuser utility can create an entry in the LDAP directory server and enable a user for calendaring. In the current release, however, it is recommended that you provision user LDAP attributes using a directory service utility or a customized user provisioning tool.

For example, use the ldapsearch and ldapmodify utilities. For information about these utilities, see the iPlanet Directory Server documentation on the following Web site:

http://docs.sun.com/db/prod/s1dirsrv

If the user already exists in your LDAP directory, a new calendar can be created for the user either manually or automatically:

• Manually - Use the cscal utility create command to create a new calendar for the user. See "Creating a New Calendar".

• Automatically - The first time a new user logs into the Calendar Server, the Calendar Server automatically creates a new default calendar for the user. The Calendar Server uses the user's user ID for the calendar ID (calid) of the new calendar, unless a calendar by that name already exists.

  In the current release, the Calendar Server always creates a default calendar for a new user the first time the user logs into the Calendar Server, and you cannot disable this functionality.

  For example, if JSmith logs into the Calendar Server for the first time, the Calendar Server automatically creates a default calendar with JSmith as the calid.

  The Calendar Server also assigns the prefix JSmith to the calid of each subsequent calendar that JSmith creates. For example, if JSmith later creates a new calendar named meetings, the calid is JSmith:meetings.

If a user sends a request to another user who has not been enabled for calendaring (that is, the user does not have a default calendar), the Calendar Server returns the Calendar not found error to the user sending the request.

Creating a New Calendar

To create a new calendar, use the cscal utility create command. The user (user ID) must already exist in the directory server.

If your site is using the LDAP Calendar Lookup Database (CLD) plug-in, you must create a new calendar on the same back-end server where the user's calendars reside (or will reside), as indicated by the user's icsDWPHost LDAP attribute. If you try to create a calendar on a different back-end server, Calendar Server returns an error. For information about the LDAP CLD plug-in, see "LDAP Calendar Lookup Database (CLD) Plug-in".

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

cscal -o JSmith -n JohnSmithCalendar create JSmith

where:

• -o JSmith specifies the primary owner of the new calendar.

• -n JohnSmithCalendar specifies the viewable name for the new calendar.

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

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

cscal -n Hobbies -o JSmith create Personal

where:

• -n Hobbies specifies the viewable name of the calendar.

• -o JSmith specifies the user ID of the primary owner.

• Personal is used as the second part of the calendar ID (calid). For example: JSmith:Personal

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

cscal -n Hobbies -o JSmith -g sports -k yes -y RJones create Personal

where:

• -g sports associates the calendar with a category named sports.

• -y RJones specifies another owner of the calendar.

• -k yes enables double booking.

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.

Managing Calendar Server Users

---

After your users are provisioned, use the csuser utility to perform the following administrative tasks:

• Displaying User Information

• Disabling and Enabling a User

• Deleting a User

• Resetting a User's Attributes

Displaying User Information

To list all calendar users or to display the calendar attributes of a specified user, use the csuser utility list command.

For example, to display all users enabled for calendaring:

csuser list

To display all of the calendar attributes of a single user such as JSmith:

csuser -v list JSmith

Disabling and Enabling a User

To prevent a user from logging into Calendar Server, use the csuser utility disable command. The disable command prohibits a user from accessing calendar data, but it does not remove the user's information from the directory server or the Calendar Server database.

For example, to disable JSmith from accessing the Calendar Server:

csuser disable JSmith

This command prevents JSmith from logging into the Calendar Server to access calendar data, but JSmith's data is not deleted from the calendar database. However, if JSmith is currently logged into the Calendar Server, JSmith retains access to calendar data until logging off.

To enable a user to access the Calendar Server and optionally to assign specific configuration settings such as a default calendar, use the csuser utility enable command.

For example, to enable JSmith to access (log into the Calendar Server) and to assign JSmith a default calendar:

csuser jsmith enable JSmith

Deleting a User

To delete a Calendar Server user, use the csuser utility delete command.

---

Caution

The csuser utility delete command removes all of the user's Calendar Server information from the LDAP server. You can recover Calendar Server database information if the calendar database has been backed up. For more information, see Chapter 6 "Backing Up and Restoring Calendar Server Data." However, you can recover the LDAP server information only if you have specifically backed it up.

---

For example, to delete JSmith from the Calendar Server:

csuser delete JSmith

Resetting a User's Attributes

To restore the default settings of all calendar LDAP attributes for a specific user, use the csuser utility reset command.

For example, to reset all calendar attributes of JSmith to the default configuration settings:

csuser reset JSmith

---

Note

After a calendar user has been reset, all of the calendar attributes are removed from the user's LDAP entry, including icsCalendarUser (object class), icsSubscribed, icsCalendarOwned, icsCalendar, and icsDWPHost (if in the LDAP CLD setup). A Calendar Server administrator will not be able to create calendars on the user's behalf. These attributes are restored in the user's LDAP entry when: The user logs back into Calendar Server, or The Calendar Server administrator issues a csuser enable command for the user (although in this case, the icsDWPHost attribute is not restored).

---

Managing User Calendars

---

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

• Displaying Calendars

• Deleting a Calendar

• Disabling and Enabling a Calendar

• Modifying Calendar Properties

• Removing Properties From a Calendar

• Recovering a "Lost" Calendar

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 the 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 6 "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 AllAdmins

where:

• -a "@@o^c^wd^g" grants owners write and delete access to the components (events and tasks) of AllAdmins.

• -y RJones specifies this user ID as another owner.

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 user's LDAP entry with these attributes:

• icsCalendar:default_calid

• icsSubscribed:default_calid

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

Creating and Managing Resource Calendars

---

A resource calendar is associated with a resource such as a meeting room or equipment such as a notebook computer or overhead projector.

To create and manage resource calendars, use the csresource utility. To run csresource, you must log in as a user who has administrator rights to the system where the Calendar Server is running.

This section describes how to create and manage resource calendars, including:

• Setting Resource Calendar Configuration Parameters

• Creating a Resource Calendar

• Displaying Resource Calendars and Attributes

• Modifying a Resource Calendar

• Disabling and Enabling a Resource Calendar

• Deleting a Resource Calendar

Setting Resource Calendar Configuration Parameters

Table 2-1 lists the resource calendar configuration parameters in the ics.conf file.

Table 2-1    Resource Calendar Configuration Parameters in ics.conf 

Parameter	Description
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.

The default values shown in Table 2-1 apply to new resource calendars, but you can change these default values by editing the ics.conf file. For more information, see "Editing the ics.conf Configuration File".

Creating a Resource Calendar

The Calendar Server does not automatically create resource calendars, so you must use the csresource utility create command to manually create each resource calendar required at your site. This command creates an entry in the LDAP directory server and calendar database for the new calendar. Several considerations for creating calendars are:

• By default, the 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 2-1:

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.

Displaying 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

The 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", the Calendar Server deletes the calendar and displays a message that it has been deleted.

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 login to the 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 calendars 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&vi ew=dayview