Chapter 3
Administering iPlanet Calendar Server
This chapter describes how to administer and maintain your iPlanet Calendar Server. It includes the following sections:
Administration Tools
iPlanet Calendar Server provides the following command line utilities for server administration to:
start and stop the iPlanet Calendar Server
enable and disable access to calendar data, to manage calendar users, events, and tasks, to monitor iPlanet Calendar Server activity, and to backup and restore calendar data.
control the server
These command line utilities should be executed only by the user who has administration rights to the system on which the Calendar Server is running. This user is typically the identity that the server will run as which was designated during installation, such as icsuser on Unix or the user with full administration privileges on Windows NT, such as administrator. Some command line utilities require the presence of a user designated as the iPlanet Calendar Server Administrator (such as calmaster) in the LDAP directory that stores user authentication and user preference information for this Calendar Server.
For more information, see the iPlanet Calendar Server Installation Guide.
To run these command line utilities, in most cases, you must change to the directory in which they are located (server-root/cal/bin), for example:
On Solaris: /opt/SUNWics5/cal/bin
On Unix systems other than Solaris: /opt/iPlanet/CalendarServer5/cal/bin
On Windows NT: c:\Program Files\iPlanet\CalendarServer5\cal\bin
Starting and Stopping the Server
You can start and stop the iPlanet Calendar Server the using:
Using start-cal and stop-cal
The start-cal and stop-cal utilities are located in the server-root/cal/bin directory. Both can be run either on a remote machine or the local machine where the iPlanet Calendar Server is installed.
To start the iPlanet Calendar Server, go to the server-root/cal/bin directory and type: start-cal on the command line. For example:
cd /opt/SUNWicsrv/cal/bin
Type: start-cal
To stop the iPlanet Calendar Server, go to the server-root/cal/bin directory and type: stop-cal on the command line. For example, enter:
cd /opt/SUNWicsrv/cal/bin
Type: stop-cal
Using the Services Panel (Windows NT only)
On Windows NT, you can open the Services dialog box from the Control Panel to start and stop the iPlanet Calendar Server. Refer to the documentation provided with the operating system for instructions.
Access Control
Access control is required for group scheduling in iPlanet Calendar Server 5.0.
The four major components of access control are:
Who - who is accessing it, also called the Universal Principal Name (UPN)
What - what is being accessed, such as a calendar or a calendar component (an event, task, or property)
How- what sort of access rights, such as read, write, or delete
Grant - if a particular access right is granted or denied
The UPN value for the logged in user is the user's login name combined with the domain to which the user belongs. For example, user "bill" in domain "siroe.com" has the UPN "bill@siroe.com".
Who
Who is the principal value for an access control entry and indicates to whom the ACE applies: an individual, user, a domain, or a type of user. There are four types of users.
All users is represented by the value: @
Primary owners of a calendar is represented by the value: @@p
Owners of a calendar is represented by the value: @@o
Non-owners of a calendar is represented by the value: @@n
A user is defined for an access control entry by a string using the following formats:
user
user@domain
@domain
@
@@{n|o|p}
where:
user refers to a specific user. For example, jsmith.
user@domain refers to a specific user at a specific domain. For example, jsmith@siroe.com.
@domain indicates any user in the specified domain. For example, @siroe.com would mean jsmith@siroe.com, sally@siroe.com, and anyone else at siroe.com.
@ means anybody.
@@ provides a mechanism to refer to other people with roles relative to the calendar. The currently defined roles are:
owner = @@o
primary owner = @@p
not an owner = @@n
Administrative Access
Administrators can be associated with a domain or with all domains. Administrators can perform any operation and are not subject to access control.
Anonymous Access
iPlanet Calendar Server supports the special principal name anonymous. The anonymous user can log in with any password and the access rights are set according to those defined for the password. The anonymous user name is not associated with any particular domain. To grant or deny access to an entire domain of users, use the form:
"@domain"
What
An ACE can be applied to the following targets:
an entire calendar
just the components (events or tasks) of the calendar
just the properties of the calendar (such as its name, description or owners).
Table 3-1 shows the target value specifiers of an ACE.
Table 3-1 ACE Target Value Specifiers
|
Value
|
Specifies
|
c
|
components (events and tasks)
|
p
|
properties (name, owners, etc.)
|
a
|
all means the entire calendar including both components and properties
|
How
Table 3-2 shows the types of access control supported by iPlanet Calendar Server 5.0.
Table 3-2 Access Control Types
|
Type
|
Description
|
|
c
|
Act on behalf of for cancel access. This type grants a user the right to cancel components to which attendees have been invited on behalf of the calendar's primary owner. This type of access does not need to be granted explicitly because it is implied when a user is designated as an owner (an owner other than the primary owner) of a calendar.
|
|
d
|
Delete access
|
|
e
|
Act on behalf of for reply access. This type grants a user the right to accept or decline invitations on behalf of the calendar's primary owner. This type of access does not need to be granted explicitly because it is implied when a user is designated as an owner (an owner other than the primary owner) of a calendar.
|
|
f
|
Free/busy (availability) access only. Free/busy access means that a user may see scheduled time on a calendar, but is not allowed to see the event details. Instead, just the words "Not Available" appears by a scheduled time block. Blocks of time without any scheduled events are listed also, with the word "Available" next to them.
|
|
i
|
Act on behalf of for invite access. This type grants a user the right to create and modify components in which other attendees have been invited on behalf of the calendar's primary owner. This type of access does not need to be granted explicitly because it is implied when a user is designated as an owner (an owner other than the primary owner) of a calendar.
|
|
r
|
Read access.
|
|
s
|
Schedule access. Requests can be made, replies will be accepted, and other iTIP scheduling interactions will be honored.
|
|
w
|
Write access. This includes adding new items, deleting items, and modifying existing items.
|
Grant
The grant attribute specifies whether to grant or deny privileges for a specified access type, such as d (delete) or r (read). Table 3-3 shows the grant and deny values.
Table 3-3 Grant or Deny Access Control
|
Value
|
Description
|
|
"g"
|
grants access.
|
|
"d"
|
denies access.
|
Access Control Entries
An Access Control Entry (ACE) is defined by the four parts described above: what, who, how, and grant. The four parts of an ACE are separated by a caret (^), for example:
jsmith^c^wd^g
where:
jsmith indicates who the ACE applies to
c indicates what is being accessed (in this case only the components of a calenadar are accessed)
wd indicates which access rights are to be granted or denied (in this case write and delete)
g indicates the specified access rights (write and delete) are granted
ACE String Examples
jsmith^a^r^g
The above example grants the userID jsmith read access to both components and calendar properties
jsmith^c^wd^g
The above example grants jsmith write and delete access to components only.
@siroe.com^c^sfr^g
The above example grants all users in the siroe.com domain privileges to schedule, free/busy, and read access to components only.
@@o^c^wd^g
The above example grants owners write and delete access to components only.
jsmith^a^sfdwr^d
The above example denies jsmith all access to calendar data.
@^c^r^g
The above example grants read access to all users.
Access Control Lists
There may be multiple ACEs that apply to a particular target (a calendar, its properties, or its event and todo components). An Access Control List (ACL) is a semicolon-separated list of all the ACE strings that collectively apply to a particular target.
Placement of ACEs in an Access Control List
When iPlanet Calendar Server reads an ACL, it uses the first ACE it encounters that either grants or denies access to the target. Therefore, the placement order of an ACL is significant and it should be ordered so that the more specific ACEs are positioned before the more general ACEs.
For example, suppose the first ACE in an ACL for the calendar jsmith:sports grants read access to all owners and that user bjones is one of the owners. Then, the server encounters a second ACE that denies bjones read access to this calendar. In this case, the server grants bjones read access to this calendar and ignores the second ACE because it is a conflict. Therefore, to ensure that an access right for a specific user such as bjones is honored, the ACE for bjones should be positioned in the ACL before more global entries such as an ACE that applies to all owners of a calendar.
|
Note
|
Calendars are created only when done so through the command line utilities or when a user logs in to the Calendar Server for the first time. Therefore, when a user sends a meeting request to another user, unless the user being invited has previously logged in to the Calendar Server or the administrator has explicitly created a calendar for the user being invited, the user sending the meeting request will receive an ACL error: Calendar not found.
|
Group Name Access Control
The Calendar Server Application Programming Interface (CSAPI) provides a call that accepts a group name and a "who" value in the URL form of a group name. The result of the call is a boolean value indicating whether or not the "who" value is a member of the group. For more information, see the iPlanet Calendar Server Programmers' Reference.
Built-in Access Control
A primary owner has access to everything in a calendar. No access control checks are required for a primary owner accessing their own calendar. Only the primary owner of a calendar can set Access Control Entries on that calendar.
iPlanet Calendar Server 5.0 does not specify how access control is handled in a hierarchy. Working on behalf of another is allowed only by other owners of a calendar on behalf of the primary owner.
Example Access Control Operation
Table 3-4 shows an example of an ACL for the calendar with calendar ID "bill".
Table 3-4 Sample iPlanet Calendar Server ACL
|
What
|
who
|
how
|
grant
|
|
bill
|
sally@siroe.com
|
s
|
d
|
|
bill
|
@siroe.com
|
s
|
g
|
|
bill
|
ldap://...
|
s
|
g
|
|
bill
|
@siroe.com
|
r
|
g
|
|
bill
|
anonymous
|
f
|
g
|
If sally@siroe.com attempts an operation that requires read access to calendar "bill", the operation returns "g" (grant) because there is an ACE that grants anyone in the domain siroe.com read access to calendar "bill". If, however, sally@siroe.com attempts to schedule with calendar "bill", the operation returns "d" (deny) because the first entry in the ACL denies scheduling access to the exact UPN sally@siroe.com.
Suppose jimbo@company22.com attempts to schedule with "bill". The "who" values for the first and second ACEs are not in URL form, and their domains do not match the principal owner's domain. In this case, they are ignored. The third "who" value is in the form of a URL. Therefore, a CSAPI call is made to determine whether or not jimbo@company22.com is a member of the "who" value. If jimbo@company22.com is a member of the "who" value, then scheduling permission is granted. Otherwise, scheduling permission is denied because no other ACE grants or denies scheduling access.
Mapping iPlanet Calendar Server 2.x Access Control Data
Included with iPlanet Calendar Server 5.0 is a migration utility called ics2migrate (located in the server-root\cal\bin directory) that lets you automatically migrate calendar database and LDAP user information from version 2.x to version 5.0. For details on using ics2migrate, see Chapter 4 of the iPlanet Calendar Server Installation Guide.
In iPlanet Calendar Server 2.x, the following access control rules applied:
Primary Owner has full access - no verification checking.
Other Owners (synonymous with all owners) had full access to events and tasks, but only read access to calendar properties.
Table 3-5 describes how to migrate calendar access control data from iPlanet Calendar Server version 2.x to version 5.0.
Table 3-5 iPlanet Calendar Server version 2.x Access Control Migration
|
Read
|
Write
|
Who
|
What
|
How
|
Grant
|
|
Public
|
Private
|
@
|
<calid>
|
R
|
1
|
|
|
|
@@O
|
<calid> COMPONENTS
|
WD
|
1
|
|
Private
|
Public
|
@
|
<calid> COMPONENTS
|
WD
|
1
|
|
|
|
@@O
|
<calid>
|
R
|
1
|
|
Public
|
Public
|
@
|
<calid> COMPONENTS
|
WD
|
1
|
|
|
|
@
|
<calid>
|
R
|
1
|
|
Private
|
Private
|
@@O
|
<calid>
|
R
|
1
|
|
|
|
@@O
|
<calid> COMPONENTS
|
WD
|
1
|
|
Primary
|
Public
|
@
|
<calid> COMPONENTS
|
WD
|
1
|
|
Primary
|
Private
|
@@O
|
<calid> COMPONENTS
|
WD
|
1
|
|
Public
|
Primary
|
@
|
<calid>
|
R
|
1
|
|
Private
|
Primary
|
@@O
|
<calid>
|
R
|
1
|
Access Control Rules
Supporting iTIP access control is separate from how iPlanet Calendar Server implements Access Control Entries. Some examples of iTIP rules are:
The organizer is the only attendee of a group event that can redistribute a change of the event to other attendees.
Attendees can only change the parameters to their own attendee entries and must resubmit changes to the attendee line back to the organizer.
Attendees can delegate their attendance to one or more other people. The delegates may not be listed in the attendee list of the event as sent by the organizer.
Party crashing results in new, uninvited attendees being added to the attendee list. The organizer must approve the party crashing and will redistribute the updated event.
Calendar Locate Mechanism
The calendar locate mechanism is a plug-in that enables an arbitrary mechanism decide where a physical calendar resides. Its purpose is to bypass the need to know where a user's physical calendar is stored, but instead to manage it programmatically.
The Database Wire Protocol calls into Calendar Lookup service to fully qualify a calendar ID (calid). By fully qualifying the calid, it can determine from the url the physical location of the calendar, along with its access protocol. For more information, see Horizontal Scalability and Calendar Locate Mechanism Configuration.
iPlanet Calendar Server 5.0 provides the following implementations of the Calendar Lookup service:
Using the Command Line Utilities
This section describes the tasks you can perform to administer iPlanet Calendar Server using the command line utilities. The examples in this section use the most commonly used commands and options. For complete details on the command line utilities syntax and usage, see Appendix , "Command Line Utilities."
This section includes the following topics:
Table 3-6 lists the command line utilities and their purpose.
Table 3-6 Command Line Utilities
|
Use...
|
To...
|
|
csattribute
|
Manage the calendar attributes in the LDAP server.
|
|
csbackup
|
Backup individual calendars, users, and the calendar database.
|
|
cscal
|
Manage calendars and their properties.
|
|
cscomponents
|
Manage components (events and tasks) in a calendar.
|
|
csdb
|
Manage calendar databases.
|
|
csexport
|
Export a calendar in ICalendar or XML format.
|
|
csimport
|
Import a calendar in ICalendar or XML format.
|
|
csplugin
|
View, enable, or disable configured Calendar Server API (CSAPI) plug-ins.
|
|
csresource
|
Manage calendar resource objects such as conference rooms and video equipment.
|
|
csrestore
|
Restore individual calendars, users, and the calendar database.
|
|
csschedule
|
Manage schedule entries in the Group Scheduling Engine (GSE) queue.
|
|
csstart
|
Start the iPlanet Calendar Server.
|
|
csstats
|
Display counters in a iPlanet Calendar Server.
|
|
csstop
|
Stop the iPlanet Calendar Server.
|
|
cstool
|
General purpose tool to ping a running iPlanet Calendar Server instance to control and monitor the server, and to force the server to refresh its configuration.
|
|
csuser
|
Manage calendar users.
|
Managing Calendar Users
The csuser command line utility let you perform the following administrative tasks on calendar users:
Creating a Calendar User
Use the csuser utility's create command to create a calendar user. For example, to create the calendar user JSmith using the default configuration settings, enter the following command on the command line:
csuser -g John -s Smith -y password -c calJSmith create JSmith
where:
-g John represents the user's givenname (first name).
-s Smith represents the user's surname (last name).
-y password represents the user's password.
-c calJSmith represents the user's default calendar ID (calID).
create JSmith adds an entry with the USERID JSmith to the LDAP directory that stores your user information.
|
Note
|
Calendars are created only when done so through the command line utilities or when a user logs in to the Calendar Server for the first time. Therefore, when a user sends a meeting request to another user, unless the user being invited has previously logged in to the Calendar Server or the administrator explicitly has created a calendar for the user being invited, the user sending the meeting request will receive the error: Calendar not found.
|
Deleting a Calendar User
Use the csuser utility's delete command to delete a user from the iPlanet Calendar Server.
|
Note
|
The delete command removes all of the user's information from the LDAP server. (Calendar database information can be recovered from a calendar database that has been saved to a backup. See Backing-Up the Calendar Database.)
|
For example, to delete JSmith from the iPlanet Calendar Server, enter the following command:
csuser delete JSmith
Enabling a Calendar User
Users are automatically enabled for calendaring when they log on to the iPlanet Calendar Server for the first time, if they are not already enabled. In such cases, the calendar ID (CALID) of the user's default calendar is the user's USERID unless a calendar by that name already exists. For example, if JSmith is not enabled for calendaring and logs on to the iPlanet Calendar Server for the first time, the server enables JSmith for calendaring automatically and assigns this user a default calendar with the CALID JSmith. Additionally, the prefix JSmith is assigned to the CALID of each subsequent calendar that JSmith creates. For example, if JSmith, who was enabled automatically, creates a calendar called sports, the assigned CALID is JSmith:sports.
Use the csuser utility's enable command to let a user access iPlanet Calendar Server data and to assign specific configuration settings such as a user's default calendar. For example, to enable JSmith for calendaring and assign a default calendar, enter the following command:
csuser calendarA enable JSmith
The above command enables JSmith to log on to the iPlanet Calendar Server.
Disabling a Calendar User
Use the csuser utility's disable command to prevent a user from logging into the iPlanet Calendar Server. The disable command prohibits a user from accessing calendar data, but does not remove the user's information from the calendar database.
For example, to disable JSmith from access to iPlanet Calendar Server data, enter the following command:
csuser disable JSmith
Checking if a User is Enabled
Use the csuser utility's check command to determine if a specified user is enabled to access calendar data. For example, to check if JSmith is enabled for calendaring using the default configuration settings, enter the following command:
csuser check JSmith
Displaying User Information
Use the csuser utility's list command to list all calendar-enabled users or to view the calendar attributes of a specified user.
For example:
To list all users enabled for calendaring, enter the following command:
csuser list
To view all of the calendar attributes of a single user, such as JSmith, enter:
csuser -v list JSmith
Resetting a User's Calendar Attributes
Use the csuser utility's reset command to restore the default settings of all calendar LDAP attributes for a specified user. For example, to reset all calendar attributes of JSmith to the default configuration settings, enter the following command:
csuser reset JSmith
Managing Calendars
This section provides examples that show how to perform administrative tasks on calendar data using the cscal utility's commands. You must run the cscal utility on the local machine where the iPlanet Calendar Server is installed.
The cscal utility lets you perform the following tasks:
create or delete a calendar
disable or enable a calendar
modify properties of an existing calendar, such as its name and owners and who can access it
display calendar information
|
Note
|
Calendar Ids are case sensitive. For example, if you type JSMITH and the calendar ID is actually jsmith, you will not find the right calendar. This distinction differs from email addresses which are not case sensitive, such as jsmith@siroe.com which is equivalent to JSMITH@SIROE.COM.
|
Creating a Calendar
Every calendar has a primary owner and, optionally, other owners. A primary owner can update the events and tasks of a calendar as well as change the properties of a calendar, such as the name, description, additional owners, and display settings. Other owners can update a calendar's events and tasks, but cannot change a calendar's properties. By default, owners other than the primary owner are granted the access control permissions to a calendar for group scheduling that enable them to act on behalf of the primary owner. Other owners of a calendar can create events and todos and invite attendees, and they can accept or decline published events and todos from other calendar users on behalf of the primary owner. For example, a manager can designate other owners who can make scheduling changes to the manager's (primary owner) calendar such as creating events and accepting or declining events proposed by others. The default access control permissions are defined in the ics.conf file by the setting calstore.calendar.default.acl. For more information, see Calendar Store Configuration.
Use the cscal utility's create command to create a calendar. For example, to create a calendar with the visible name exampleA that is owned by JSmith and uses the default access control settings for group scheduling, enter the following command on the command line:
cscal -n exampleA -o JSmith create calA
where:
-n exampleA specifies that exampleA is the viewable name of the calendar.
-o JSmith specifies the USERID of the primary owner.
calA is the name that will be used as the second part of the calendar's CALID (for example, JSmith:calA).
The following command creates a calendar similar to the example above, but also associates it with the category sports, enables double booking, and specifies RJones as an other owner.
cscal -n exampleA -o JSmith -g sports -k yes -y RJones create calA
where:
The following command creates a calendar similar to the example above and sets specific access control settings for group scheduling:
cscal -n exampleA -o JSmith -a "@@o^asfr^g" create calA
where:
-a "@@o^a^sfr^g" grants owners schedule, free/busy, and read access privileges to both the components and calendar properties of this calendar for group scheduling.
Deleting Calendars
Use the cscal utility's delete command to delete one or more calendars from the iPlanet Calendar Server.
|
Note
|
The delete command removes all of the calendar's information from the calendar database and cannot be undone. (Database information, however, can be recovered from a database that has been saved to a backup. See Backing-Up the Calendar Database.)
|
The cscal utility lets you delete a single calendar or multiple calendars. For example, to delete a specific calendar with the CALID calendarA, enter the following command:
cscal delete calendarA
The following example deletes all calendars whose primary owner is JSmith:
cscal -o JSmith delete
Enabling a Calendar
Use the cscal utility's enable command to allow users to access a calendar. For example, to enable calendarA using the default configuration settings, enter the following command:
cscal enable calendarA
The following command enables the calendar calA and does not allow double booking:
cscal -k no enable calA
Disabling a Calendar User
Use the cscal utility's disable command to prevent users from accessing one or more calendars. The disable command prohibits users from accessing the calendar's data, but does not remove its information from the calendar database.
For example, to prevent users from accessing calendarA on the iPlanet Calendar Server, enter the following command:
cscal disable calendarA
Modifying Calendar Properties
Use the cscal utility's modify command to change the properties of a calendar. For example, to change the group scheduling access control settings of calendarA and specify that RJones is an other owner, enter the following command:
cscal -a "@@o^c^wd^g" -y RJones calendarA
where:
Removing Properties from a Calendar
To remove a property value, specify two double quotes ("") as the value of the property option using the modify command.
For example, to remove a description from calendarA:
cscal -d "" modify calendarA
To remove all categories from calendarA:
cscal -g "" modify calendarA
To remove other owners from calendarA:
cscal -y "" modify calendarA
Displaying Calendars
Use the cscal utility's list command to list all calendars, all calendars owned by a user, or all properties of a specific calendar. For example, to list all calendars in the calendar database, enter the following command:
cscal list
To list all calendars owned by JSmith, enter:
cscal -o JSmith list
To list all the properties of a calendar with the CALID calendarA, enter:
cscal -v list calendarA
Managing Calendar Events and Tasks
The cscomponents utility lets you:
You must run the cscomponents utility on the local machine where your iPlanet Calendar Server is installed.
Use the cscomponents utility's list command to list all events and tasks in a calendar. For example, to list the events and tasks in calendarA, enter the following command:
cscomponents -v list calendarA
where:
-v specifies verbose mode which displays all information available about the events or tasks.
Use the cscomponent utility's delete command to remove events and tasks in a calendar. For example, to delete all events and tasks in calendarA occurring in 1998, enter the following command:
cscomponents -s 19980101T000000Z -e 19981231T000000Z delete calendarA
where:
To delete all calendar events and tasks from calendarA, enter:
cscomponents -s 0 -e 0 delete calendarA
where specifying 0 for both start and end dates indicates the beginning and end of time.
Managing Calendar Databases
Use the csdb command line utility to view the statistics of the local calendar databases, and to create, delete, backup and restore the calendar database. You must run the csdb utility on the local machine where your iPlanet Calendar Server is installed. This section describes how to use csdb to view database statistics and to create and delete databases. For csdb backup and restore options, see Backup and Restore Procedures.
|
Caution
|
You must stop the Calendar Server before restoring, creating, or deleting the calendar database.
|
The csdb utility lets you choose from three types of databases:
caldb (calendar)
sessdb (session)
statdb (statistics)
For example:
To view calendar database status and statistical information for all database types, enter the following command:
csdb list
To create all new calendar databases if they were accidentally deleted, enter:
csdb create
To list information about the calendar database in the current directory in verbose mode, enter:
csdb -v -t caldb list
To delete the all databases before restoring it from a backup, enter:
csdb delete
To attempt to recover a damaged calendar database in the current directory, enter the following command:
csdb -t caldb recover
Importing and Exporting Calendar Data
The csexport and csimport command line utilities let you export and import calendar data to a text file using ICalendar or XML format.
|
Note
|
The csexport and csimport utilities must be run locally on the machine where your iPlanet Calendar Server is installed and can be executed while the server is either running or stopped.
|
Exporting Calendar Data
Use csexport to export a calendar to a file. The file name extension (.ics or .xml) that you specify for the output file determines which format is used. For example:
To export the calendar with the CALID JSmithcal in ICalendar (text/calendar MIME) format to a file named jsmith.ics, enter the following command:
csexport -c JSmithcal calendar jsmith.ics
To export the calendar JSmithcal in XML (text/xml MIME) format to a file named jsmith.xml, enter:
csexport -c JSmithcal calendar jsmith.xml
Importing Calendar Data
Use csimport to import calendar data from a file previously saved using the csexport utility. The file name extension of the import file (.ics or .xml) indicates the format in which it was saved. For example:
To import calendar data to the CALID JSmithcal from the file jsmith.ics that was saved in ICalendar (text/calendar MIME) format, enter the following command:
csimport -c JSmithcal calendar jsmith.ics
To import data into the calendar JSmithcal from a file named jsmith.xml that was saved in XML (text/xml MIME) format, enter:
csimport -c JSmithcal calendar jsmith.xml
|
Note
|
If the specified CALID already exists, its data is cleared before the new data is imported.
|
Managing LDAP Attributes
Use the csattribute command line utility to manage the LDAP attributes used by Calendar Server.
For example:
To add the LDAP attribute icsCalendar with the value calA to the userID userA, enter the following command on the command line:
csattribute -a icsCalendar=calA add userA
To delete the LDAP attribute icsCalendar from userA, enter:
csattribute -a icsCalendar delete userA
Managing Calendar Resources
Use the csresource command line utility to manage the properties of a calendar associated with a resource object such as meeting rooms and equipment. You can run the csresource utility on the local machine where your iPlanet Calendar Server is installed or from remote machine. This section describes how to use csresource to view, add, delete, enable, or disable calendar resources.
For example:
To display a list of all resource calendars on the Calendar Server and their LDAP attributes, enter the following command on the command line:
csresource list
To create a resource calendar with the calendar ID Room1A and the viewable name (LDAP cn attribute) Galaxy, enter:
csresource -c Room1A create Galaxy
To following command performs the same action as the above example, but also allows double booking on this calendar:
csresource -k yes -c Room1A create Galaxy
The following command performs the same action as the above examples, but also specifies group scheduling access rights that let anyone read and write to it:
csresource -a "@^a^rw^g" -k yes -c Room1A create Galaxy
To delete the Galaxy resource, enter:
csresource delete Galaxy
To disable the Galaxy resource, enter:
csresource disable Galaxy
To enable the Galaxy resource, enter:
csresource enable Galaxy
To display a list of all LDAP attributes for the calendar Galaxy, enter:
csresource -v list Galaxy
Managing the Calendar Group Scheduling Queue
Use the csschedule command line utility to manage entries in the Group Scheduling Engine (GSE) queue. You must run the csschedule utility on the local machine where your iPlanet Calendar Server is installed. This section describes how to use csschedule to view or remove entries stored in the GSE queue.
For example:
To list all entries in the GSE queue, enter the following command on the command line:
csschedule list
To list the first ten entries stored in the GSE queue, enter:
csschedule -c 10 list
To list all entries in the GSE queue for a calendar with the calid calendarA, enter:
csschedule -v list calendarA
Managing Plug-ins
Use the csplugin command line utility to manage the plug-ins that have been configured for use with your Calendar Server.
Table 3-7 shows of the types of plug-ins supported by iPlanet Calendar Server 5.0.
Table 3-7 Plug-in Types Supported
|
Type
|
Description
|
|
ac
|
Augments or overrides the default group scheduling access control mechanism.
|
|
attr
|
Augments or overrides the mechanism for storing and retrieving user attributes.
|
|
auth
|
Augments or overrides the login authentication mechanism.
|
|
locate
|
Retrieves a calendar ID for the specified qualified URL.
|
|
lookup
|
Augments or overrides the default calendar lookup mechanism.
|
|
xlate
|
Augments or overrides the format translation of incoming and outgoing data.
|
For example:
To list all plug-ins configured for this server instance, enter the following command on the command line:
csplugin list
To activate the lookup type plug-in with the filename mylookup, enter:
csplugin activate -t lookup mylookup
To disable the group scheduling access control type plug-in with the filename xyz_access and delete it from the plugin directory, enter:
csplugin deactivate -t ac xyz_access -r
Backup and Restore Procedures
This section describes how to use the command line utilities to backup and restore iPlanet Calendar Server data:
Use csbackup to back up a specified calendar, a user's default calendar, or the calendar database.
Use csrestore to recover a specified calendar, a user's default calendar, or the calendar database.
The csexport and csrestore utilities must be run locally on the machine where iPlanet Calendar Server is installed and can be executed while the server is running or stopped.
|
Note
|
The version file caldb.conf located in the specified backup directory shows the version number of the database that was backed up.
Do not attempt to restore data backed up using iPlanet Calendar Server version 2.x because the utilities provided in versions 2.x and 5.0 are incompatible and doing so could result in data loss.
|
This section includes the following topics:
Backing-Up a Specified Calendar
Use the csbackup utility's calendar command to backup a calendar to a plain text file using ICalendar or XML format. The file name extension (.ics or .xml) that you specify for the output file determines which format is used. For example:
To backup the calendar JSmithcal in ICalendar (text/calendar MIME) format, enter the following command:
csbackup -c JSmithcal calendar jsmith.ics
To backup the calendar JSmithcal in XML (text/xml MIME) format, enter:
csbackup -c JSmithcal calendar jsmith.xml
Restoring a Specified Calendar
You can restore a specified calendar the using the csrestore utility's:
calendar command
database command
Restoring a Calendar from a File
Use the csrestore utility's calendar command to restore a calendar that was saved to a backup file using the csbackup utility. The file name extension (.ics or .xml) of the backup file indicates the format in which it was saved. For example:
To restore the calendar JSmithcal that was saved in ICalendar (text/calendar MIME) format to the file jsmith.ics located in the backupdir directory, enter the following command:
csrestore -c JSmithcal calendar backupdir/jsmith.ics
To restore the calendar JSmithcal that was saved in XML (text/calendar MIME) format to the file jsmith.xml located in the bcakupdir directory, enter:
csrestore -c JSmithcal calendar backupdir/jsmith.xml
Restoring a Calendar from a Database
Use the csrestore utility's database command to restore a calendar from a database that was saved to a backup directory using the csbackup utility. For example, to restore the calendar JSmithcal from the backup database directory backupdir, enter the following command:
csrestore -c JSmithcal database backupdir
Backing-Up a User's Default Calendar
Use the csbackup utility's defcal command to backup a user's default calendar to a plain text file using ICalendar or XML format. The file name extension (.ics or .xml) that you specify for the output file determines which format is used. For example:
To backup calendar user JSmith's default calendar in ICalendar (text/calendar MIME) format to a file named jsmith.ics, enter the following command:
csbackup -a JSmith defcal jsmith.ics
To backup calendar user JSmith's default calendar in XML (text/xml MIME) format to a file named jsmith.xml, enter the following command:
csbackup -a JSmith defcal jsmith.xml
Restoring a User's Default Calendar
Use the csrestore utility's defcal command to restore a a user's default calendar that was saved to a backup file using the csbackup utility. The file name extension (.ics or .xml) of the backup file indicates the format in which it was saved. For example:
To restore calendar user JSmith's default calendar that was saved in ICalendar (text/calendar MIME) format to a file named jsmith.ics located in the backup directory backupdir, enter the following command:
csrestore -a JSmith defcal backupdir/jsmith.ics
To restore calendar user JSmith's default calendar that was saved in XML (text/xml MIME) format to a file named jsmith.xml located in the backup directory backupdir, enter the following command:
csrestore -a JSmith defcal backupdir/jsmith.xml
Backing-Up the Calendar Database
Use the csbackup utility's database command to backup the calendar database to an output directory. For example, to backup the calendar database to a directory named backupdir, enter the following command:
csbackup database backupdir
Restoring the Calendar Database
The following command line utilities let you restore the calendar database:
The csrestore and csdb commands must be run on the local machine on which your iPlanet Calendar Server is installed.
|
Caution
|
You must stop the iPlanet Calendar Server before restoring or recovering the calendar database. (The server may be running, however, when you backup the database.)
|
Use the csrestore utility's database command to restore a calendar database that was saved to a backup directory using the csbackup utility. For example, to restore the calendar database that was saved to a backup directory named backupdir, enter the following command:
csrestore database backupdir
Use the csdb utility's recover command to recover a calendar database that was accidentally corrupted or deleted. For example, to attempt to recover a damaged calendar database in the default directory (for example, /var/opt/SUNWics5/csdb on Solaris or c:\Program Files\iPlanet\CalendarServer\var\csdb), enter the following command:
csdb recover
Using Solstice or Legato Software to Backup iPlanet Calendar Server
We recommend using the Sun Solaris Solstice Backup or the Legato file backup and restore products to backup the iPlanet Calendar Server. If you do not have Solstice Backup, use the command line utilities csbackup, csdb, or csexport. See http://docs.sun.com for documentation on Solstice Backup.
|
Note
|
Solstice Backup and the Legato Networker product are identical. The instructions here are applicable to both products. Read the Solstice Backup or Legato Networker documentation set before attempting to backup the iPlanet Calendar Server.
|
iPlanet Calendar Server provides backup and restore procedures that let you:
backup and restore the entire database or specified calendars
recover a calendar database that was damaged or lost such as through hardware failure.
migrate data from one iPlanet Calendar Server to another.
Backing Up iPlanet Calendar Server Data
Use the following steps to backup calendar data:
Run the command line utilities to backup the calendar database or specified calendars using the -l option.
- For more information, see Backup and Restore Procedures).
- The backup procedure creates a backup directory under the current directory. This directory is not the actual directory calendar data is stored, but a directory image of how calendars are stored. The files in this directory are empty and are used only to provide information to the backup program on how calendars will be stored on the backup media. If the backup directory already exists, it is synchronized with the directory structure of the current hierarchy.
Start Solstice or Legato backup.
- You can use the backup program's graphical user interface or the save command to back up calendar data.
|
Note
|
Do not use the Solstice Backup incremental backup feature because the backup directory is only an image of the folder structure and contains no actual data. The incremental backup feature is not supported in iPlanet Calendar Server.
|
- Important: The .nsr files generated by the command line utilities contain standard Networker directives and should never be modified.
Automate the backup procedure.
- The preceding steps describe how to run a backup manually. It is recommended that you set up the backup program's backup command to run the iPlanet Calendar Server csbackup command line utility before the running backup program's save command to achieve an automated backup process.
|
Note
|
You cannot use Networker to backup a calendar with a name that contains non-ASCII characters or the forward slash (/).
|
Restoring iPlanet Calendar Server Data
Use the Solstice nwrestore feature or the recover command to restore backed up calendar information. If you use nwrestore, you will receive the message:
"File already exists. Do you want to overwrite, skip, backup, or rename?"
Choose overwrite. (This message appears because the backup tree is just the directory hierarchy, that is, it consists of empty files and stays that way permanently.)