Previous     Contents     Index     Next     
iPlanet Calendar Server Administrator's Guide



Chapter 3   Managing the Calendar Server


This chapter describes how to manage and configure iPlanet Calendar Server.

This chapter contains these sections:

You manage the Calendar Server by running command-line utilities and by editing the ics.conf configuration file.

To run the command-line utilities, you must log in as a user who has administrative rights to the system where the Calendar Server is running.

For more information, see Chapter 7 "Calendar Server Command-Line Utilities" and Chapter 8 "Calendar Server Configuration."



Starting and Stopping the Calendar Server


You can start and stop the Calendar Server as follows:


Note The Calendar Server provides the csstart and csstop utilities only to provide compatibility with earlier releases. iPlanet recommends that you use the start-cal and stop-cal commands to start and stop the Calendar Server.



Using the start-cal and stop-cal Commands

The start-cal and stop-cal utilities are located in the server-root/cal/bin directory. You must run these utilities on the local machine where the Calendar Server is installed. For problems that might occur, see "Troubleshooting the start-cal and stop-cal Commands".

The start-cal command starts the Calendar Server services in the following order:

  1. enpd — Event Notification Service (ENS)

  2. csnotifyd — Notification Service

  3. csadmind — Administration Service

  4. csdwpd — Distributed Database Service (started only with a remote Calendar Server database configuration)

  5. cshttpd — HTTP Service

For a description of these services, see "Calendar Server Services".


To start the Calendar Server using the start-cal command:

  1. Log in as a user who has administrative rights to the system.

  2. Change to the server-root/cal/bin directory. For example on Solaris systems:

    cd /opt/SUNWics5/cal/bin

  3. Start the Calendar Server:

    ./start-cal


To stop the Calendar Server using the stop-cal command:
  1. Log in as a user who has administrative rights to the system where the Calendar Server is running.

  2. Change to the server-root/cal/bin directory. For example on Solaris systems:

    cd /opt/SUNWics5/cal/bin

  3. Stop the Calendar Server:

    ./stop-cal


Using the Windows NT Control Panel

On Windows NT systems, use the Services dialog box from the Control Panel.


To start and stop the Calendar Server using the Windows NT Control Panel:

  1. Log in as a user who has administrative rights to the Windows NT system.

  2. Display the Services dialog box from the Control Panel:

    Start>Settings>Control Panel>Services

  3. Under Service, click the specific Calendar Server service (Admin, DWP, HTTP, ENS, or Notification) and then click Start or Stop.

For more information, refer to the Windows NT online Help.


Troubleshooting the start-cal and stop-cal Commands

When you are starting and stopping the Calendar Server, the following problems might occur:

  • The start-cal command does not start all of the Calendar Server processes. For example, start-cal might start the enpd, csnotifyd, and csadmind processes but not cshttpd. In this situation, you must stop all of the Calendar Server processes before you try to restart the Calendar Server.

  • The stop-cal command does not stop all of the Calendar Server processes. For example, stop-cal might stop the cshttpd parent process but not any cshttpd child processes. In this situation, you must stop the remaining Calendar Server processes.


To stop Calendar Server processes on a Windows NT system:
  1. Log in as a user who has administrative rights to the system where the Calendar Server is running.

  2. Use the Task Manager to identify and then stop any remaining Calendar Server processes.


To stop Calendar Server processes on Solaris and other UNIX systems:
  1. Log in as a user who has administrative rights to the system where the Calendar Server is running.

  2. Determine the process ID (PID) of the remaining Calendar Server processes by entering a ps command for each service:

    ps -elf | grep cs-process

    where cs-process  is enpd, csnotifyd, csdwpd, csadmind, or cshttpd. For example:

    ps -elf | grep cshttpd

  3. Using the PID of each process that is still running, enter a pkill -15 command to kill the process. For example:

    pkill -15 9875

  4. Enter each ps command again to make sure that all Calendar Server processes are stopped.

    If a Calendar Server process is still running, enter a pkill -9 command to kill it. For example:

    pkill -9 9875


    Caution

    		After you have stopped all of the Calendar Server processes and before you restart the Calendar Server, consider running the csdb utility check command to check for any calendar database corruption that might have occurred.

    For information about the check command, see "Checking and Rebuilding a Calendar Database".




