Previous     Contents     Index     Next     
iPlanet Calendar Server Administrator's Guide

Chapter 1   Introduction to iPlanet Calendar Server

iPlanet Calendar Server is a scalable, Web-based solution for centralized calendaring and scheduling for enterprises and service providers. The Calendar Server supports personal and group calendars as well calendars for resources such as conference rooms and equipment.

This chapter contains these sections:

Calendar Server Administrators

Calendar Server Administrator (calmaster)

The Calendar Server Administrator is the user name and associated password that can manage the Calendar Server. This user has administration privileges for the Calendar Server but not for the directory server. The default user ID is calmaster, but you can specify a different user during installation, if you wish. After installation you can specify a different user in service.admin.calmaster.userid in the ics.conf file.

The user ID you specify for the Calendar Server Administrator must be a valid user account in your directory server. If the Calendar Server Administrator user account does not exist in the directory server during installation, you must add it after installation. For example, if you accept the default calmaster, a user named calmaster must exist in your directory server.

Table 1-1 describes the Calendar Server Administrator configuration parameters in the ics.conf file.

Table 1-1    Calendar Server Administrator Configuration Parameters 




User ID of the person designated as the Calendar Server administrator. You must provide this required value during Calendar Server installation. The default is "calmaster".  


Password of the user ID specified as the Calendar Server administrator. You must provide this required value during installation.  


Email address of the Calendar Server administrator. The default is "root@localhost".  


Indicates whether the Calendar Server administrator can override access control.The default is "no".  


Indicates whether the Calendar Server administrator can get and set user preferences using WCAP commands.The default is "no".  


Enables LDAP for user authentication of the user specified in service.admin.calmaster.userid. The default is "yes".  

Calendar Server User and Group (UNIX only)

On Solaris and other UNIX systems, these accounts are the UNIX user and group identity under which Calendar Server runs. iPlanet recommends that you use the default values, icsuser and icsgroup, which are automatically created by the installation program if they do not exist. The icsuser and icsgroup values are stored in the local.serveruid and local.servergid parameters, respectively, in the ics.conf file.

root (UNIX only)

On Solaris and other UNIX systems, you must log in as (or become) root (user ID = 0) to install, re-install, or upgrade the Calendar Server. To manage the Calendar Server using the command-line utilities, you must log in as (or become) root or an administrator such as icsuser.

Windows NT Administrator

To install and manage the Calendar Server on Windows NT systems, you must log in as an administrator with full administrator rights to the system.

Calendar Server Users

Creation of Calendar Server Users

Calendar Server users are created either manually or automatically:

  • Manually — A administrator can add users to the directory server using the directory server tools and then create the users' default calendars using the Calendar Server cscal utility. If a user doesn't already exist in the directory server, an administrator can create both the user and the calendar at the same time using the Calendar Server csuser utility.

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

    For example, suppose TChang exists in the directory server but is not yet enabled for calendaring (that is, does not have a default calendar). When TChang logs into the Calendar Server for the first time, it automatically enables TChang for calendaring and creates a default calendar with the calid TChang.

Authentication of Calendar Server Users

The Calendar Server stores and manages calendars, calendar properties, access control information, events, todos (tasks), and alarms. The Calendar Server, however, requires a directory service such as an LDAP server for user authentication and for the storage and retrieval of user preferences.

The Calendar Server default installation supports users defined and maintained in an LDAP directory, such as Netscape Directory Server. To allow access for users defined in a non-LDAP directory server, the Calendar Server also supports Calendar Server API (CSAPI) plug-ins.

For more information, see "Provisioning New Calendar Server Users".

Calendar Server Data

For information about access control for data, see "Calendar Server Access Control".

Calendar Server Data Format

The Calendar Server data format is modeled after RFC 2445, Internet Calendaring and Scheduling Core Object Specification (iCalendar). The Calendar Server stores and manages calendars, calendar properties, access control information, events, todos (tasks), and alarms. The Calendar Server, however, does not manage user information. It requires a directory service to perform operations such as user authentication and the storage and retrieval of user preferences.

Calendar Server Format Encoding

