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

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.iplanet.com/docs/manuals/directory.html

You can also modify your directory schema manually to allow your users to access the Calendar Server data. For information, see the iPlanet 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 Plug-in

If the calendar database is distributed over several servers (for example, see Figure 1-5), the Calendar Server uses the Calendar Lookup Database plug-in to determine the physical location of a calendar. The Database Wire Protocol (DWP) calls the Calendar Lookup service to fully qualify a calendar ID (calid). From the returned URL, DWP can then determine the location of the calendar, along with its access protocol.

The caldb.cld.type parameter in the ics.conf file specifies the type of Calendar Lookup Database plug-in to use:

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

• algorithmic loads a plug-in that uses a regular expression to determine the server where a specified calendar ID 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 Database Wire Protocol (DWP)".

• directory loads a plug-in that uses an LDAP directory schema entry to determine the physical machine where a specified calendar ID 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, iPlanet recommends that you provision user LDAP attributes using a directory service utility or a customized user provisioning tool.

For example, if you are using Netscape Directory Server, use the ldapsearch and ldapmodify utilities. For information about these utilities, see the Netscape Directory Server documentation on the following web site:

http://docs.iplanet.com/docs/manuals/

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.

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 iPlanet 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

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

• Linking to 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 Resource Calendar

You can link to a resource calendar in email messages and web pages using a URL. Users can use the URL to anonymously view the resource calendar without having to log in to the Calendar Server (provided the calendar allows read access).

For example, the following link specifies a resource calendar for an overhead projector with the calendar ID (calid) overhead_projector10:

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