Configuring Calendar Server Timeout Values

For information about editing ics.conf parameters, see "Editing the ics.conf Configuration File".


Configuring Timeout Values for csadmind

Table 3-1 describes the Calendar Server timeout parameters in the ics.conf file used by the Administration (csadmin) service.


Table 3-1    HTTP Timeout Values for the Administration Service (csadmin)

Parameter

Description

service.admin.idletimeout  

Specifies the number of seconds the csadmind service waits before timing out an idle HTTP connection.

The default is 120 seconds (2 minutes).  

service.admin.resourcetimeout  

Specifies the number of seconds the csadmind service waits before timing out an HTTP session for a resource calendar.

The default is 900 seconds (15 minutes).  

service.admin.sessiontimeout   

Specifies the number of seconds the csadmind service waits before timing out an HTTP session.

The default is 1800 seconds (30 minutes).  


Configuring HTTP Timeout Values for End Users

Table 3-2 describes the Calendar Server HTTP timeout parameters in the ics.conf file that apply to end users.


Table 3-2    HTTP Timeout Values in ics.conf for End Users (cshttpd Service)

Parameter

Description

service.http.idletimeout  

Specifies the number of seconds the cshttpd service waits before timing out an idle HTTP connection.

The default is 120 seconds (2 minutes).  

service.http.resourcetimeout  

Specifies the number of seconds the cshttpd service waits before timing out an HTTP session for a resource calendar.

The default is 900 seconds (15 minutes).  

service.http.sessiontimeout   

Specifies the number of seconds the cshttpd service waits before timing out an HTTP session.

The default is 1800 seconds (30 minutes).  



Configuring Single Sign-on (SSO)


Single Sign-on (SSO) allows a user to authenticate once and then use multiple trusted applications without having to authenticate again. For example, a user can log in to Messenger Express and then use Calendar Express without authenticating again, if SSO is enabled for both applications.

When configuring SSO, consider these points:

  • Each trusted application must be configured for SSO.

  • SSO does not work correctly if the default.html page is in your browser's cache. Before using SSO, be sure to reload the default.html page in your browser. For example, in Netscape Navigator, hold down the Shift key and then click Reload.

  • SSO works only for bare URLs. For example, SSO works for http://servername but not for URLs such as http://servername/command.shtml?view.

The following example shows an SSO configuration for the Calendar Server (Calendar Express) and Messaging Server (Messenger Express) for the sesta.com domain.


To configure Single Sign-on (SSO):

  1. Log in as a user with administrator privileges.

  2. Stop the Calendar Server and Messaging Server.

  3. Edit the Calendar Server ics.conf file as described in Table 3-3. (For a description of the Calendar Server SSO configuration parameters, see "Single Sign-on (SSO) Configuration".)


Table 3-3    Calendar Server Configuration for SSO 

Parameter

Description

sso.enable = "1"  

This parameter must be set to"1" (the default) to enable SSO. "0" disables SSO.  

sso.appid = "ics50"  

This parameter specifies the unique application ID for the specific Calendar Server installation. Each trusted application must also have a unique application ID. The default is "ics50".  

sso.appprefix = "ssogrp1"  

This parameter specifies the prefix value to be used for formatting SSO cookies. The same value must be used by all trusted applications, because only SSO cookies with this prefix will be recognized by the Calendar Server. The default is "ssogrp1".  

sso.cookiedomain = ".sesta.com"  

This parameter causes the browser to send a cookie only to servers in the specified domain. The value must begin with a period (.)  

sso.singlesignoff = "true"  