The Calendar Server supports the following format encodings:

  • SHTML (.shtml)—the default

  • XML (.xml)—WCAP only

  • iCalendar (.ical)—WCAP only

You can add other formats by developing your own XSL translations for the Calendar Express views and dialogs. Or by using CSAPI, you can develop a translator DLL or shared library for the WCAP protocol.

For details about CSAPI, see the iPlanet Calendar Server Programmer's Manual.

Calendar Groups

A calendar group is a named list of individual calendars. Group calendars allow multiple calendars to be combined into a single calendar for display purposes. A user can, for example, have a calendar group made up of a private calendar, department calendar, and a company holidays calendar.

Users can create or subscribe to calendar groups and then view and modify the calendar group (subject to access control). They can then view the calendar group, rather than having to select a list of calendars each time they want to view them side-by-side or invite the calendar owners to an event.

Calendar Server Event Feeds

The Calendar Server supports event feeds, which allows users to import and export calendar data in either iCalendar (.ics) or XML (.xml) formats. End users can import and export data using Calendar Express. For information, see the Calendar Express online help.

Users can also subscribe to event or group calendars such as holiday schedules, convention center schedules, concert schedules, or any other schedule of events that might be of interest.

Calendar Server administrators can also import and export calendar data using the csimport and csexport command-line utilities.

Calendar Server Data Exchange and Alarms

Calendars can be referenced as links that can be embedded in email messages and Web pages. Users can then click a link to view a calendar, and as long as the calendar allows read access, are not required to log into the Calendar Server. For example, the following link specifies a resource room named Auditorium:

The Calendar Server supports server-side email alarms, which can be sent to a list of recipients. The format of the email message is configurable and is maintained as a server attribute, rather than as a user or calendar attribute. The Calendar Server has limited support for the ITIP/IMIP standards (RFC-2446 and RFC-2447), including ITIP methods PUBLISH, REQUEST, REPLY, and CANCEL for events.

Calendar Server User Preferences

The Calendar Server customizes the display of calendar information for each user according to attributes called user preferences. User preferences (as opposed to calendar preferences) refer to the user interface representation of calendar information. User preferences include such things as email address, user name, and preferred colors to use when rendering calendar information. For a list of preferences, see the get_userprefs and set_userprefs commands in the iPlanet Calendar Server Programmer's Manual.

Calendar Server Architecture

For descriptions of more complex Calendar Server configurations, see Calendar Server Deployment Configurations.

Calendar Server Internal Subsystems

The Calendar Server includes a collection of shared libraries that make up the following internal subsystems:

Figure 1-1 shows the logical flow through these subsystems.

Figure 1-1    Calendar Server Internal Subsystems Logical Flow

Protocol Subsystem

Commands and requests enter through the HTTP protocol layer. This is a minimal HTTP server implementation, streamlined to support calendar requests.

Clients use either SHTML or Web Calendar Access Protocol (WCAP) to submit requests:

  • SHTML is based on XML and XSLT specifications, which generate a user interface in response to commands. In response to an incoming request, the UI generator uses an XML specification to build a document tree with calendar and user data, subject to access control. The XSLT specification then traverses the document data tree and emits HTML. This design results in fewer interactions between the client and server, which reduces the network traffic.

  • WCAP is an open protocol that can perform all server commands (except for specific administrative commands). WCAP can be used by clients that need raw, unformatted calendar information, but it can also be used to obtain a JavaScript based user interface. WCAP commands (that is, commands that use the .wcap extension) can also request output as XML or iCalendar wrapped in HTML.

    For a description of WCAP, see the iPlanet Calendar Server Programmer's Manual.

Core Subsystem

The Core subsystem includes the Access Control subsystem, the UI Generator subsystem (either SHTML using XML and XSLT or WCAP using data translators), Caldb subsystem, and any CSAPI plug-ins. The Core subsystem processes calendar requests and generates the desired UI output. The Core subsystem also handles user authentication including:

Database Subsystem

The Database subsystem uses the Berkeley DB from Sleepycat Software (the database API is not public). The Database subsystem stores and retrieves calendar data to and from the database, including events, todos (tasks), and alarms. Calendar data is based on iCalendar format, and the schema used for Calendar Server data is a superset of the iCalendar standard. The Database subsystem returns data in a low-level format, and the Core UI generator (either SHTML or WCAP) then translates the low-level data into the desired output.

For a distributed calendar store, the Calendar Server use the Database Wire Protocol (DWP) to provide a networking capability. For more information, see "Distributed Database Service - csdwpd".

For information about managing the database, see Chapter 5 "Managing Calendar Server Databases," which describes how to manage databases and calendar data using the csdb utility.

Calendar Server Services

These services run as processes (or daemons on UNIX systems) on a single machine or on multiple machines, depending on your configuration.

Administration Service - csadmind

The csadmind service is required for each instance of the Calendar Server. It provides a single point of authentication for administering the Calendar Server and provides most of the administration tools such as commands to start or stop a service, list or log out users, create or delete users or resources, fetch or store calendars, and fetch or reset counters. The csadmind service also manages alarm notifications, group scheduling requests, database checkpointing, and deadlock detection, as well as disk usage and server response monitoring.

HTTP Service - cshttpd

Since the Calendar Server uses HTTP as its primary transport, the cshttpd service listens for HTTP commands. The cshttpd service receives user commands and returns data to the caller, depending on the format of the incoming command:

  • For a command received with the default .shtml extension, cshttpd returns data formatted in HTML.

  • For a command received with the.wcap extension, cshttpd returns data formatted as calendar data in standard RFC2445 iCalendar format (text/calendar), XML format (text/xml), or JavaScript embedded in HTML (text/js).

Notification Service - csnotifyd

The csnotifyd service sends notifications of events and todos (tasks) using the Event Notification Service (ENS) as the broker for events. csnotifyd also subscribes to alarm events. When an alarm event occurs, csnotifyd sends an SMTP message reminder to the recipients.

Event Notification Service (ENS) - enpd

The enpd service is the other half of the Event Notification Service (ENS) and acts as the broker for event alarms. enpd receives notifications of alarms from the csadmind service, checks for subscriptions to this event, and then notifies the event's subscribers by passing the subscribed-to alarm notifications to csnotifyd. enpd also receives and stores subscriptions and cancellations of subscriptions (unsubscribe) from csnotifyd.

Distributed Database Service - csdwpd

The csdwpd service allows you to link multiple servers together within the same Calendar Server system to form a distributed calendar store. csdwpd can run in the background on any server where the Calendar Server is installed. It then accepts requests that follow the Database Wire Protocol (DWP) for calendar information. DWP is an internal protocol used to provide networking capability for the Calendar Server database.

The csdwpd service should be run only on a server that has a local calendar database and must provide network access to its calendar data from other Calendar Server installations.

You should use DWP only on a relatively fast network. If the network connection between the various databases is slow, DWP can degrade overall system performance.

Basic Calendar Server Configurations

The Calendar Server can be configured to fit the different needs of an organization. For example, it can run as a stand-alone server, or it can be configured with multiple instances, with the various Calendar Server services duplicated or split between the instances.

This section describes these basic Calendar Server configurations:

For descriptions of more complex Calendar Server configurations, see Calendar Server Deployment Configurations.

Minimal Calendar Server Configuration

Figure 1-2 shows a minimal Calendar Server configuration, including a:

  • Single Calendar Server instance with support for event notifications. This configuration consists of the required Administration Service (csadmind), the HTTP service (cshttpd) to handle incoming SHTML and WCAP requests, and the Event Notification Services (ENS), enpd and csnotifyd.

  • Directory service such as an LDAP server.

In Figure 1-2, CLD is the Calendar Lookup Database. CUA is a Calendar User Agent, which is an application that a calendar client uses to access the Calendar Server. iCal refers to RFC 2445, Internet Calendaring and Scheduling Core Object Specification (iCalendar). The calendar database is local, so the Database Wire Protocol (DWP) service is not required.

Figure 1-2    Minimal Calendar Server Configuration

Scalable Calendar Server Configuration