A value of "true" (the default) clears all SSO cookies on the client with prefix values matching the value configured in sso.appprefix when the client logs out.  

sso.userdomain = "sesta.com"  

This parameter sets the domain used as part of the user's SSO authentication.  

sso.appid.url = "verifyurl"

For example:

sso.ics50.url = "http://sesta.com:8883/VerifySSO?"

sso.msg50.url = "http://sesta.com:8882/VerifySSO?"   

This parameter sets the verify URL values for peer SSO hosts for the Calendar Server configuration. One parameter is required for each trusted peer SSO host. The parameter includes the:

  • Application ID (appid) identifies each peer SSO host whose SSO cookies are to be honored

  • Verify URL ("verifyurl") includes the host URL, host port number, and VerifySSO? (including the ending ?).

In this example, the Calendar Server application ID is ics50, the host URL is sesta.com, and the port is 8883.

The Messenger Express application ID is msg50, the host URL is sesta.com, and the port is 8882.  

  1. Use configutil to set the Messaging Server configuration parameters as shown in Table 3-4. You do not have to enclose these parameters in double quotation marks (").


Table 3-4    Messaging Server Configuration for SSO 

Parameter

Description

local.webmail.sso.enable = 1  

This parameter must be set to a non-zero value to enable SSO.  

local.webmail.sso.prefix = ssogrp1  

This parameter specifies a prefix used when formatting SSO cookies set by the HTTP server.  

local.webmail.sso.id = msg50  

This parameter specifies the unique application ID (msg50) for the Messaging Server.

Each trusted application must also have a unique application ID.  

local.webmail.sso.cookiedomain = .sesta.com  

This parameter specifies the cookie domain value of all SSO cookies set by the HTTP server.  

local.webmail.sso.singlesignoff = 1  

A non-zero value clears all SSO cookies on the client with prefix values matching the value configured in local.webmail.sso.prefix when the client logs out.  

sso.appid.url = "verifyurl"

For example:

local.sso.ics50.verifyurl = http://sesta.com:8883/VerifySSO?

local.sso.msg50.verifyurl = http://sesta.com:8882/VerifySSO?   

This parameter sets the verify URL values for peer SSO hosts for the Messaging Server configuration. One parameter is required for each trusted peer SSO host. The parameter includes the:

  • Application ID (appid) identifies each peer SSO host whose SSO cookies are to be honored

  • Verify URL ("verifyurl") includes the host URL, host port number, and VerifySSO? (including the ending ?).

In this example, the Messaging Server application ID is msg50, the host URL is sesta.com, and the port is 8882.

The Calendar Server application ID is ics50, the host URL is sesta.com, and the port is 8883.  

  1. Restart the Calendar Server and Messaging Server to update the configurations.

    For more information, see "Starting and Stopping the Calendar Server". For information about the Messaging Server, see the iPlanet Messaging Server Administrator's Guide.



Configuring Database Wire Protocol (DWP)

DWP is a proprietary protocol used by the Calendar Server to perform calendar database operations over a network. DWP uses HTTP as its transport mechanism and includes a subset of the calendar database API.

If the calendar database resides on the local server, the Calendar Server Database subsystem uses the calid to access a calendar in the database. However, if the calendar database is located over a network (such as, on a back-end server), the Calendar Server must use the Calendar Lookup Database plug-in to determine the network address of the server where a calendar actually resides. The request is then forwarded to the DWP (csdwpd) service on the other server for processing.


Front-End Machine and a Back-End Server

Figure 3-1 shows a Calendar Server configuration with a single front-end machine and a back-end server. To use DWP, the front-end machine and back-end server must be running the same operating system and the same version of the Calendar Server (such as 5.1).

Figure 3-1    Calendar Server Configuration for a Front-End Machine and a Back-End Server



In the configuration shown in Figure 3-1, the front-end machine performs these functions:

  • Handles client requests for calendar data residing over a network

  • Makes requests to the back-end server for calendar data

  • Transforms the calendar data first into an XML document tree

  • Applies an XSL file to the XML document tree to produce HTML

  • Sends the HTML back to the client

The back-end server performs these functions:

  • Handles all calendar database requests

  • Processes the group scheduling engine (GSE) request queue

  • Monitors the reminder queue

  • Sends reminders using the ens and csnotifyd services

To configure DWP, you must set ics.conf parameters on both the front-end machine and back-end servers.


To Configure DWP Parameters on a Front-End Machine:

  1. On the front-end machine, log in as a user with administrator privileges.

  2. Change to the server-root/cal/bin directory where the Calendar Server command-line utilities are located and stop the Calendar Server using the stop-cal command.

  3. Change to the server-root/cal/bin/config/ directory and edit the ics.conf parameters shown in Table 3-5. (To configure multiple front-end machines that point to a single back-end server, see Multiple Front-End Machines.)


Table 3-5    DWP Configuration Parameters for a Front-End Machine 

Parameter

Description

service.http.enable = "yes"  

Set to "yes" (which is the default) to indicate that the local configuration requires the cshttpd service.  

csapi.plugin.calendarlookup = "y"  

Set to "y" (yes) to cause the CSAPI subsystem to load the Calendar Lookup Database plug-in.  

csapi.plugin.calendarlookup.name = "*"  

This parameter specifies the plug-in name. In the current release, Set to "*" (which is the default) to cause the CSAPI subsystem to load the Calendar Lookup Database plug-in.  

caldb.cld.type = "algorithmic"  

This parameter specifies the Calendar Lookup Database plug-in to use. The default is "local", but for a successful connection to the hostname server, set to "algorithmic".  

caldb.dwp.server.hostname.ip = "hostname"  

This parameter specifies the name (network address) of the back-end server where the DWP service is running. It is read by all services that use DWP, and at startup, each service tries to establish contact with the DWP service.

For example, if the server name is sesta, the parameter is:

caldb.dwp.server.sesta.ip = "sesta"  

caldb.dwp.server.hostname.port = "9779"  

This parameter specifies the port on which the DWP (csdwpd) service listens. The default is "9779". It is used with the caldb.dwp.server.hostname.ip value. The hostname part must be the same as in the caldb.dwp.server.hostname.ip. For example:

caldb.dwp.server.sesta.port = "9779"  

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

If caldb.cld.type is "algorithmic", this parameter specifies the expression used by the Calendar Lookup Database plug-in to determine the physical server where a specified calendar ID is stored. For example:

caldb.cld.server.sesta.regexpr = "^[^\n]"

matches all calendar IDs on the sesta server.  

  1. Change to the server-root/cal/bin directory where the Calendar Server command-line utilities are located and restart the Calendar Server using the start-cal command.

    On the front-end machine, the cshttpd and csadmind services are required.


To Configure DWP Parameters on a Back-End Server:
  1. On the back-end server, log in as a user with administrator privileges.

  2. Change to the server-root/cal/bin directory where the Calendar Server command-line utilities are located and stop the Calendar Server using the stop-cal command.

  3. Change to the server-root/cal/bin/config/ directory and edit the ics.conf parameters shown in Table 3-6.


Table 3-6    DWP Configuration Parameters for a Single Back-End Server 

Parameter

Description

service.dwp.enable = "yes"  

Enables the DWP (csdwpd) service. Causes the Calendar Server to start the csdwpd service when starting other services. Also, causes csdwpd service to listen on the port specified in service.dwp.port.

Default is "no" and must be reset to "yes".  

service.dwp.port = "9779"  

Specifies the port on which the csdwpd service listens.

Default is "9779".  

service.notify.enable = "yes"

service.admin.enable = "yes"

service.ens.enable = "yes"  

Enables each service on the back-end server. Must be set to "yes" (which is the default) to enable respective service.  

  1. Change to the server-root/cal/bin directory where the Calendar Server command-line utilities are located and restart the Calendar Server using the start-cal command.

    On the back-end server, the csdwpd, csadmind, enpd, and csnotifyd services are required.

You can now access the Calendar Server database on the back-end server from the front-end machine using Calendar Express. Here's how it works:

When the cshttpd service starts on the front-end machine, it initializes the Database subsystem. It loads the caldb.dwp.server.host.ip and caldb.dwp.server.host.port parameters from the ics.conf file and attempts to contact the back-end server using the host IP address and port values. If the contact is successful, the cshttpd service creates a pool of connections with the csdwpd service on the back-end server that are to used exclusively for DWP transactions.

Initially, the size of this connection pool is set to the value of the caldb.dwp.initconns. parameter, but the pool can grow to the maximum value specified by the caldb.dwp.maxcons parameter. Each connection in the pool is an HTTP/1.1 persistent connection, and if any connection fails, an error message is written to the log file.

If a DWP connection between the front-end machine and back-end server is broken (for example, the back-end server is restarted), the front-end machine tries to reconnect with the back-end server. Requests for calendar data fail while the DWP connection is broken, and data is not available until the connection is restored.


Multiple Front-End Machines

Figure 3-2 shows a Calendar Server configuration with multiple front-end machines and a single back-end server. The configuration parameters for both front-end machines (cal1.example.com and cal2.example.com) are identical and are described in To Configure DWP Parameters on a Front-End Machine:. You can add other front-end machines as well to distribute the front-end load.

Figure 3-2    Calendar Server Configuration for Multiple Front-End Machines and a Back-End Server





Managing LDAP Attributes


To manage the LDAP attributes used by Calendar Server, use the csattribute utility.


Listing LDAP Attributes

To list LDAP attributes for a user or resource, use the csattribute utility add command. For example, to list the LDAP attributes for the user TChang:

csattribute list TChang


Adding an LDAP Attribute

To add an attribute to the LDAP server, use the csattribute utility add command. For example, to add the LDAP attribute icsCalendar with the value Conference_Schedule to the user TChang:

csattribute -a icsCalendar=Conference_Schedule add TChang


Deleting an LDAP Attribute

To delete an attribute to the LDAP server, use the csattribute utility delete command. For example, to delete the LDAP attribute icsCalendar from TChang:

csattribute -a icsCalendar delete TChang



Managing the Group Scheduling Engine (GSE) Queue


Group scheduling allows a Calendar Server user to create an event such as a meeting and then invite other attendees. By using the free/busy lookup feature, the user can determine when an invitee is actually available for an event.

If an attendee is on the same Calendar Server, the event is scheduled in the attendee's calendar. If an attendee is not on the same Calendar Server, the invitation is sent via email. The attendee can then accept or decline the invitation.

Calendar Server users can also compare a group schedule by viewing attendees' calendars side-by-side.

To manage entries in the GSE queue, use the csschedule utility. You must run csschedule on the local machine where the Calendar Server is installed.


Listing Entries in the GSE Queue

To list entries in the GSE queue, use the csschedule utility list command. For example, to list all entries in the GSE queue:

csschedule list

To list the first ten entries stored in the GSE queue:

csschedule -c 10 list

To list all entries in the GSE queue for a calendar with the calid Holiday_Schedule:

csschedule -v list Holiday_Schedule


Deleting Entries in the GSE Queue

To delete entries in the GSE queue, use the csschedule utility delete command. For example, to delete all entries in the GSE queue:

csschedule -v delete

To delete the entry in the GSE queue for calendar calA with the first schedule time of 13:30:45 on 11/30/2001, an offset number of 1, the unique identifier 1111, the recurrence ID 0, and the sequence number 0:

csschedule -v -t 20011130T133045Z -o 1 -u 1111 -r 0 -n 0 delete calA



Monitoring the Calendar Server


To monitor Calendar Server activity, use the csstats and cstool utilities. This section describes the following tasks:


Listing Counter Statistics

The csstats utility displays statistical information from counter objects defined in the calendar configuration (counter.conf) files. Counter objects such as httpstat, authstat, wcapstat, or dbstat show information about the Calendar Server including:

  • Maximum number of concurrent connections and total number of connections

  • Total number of successful and failed logins and connections

  • Number of database reads, writes, and deletes

For more information about Calendar Server counter statistics, see Counters Configuration (counter.conf) File.

To list statistical information, use the csstats utility list command. For example, to display basic information about the counter objects and the types available:

csstats list

To list statistics specifically about the httpstat counter object:

csstats list http

To list statistics about the wcapstat counter object every 10 seconds for one hour:

csstats -i 360 -s 10 list wcap


Monitoring the Calendar Server Log Files

Each Calendar Server service writes status information to its own log file. Each log file is named after its associated service name, as shown in Table 3-7:


Table 3-7    Calendar Server Log Files

Service Name

Log File Name

csadmind  

admin.log  

csdwpd  

dwp.log  

cshttpd  

http.log  

csnotifyd  

notify.log  

Calendar Server log files are stored in the default log directory:

  • On Solaris systems:

    /var/opt/SUNWics5/logs

  • On UNIX systems other than Solaris:

    /var/opt/iPlanet/CalendarServer5/logs

  • On Windows NT systems:

    c:\Program Files\iPlanet\CalendarServer5\var\logs

Each log file is rolled-over to a new log file with a new name based on the configured time and size limits as follows:

ServiceName.TimeStamp.#

For example:

admin.20000801115354.1
http.20000801115354.2


Log Event Severity Levels

The Calendar Server provides eight levels of severity for events reported to the log files as described in Table 3-8.


Table 3-8    iPlanet Calendar Server Log Error Severity Levels

Severity Level

Meaning

EMERGENCY  

System is unusable. This level indicates events with the highest (most critical) severity.  

ALERT  

Action must be taken immediately.  

CRITICAL  

Critical condition.  

ERROR  

Error condition.  

WARNING  

Warning condition.  

NOTICE  

Normal, but signification condition. This is the default reporting level for each calendar service.  

INFORMATION  

Informational.  

DEBUG  

Debug-level message.  

A log event is represented by a single line that shows the associated timestamp, server host name, severity level, process name (process ID), type of event, priority, and description. You can specify the level of severity of the events that the Calendar Server reports to the log files by modifying certain configuration settings in the ics.conf file. For information, see Calendar Log Information Configuration.

You should inspect the log files on a regular basis for EMERGENCY, ALERT, CRITICAL, ERROR, and WARNING level errors and, if found, examine the events for possible problems with the operation of the Calendar Server. The NOTICE and INFORMATION level log events are generated during normal operation of the Calendar Server and are provided to help you monitor server activity.


Note When requesting technical support for Calendar Server, you might be asked to provide the log files for help in resolving problems.




Pinging the Calendar Server


To verify that a Calendar Server service is listening on a specified port number, use the cstool utility ping command. Pinging a service does not verify that a service is actually running but indicates if it can accept a socket connection.

The Calendar Server service options are:

  • http — HTTP Service (cshttpd)

  • admin — Administration Service (csadmind)


    Note In the current release, you cannot ping the Distributed Database Service (csdwpd), Event Notification Service (enpd), or Notification Service (csnotifyd).


To run cstool, the Calendar Server must be running.

For example, to ping the machine with the host name calserver to see if the cshttpd service is listening on port 80:

cstool -p 80 -h calserver ping http

By default, cstool waits 120 seconds for a response; however, you can change by value by using the -t timeout option.



Refreshing the Calendar Server Configuration


To force a Calendar Server service to refresh its configuration, use the cstool utility refresh command. If no service is specified, the command refreshes the configuration of all Calendar Server services.

To run cstool, the Calendar Server must be running.

For example, to force a local Calendar Server to refresh configurations for all services:

cstool refresh


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

Last Updated January 22, 2002