The Calendar Server is scalable both vertically and horizontally. The Calendar Server can run in multiple processors on a single machine or on multiple machines. The Calendar Server consists of the cshttpd, csadmind, csdwpd, csnotifyd, and enpd. services, which can be run in different configurations to allow you great flexibility and scalability.

The Calendar Server supports horizontal scalability, which is spreading an installation over several machines. To achieve horizontal scalability, you can install various instances of the Calendar Server across your machines. The basic requirements for each system are:

  • Each Calendar Server instance must have an Administration (csadmind) service. You can, however, install the Event Notification Services (ENS) enpd and csnotifyd on a separate instance without the csadmind service.

  • All other Calendar Server services must be installed at least once, unless you have a single-instance installation using a local database. In this installation, the DWP (csdwpd) service is not required because the calendar database is local.

Figure 1-3 shows three Calendar Server HTTP front-end services using three Calendar Server database services. All six of these instances can run on separate machines.

This configuration uses the Database Wire Protocol (DWP), which is an internal protocol that provides networking capability for the Calendar Server database. DWP uses HTTP as its base, with an HTTP POST or GET command with a single binary MIME part that contains serialized binary database information. For more information, see Distributed Database Service - csdwpd.

Figure 1-3    Scalable Calendar Server Configuration

Calendar Server Access Control

The 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). An ACL consists of one or more access control entries (ACEs), which are strings that collectively apply to the same calendar or component. Each ACE in an ACL must be separated by a semicolon. For example:

  • jsmith^c^wd^g consists of a single ACE.

  • @@o^a^r^g;@@o^c^wdeic^g;@^a^sf^g consists of three ACEs.

Calendar Server access control features are:

  • Calendar properties - Only the primary owner of a calendar or an administrator can delete a calendar or change the calendar's properties, including its ACLs.

  • Group scheduling - When an organizer schedules a group event, the Calendar Server uses ACLs to determine the access to the invitees' calendars. For example, the organizer of an event might be able to view only the free/busy time for an attendee and not the attendee's entire calendar.

  • Other owners - The primary owner of a calendar can specify other owners of the calendar to act in their behalf. For example, a primary owner such as a vice president can designate an administrative assistant to schedule meetings and invite attendees, or to cancel or accept invitations to meetings scheduled by others.

End users set the access control for their calendars using Calendar Express. Calendar Server administrators can set access control configuration parameters in the ics.conf file and use the cscal, csresource, and csuser command-line utilities.

For more information, see Chapter 4 "Managing Calendar Server Access Control."

Calendar Server APIs and SDKs

For detailed information about these APIs, see the iPlanet Calendar Server Programmer's Manual.

Calendar Server API (CSAPI)

The Calendar Server API (CSAPI) allows a programmer to customize functional areas of the Calendar Server such as user login authentication, access control, and calendar lookup.

For example, by default the Calendar Server uses entries in an LDAP server to authenticate users and to store user preferences. If you have another mechanism that is not based on LDAP, you can use CSAPI to implement your existing authentication and directory services and override the default Calendar Server mechanisms.

Event Notification Service (ENS) API

The Event Notification Service (ENS) is an alarm dispatcher that detects events on an alarm queue and sends notifications of these events to its subscribers. The ENS API allows programmers to modify publish-and-subscribe functions used by the Calendar Server to perform functions such as subscribe to events, unsubscribe to events, and notify a subscriber of events. The ENS APIs consists of these specific APIs:

  • Published API

  • Subscriber API

  • Publish and Subscribe Dispatcher API

Proxy Authentication SDK (authSDK)

The Calendar Server provides the authSDK for user authentication. With authSDK, you can integrate an existing portal service with the Calendar Server, thus allowing users to access various applications without requiring re-authentication.

A connection established between the Calendar Server and the authSDK forms a trusted relationship. If a user logs in and successfully authenticates to the authSDK, the Calendar Server accepts the certificate generated by the proxy for its functions.

The authSDK consists of the following functions packaged in a DLL/shared-object library (libicsexp10) and a header (file, expapi.h):

  • CEXP_GenerateLoginURL generates a URL with the valid session ID.

  • CEXP_GetVersion generates the version ID string.

  • CEXP_Init initializes the SDK.

  • CEXP_SetHttpPort allows you to specify the port over which you will contact the Calendar Server.

  • CEXP_Shutdown performs all shutdown procedures, including freeing memory and shutting down connections.

Web Calendar Access Protocol (WCAP)

iPlanet Calendar Server 5.x supports WCAP 2.0, a high-level, command-based protocol that allows communication with clients. WCAP commands, which use the .wcap extension, allow clients to get, modify, and delete calendar components, user preferences, calendar properties, and other calendar information such as time zones. WCAP elements such as times, strings, and parameters follow RFC2445, RFC2446, and RFC2447 specifications (unless otherwise noted).

WCAP returns output calendar data in an HTTP message in the following formats:

  • Standard RFC2445 iCalendar format (text/calendar)

  • XML format (text/xml)

  • JavaScript embedded in HTML (text/js).

Using WCAP commands, a Calendar Server administrator who logs in using login.wcap has the following capabilities:

  • To override the access control of WCAP commands

    The administrator can use WCAP commands to read (fetch), alter (store), or delete other user's calendars. For an administrator to have this privilege, the following parameter in the ics.conf file must be set to "yes":


  • To retrieve and modify user preferences for any user

    The administrator can use get_userprefs.wcap and set_userprefs.wcap to retrieve and modify any user's preferences. For an administrator to have this privilege, the following parameter in the ics.conf file must be set to "yes":


For more information, see the iPlanet Calendar Server Programmer's Manual.

Single Sign-on (SSO)

Single Sign-on (SSO) allows a user to authenticate once and then use multiple applications. For example, a user can log into Calendar Express and then use Messenger Express without authenticating again.

SSO is independent from other authentication mechanisms, session management, and resource access control. With SSO, applications form circles of trust that share cookies and accept each others' user authentication. Each verification authority stores a cookie that is understood by the other applications' verification routines. Each application can also have its own verification interface, if necessary.

SSO has the following requirements:

  • The client browser must accept cookies.

  • Each application must implement the verification protocol.

  • All trusted applications must be in the same domain.

  • To switch to a different identity, the user must restart the browser, because each browser session can support only one user ID.

To enable SSO between applications, you must configure each application. For information about configuring Calendar Server, see "Configuring Single Sign-on (SSO)".

Calendar Server Deployment Configurations

In addition to the Minimal Calendar Server Configuration (Figure 1-2) and the Scalable Calendar Server Configuration (Figure 1-3), two other Calendar Server configurations are:

(Other Calendar Server configurations are also possible, depending on the requirements of the specific site.)

Network Front End, Single Database Back End

serviceFigure 1-4 shows a configuration where client browsers and applications connect to the Calendar Server through the HTTP (cshttp) service at the front end ( All requests for calendar data are then routed to the back end ( using the DWP (csdwpd) service.

The front end requires only the HTTP (cshttp) and Administration (csadmind) services, because it does not perform any database processing. The back end does not require cshttpd, but it does require the Administration (csadmind) and DWP (csdwpd) services and the Event Notification Services (ENS), enpd and csnotifyd.

Figure 1-4    Network Front End, Database Back End

Multiple Front Ends, Multiple Database Back Ends

Figure 1-5 shows a configuration where clients are routed to one of the front-end HTTP (cshttp) services by a user-supplied mechanism. The session ID returned at login is valid only on the host system where the login occurred. All requests for this session ID must be routed to the same host, or the user is forced to log in again.

In this example, the database has been distributed, with calendars A-M on the server and calendars N-Z on the server. A CSAPI plug-in handles the mapping between calendar IDs and the server where the calendar is located. (The default CSAPI implementation provided by the Calendar Server uses an algorithm to associate a calendar ID with a server name. See "Calendar Lookup Database Plug-in" for more information.)

Each front end requires the HTTP (cshttp) and Administration (csadmind) services. All requests for calendar data are routed to the appropriate back end using the DWP (csdwpd) service. Each back end requires the Administration (csadmind) and DWP (csdwpd) services and the Event Notification Services (ENS), enpd and csnotifyd.

Figure 1-5    Multiple Front Ends, Multiple Database Back Ends

Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated January 22, 2002