| Sun ONE Calendar Server 6.0 Administrator's Guide |
Chapter 2
Managing Calendar Server Users and CalendarsThis chapter describes how to use the Calendar Server command-line utilities to provision and manage users and calendars, including both user calendars and resource calendars.
This chapter contains these sections:
To provision and manage Calendar Server users and calendars, use the following command line-utilities:
- The csuser utility manages calendar user information stored in an LDAP directory server and the calendar database.
- The cscal utility manages calendars and their properties in the calendar database.
- The csresource utility manages calendars for resources such as conference rooms or equipment stored in the LDAP server and the calendar database.
To run the command-line utilities, you must log in as a user who has administrative rights to the system where Calendar Server is running. For more information, see Chapter 11, "Calendar Server Command-Line Utilities".
Provisioning New Calendar Server UsersThis section provides the following information about provisioning new Calendar Server users:
Directory Server Requirements
Calendar Server requires that a calendar user be stored in a directory server. Calendar Server then uses the directory server for user authentication and for the storage and retrieval of user preferences.
The Calendar Server default installation supports users defined in an LDAP directory, such as the Sun ONE Directory Server. If your users are already stored in an LDAP directory, you can simply upgrade your directory server to Sun ONE Directory Server, which supports the schema extensions that allow users to access Calendar Server.
For information about installing and configuring Sun ONE Directory Server, see the following documentation Web site:
http://docs.sun.com/coll/S1_DirectoryServer_52
You can also modify your directory schema manually to allow your users to access Calendar Server data. For information, see the Sun ONE Calendar Server 6.0 Installation Guide for Solaris Operating Systems.
Required LDAP mail Attribute for Calendar Server Users
Calendar Server 6.0 (and later) requires users to have the LDAP mail attribute for both user and resource calendars (for example, for meeting rooms or equipment such as a notebook computer or overhead projector). Each resource calendar must have an email address, even if the email address is not actually used.
You might specifically need to add the LDAP mail attribute as follows:
Existing 5.x Installation. Before you run the cs5migrate migration utility, add the mail attribute to users for both user and resource calendars. To add the mail attribute, use the Calendar Server csattribute utility or a utility such as the Directory Server ldapmodify utility.
New 6.0 Installation. Provision the LDAP mail attribute for existing users for both user and resource calendars using the Calendar Server csattribute utility or a utility such as the Directory Server ldapmodify utility.
If you create new calendars or users after installation, use the required -m email option to specify an email address when you run these Calendar Server utilities:
- csresource utility for new resource calendars
- csuser utility for new users
For information about the cs5migrate migration utility, refer to the Sun ONE Calendar Server 6.0 Installation Guide for Solaris Operating Systems.
For information about ldapmodify utility, refer to the Sun ONE Directory Server Resource Kit Tools Reference, which is available on the following Web site:
http://docs.sun.com/coll/S1_DirectoryServer_52
Example: Adding the email LDAP Attribute to a Resource Calendar
The following example adds the LDAP mail attribute for a conference room named “Room100” on the sesta.com server. This example uses Sun ONE Messaging Server. If you are using another email server, refer to that product’s documentation for the equivalent process.
- Add the mail attribute to the LDAP server using the csattribute utility:
# ./csattribute -a mail=Room100@sesta.com add Room100
- To check that the attribute has been set, use the csattribute list command with the -v (verbose) option:
# ./csattribute -v list Room100
...
cn=Room 100,ou=conferenceRooms,dc=sesta,dc=com has mail: Room100@sesta.com
Example: Setting up the bitbucket Channel for the Resource Email
The following examples set up the bitbucket channel for Sun ONE Messaging Server or the equivalent for Sendmail for the email generated for resource calendars. These examples use a resource named “Room100” on the sesta.com server. If you don’t set up the bitbucket channel (or equivalent), you will need to periodically delete the email messages sent to the resource calendar.
If you are using Sun ONE Messaging Server, perform these steps:
If you are using Sendmail, perform these steps:
Email Alias (mailalternateaddress Attribute)
If you need to setup an email aliases for a calendar user, use the LDAP mailalternateaddress attribute. The LDAP mail attribute provides the primary mail address, and the LDAP mailalternateaddress attribute is used for email aliases. Both attributes map the mail addresses to the user’s calendar ID (calid).
For example, to add the mailalternateaddress attribute for a user named John Smith with these values:
Use these Calendar Server utility commands:
# ./csuser -g John -s Smith -y password -l en -m john.smith@sesta.com -c johnsmith create johnsmith
# ./csattribute -a mailalternateaddress=johns@sesta.com add johnsmith
# ./csattribute -a mailalternateaddress=jsmith@sesta.com add johnsmith
Calendar Identifiers (calids)
Each calendar in the Calendar Server database is identified by a unique calendar identifier (ID) or calid. The format for a calid is:
userid[@domain][:calendar-name]
where:
userid is the user ID.
domain is an optional domain name for the user. The default is the value specified by the service.defaultdomain parameter.
calendar-name is an optional calendar name
Calendar IDs are case sensitive. For example, JSMITH is not equivalent to jsmith. (This distinction differs from email addresses, which are not case sensitive. For example, jsmith@sesta.com is equivalent to JSMITH@SESTA.COM.)
A calendar ID cannot contain spaces and is limited to the following characters:
Examples of calendar IDs are jsmith, jsmith@calendar.sesta.com:new-cal, and jsmith:private_calendar.
Because the user ID is part of the calid, the user ID should not contain spaces (for example, j smith). A user with a user ID that contains a space can log into Calendar Server, but a space can cause subsequent problems.
Calendar Lookup Database (CLD) Plug-in
If the calendar database is distributed over several back-end servers, Calendar Server uses a plug-in to determine the actual server where a calendar is stored. Calendar Server accesses the calendar data on the back-end server using the Database Wire Protocol (DWP). DWP is an internal protocol that runs as the csdwpd service and provides the networking capability for the calendar database.
Calendar Server loads the plug-in, depending on the value of the caldb.cld.type parameter in the ics.conf file:
Checking if a User is Enabled for Calendaring
To determine if a specific user exists in your directory server and is enabled to access Calendar Server data, use the csuser utility check command.
For example, to check if JSmith is enabled for calendaring:
csuser check JSmith
If the check command indicates that a user does not exist in your LDAP directory server, you must create a directory server entry for the user.
Provisioning a New User
The csuser utility can create an entry in the LDAP directory server and enable a user for calendaring. You can also use Sun ONE Directory Server utilities such as ldapsearch and ldapmodify. For information about these utilities, see the Sun ONE Directory Server documentation on the following Web site:
http://docs.sun.com/coll/S1_DirectoryServer_52
If the user already exists in your LDAP directory, a new calendar can be created for the user either manually or automatically:
- Manually - Use the cscal utility create command to create a new calendar for the user. See "Creating a New Calendar".
- Automatically - The first time a new user logs into Calendar Server, Calendar Server automatically creates a new default calendar for the user if local.autoprovision is set to “yes” (the default) and the domain has been assigned the calendar service. Calendar Server uses the user’s user ID for the calendar ID (calid) of the new calendar, unless a calendar by that name already exists.
For example, if JSmith logs into Calendar Server for the first time, Calendar Server automatically creates a default calendar with JSmith as the calid.
Calendar Server also assigns the prefix JSmith to the calid of each subsequent calendar that JSmith creates. For example, if JSmith later creates a new calendar named meetings, the calid is JSmith:meetings.
If a user sends a request to another user who has not been enabled for calendaring (that is, the user does not have a default calendar), Calendar Server returns the “Calendar not found” error to the user sending the request.
Creating a New Calendar
To create a new calendar, use the cscal utility create command. The user (user ID) must already exist in the directory server.
If your site is using the LDAP Calendar Lookup Database (CLD) plug-in, you must create a new calendar on the same back-end server where the user’s calendars reside (or will reside), as indicated by the user’s icsDWPHost LDAP attribute. If you try to create a calendar on a different back-end server, the cscal utility returns an error. For information about the LDAP CLD plug-in, see "Configuring the LDAP Calendar Lookup Database (CLD) Plug-in".
For example, to create a new calendar with the calendar ID (calid) JSmith:
cscal -o JSmith -n JohnSmithCalendar create JSmith
where:
To create a calendar with the viewable name Hobbies that is owned by JSmith and uses the default access control settings for group scheduling:
cscal -n Hobbies -o JSmith create Personal
where:
The following example creates a new calendar similar to the previous example, but it also associates the calendar with the category named sports, enables double booking, and specifies RJones as another owner:
cscal -n Hobbies -o JSmith -g sports -k yes -y RJones create Personal
where:
The following example creates a calendar similar to the previous example, but it also sets specific access control settings for group scheduling:
cscal -n Hobbies -o JSmith -a "@@o^a^sfr^g" create Personal
where -a "@@o^a^sfr^g" grants other owners schedule, free/busy, and read access privileges to both the components and calendar properties of this calendar for group scheduling.
Managing Calendar Server UsersAfter your users are provisioned, use the csuser utility to perform the following administrative tasks:
Displaying User Information
To list all calendar users or to display the calendar attributes of a specified user, use the csuser utility list command.
For example, to display all users enabled for calendaring:
csuser list
To display all of the calendar attributes of a single user such as JSmith:
csuser -v list JSmith
Disabling and Enabling a User
To prevent a user from logging into Calendar Server, use the csuser utility disable command. The disable command prohibits a user from accessing calendar data, but it does not remove the user’s information from the directory server or the Calendar Server database.
For example, to disable JSmith from accessing Calendar Server:
csuser disable JSmith
This command prevents JSmith from logging into Calendar Server to access calendar data, but JSmith’s data is not deleted from the calendar database. However, if JSmith is currently logged into Calendar Server, JSmith retains access to calendar data until logging off.
To enable a user to access Calendar Server and optionally to assign specific configuration settings such as a default calendar, use the csuser utility enable command.
For example, to enable JSmith to access (log into Calendar Server) and to assign JSmith a default calendar:
csuser jsmith enable JSmith
Deleting a User
To delete a Calendar Server user, use the csuser utility delete command.
Caution
The csuser utility delete command removes all of the user’s Calendar Server information from the LDAP server. You can recover Calendar Server database information if the calendar database has been backed up. For more information, see Chapter 6, "Backing Up and Restoring Calendar Server Data".
However, you can recover the LDAP server information only if you have specifically backed it up.
For example, to delete JSmith from Calendar Server:
csuser delete JSmith
Resetting a User’s Attributes
To restore the default settings of all calendar LDAP attributes for a specific user, use the csuser utility reset command.
For example, to reset all calendar attributes of JSmith to the default configuration settings:
csuser reset JSmith
Managing User CalendarsAfter your user calendars are created, use the cscal utility to perform the following administrative tasks:
Displaying Calendars
To display all calendars, all calendars owned by a user, or the properties of a specific calendar, use the cscal utility list command.
For example, to list all calendars in the calendar database:
cscal list
To list all calendars owned by JSmith:
cscal -o JSmith list
To list all the properties of a calendar with the calendar ID JSmith:meetings:
cscal -v list JSmith:meetings
Deleting a Calendar
End users can unsubscribe from a calendar through Calendar Express, but an end user cannot delete a calendar from the Calendar Server database. Deleting a calendar must be done by an administrator who has administrative rights to the system.
To delete one or more calendars from Calendar Server, use the cscal utility delete command. This utility deletes the calendar, but it does not delete the user from the directory server.
Caution
The delete command removes all of the calendar information from the calendar database and cannot be undone. After you delete a calendar, you can recover the calendar data only if it was backed up. For more information, see Chapter 6, "Backing Up and Restoring Calendar Server Data".
The cscal utility lets you delete a single calendar or multiple calendars.
For example, to delete a specific calendar with the calendar ID JSmith:meetings:
cscal delete JSmith:meetings
To delete all calendars whose primary owner is JSmith:
cscal -o JSmith delete
Disabling and Enabling a Calendar
To prevent users from accessing a calendar, use the cscal utility disable command. The disable command prohibits users from accessing the calendar, but it does not remove the information from the calendar database.
For example, to prevent users from accessing JSmith:meetings:
cscal disable JSmith:meetings
To enable a calendar to allow users to access the calendar, use the cscal utility enable command. For example, to enable calendar JSmith:meetings using the default configuration settings:
cscal enable JSmith:meetings
To enable the calendar JSmith:meetings but not allow double booking:
cscal -k no enable JSmith:meetings
Modifying Calendar Properties
To modify the properties of a calendar, use the cscal utility modify command.
For example, to change the group scheduling access control settings of AllAdmins and specify RJones as another owner:
cscal -a "@@o^c^wd^g" -y RJones AllAdmins
where:
Removing Properties From a Calendar
To remove a property value from a calendar, use the cscal utility modify command and specify the option with two double quotes ("") as the value for the option.
For example, to remove a description from JSmith:meetings:
cscal -d "" modify JSmith:meetings
To remove all categories from JSmith:meetings:
cscal -g "" modify JSmith:meetings
To remove “other owners” from JSmith:meetings:
cscal -y "" modify JSmith:meetings
Recovering a “Lost” Calendar
If a user’s default calendar does not appear in the Calendar Express View tab or Calendars tab but still exists in the database, you can recover the calendar by updating the user’s LDAP entry with these attributes:
where default_calid is the user’s default calendar ID (calid).
Creating and Managing Resource CalendarsA resource calendar is associated with a resource such as a meeting room or equipment such as a notebook computer or overhead projector.
To create and manage resource calendars, use the csresource utility. To run csresource, you must log in as a user who has administrator rights to the system where Calendar Server is running.
This section describes how to create and manage resource calendars, including:
Setting Resource Calendar Configuration Parameters
Table 2-1 lists the resource calendar configuration parameters in the ics.conf file.
The default values shown in Table 2-1 apply to new resource calendars, but you can change these default values by editing the ics.conf file. For more information, see "Editing the ics.conf Configuration File".
Creating a Resource Calendar
Calendar Server does not automatically create resource calendars, so you must use the csresource utility create command to manually create each resource calendar required at your site. This command creates an entry in the LDAP directory server and calendar database for the new calendar. Several considerations for creating calendars are:
- By default, Calendar Server does not allow double booking for a resource calendar (resource.allow.doublebook parameter). This default prevents scheduling conflicts for resources such as rooms and equipment. However, if you want to allow double booking for a resource calendar, set the csresource -k option to “yes” when you create the calendar.
- To control who can schedule a specific resource, consider limiting the users who have write access to the resource calendar. For example, you might want to allow only certain users to schedule meeting rooms or reserve equipment.
For example, to create a resource calendar with the calendar ID aud100, viewable name Auditorium (LDAP cn attribute), and the default settings shown in Table 2-1:
csresource -c aud100 create Auditorium
The following command performs the same action as the previous example, but the -k option allows double booking on the calendar, the -o option specifies bkamdar as the owner of the calendar, and the -y option specifies jsmith as another owner:
csresource -c aud100 -k yes -o bkamdar -y jsmith create Auditorium
If you do not specify an owner for a resource calendar, the value is taken from the service.admin.calmaster.userid parameter in the ics.conf file.
Displaying Resource Calendars and Attributes
To display a resource calendar, use the csresource utility list command.
For example, to display a list of all Calendar Server resource calendars and their corresponding LDAP attributes:
csresource list
To display a list of all LDAP attributes for a specific resource calendar named Auditorium:
csresource -v list Auditorium
Modifying a Resource Calendar
To modify a resource calendar, use the cscal utility modify command (csresource does not have a modify command).
For example, to set the owner as tchang and add another owner named mwong to the resource calendar named Auditorium:
cscal -o tchang -y mwong modify aud100
In this example, the cscal utility requires the calid (aud100) rather than the calendar name (Auditorium).
Disabling and Enabling a Resource Calendar
You might need to disable a resource calendar to prevent users from scheduling events. For example, a conference room might be unavailable during remodeling, or an overhead project might be out for repair.
To disable or enable a resource calendar, use the csresource utility enable or disable command.
For example, to disable the resource calendar named Auditorium:
csresource disable Auditorium
Then, to enable the resource calendar later:
csresource enable Auditorium
Deleting a Resource Calendar
To delete a resource calendar, use the csresource utility delete command.
For example, to delete the Auditorium resource calendar:
csresource delete Auditorium
Calendar Server displays the following message:
Do you really want to delete this resource (y/n)?
Enter “y” to delete the calendar or “n” to cancel the operation.
If you enter “y”, Calendar Server deletes the calendar and displays a message that it has been deleted.
Linking to a CalendarYou can create a link to one or more user or resource calendars, as long as each calendar has the permissions set to allow read access. For example, you can embed a calendar link in a web page or email message. Other users can then view the calendar anonymously without having to log into Calendar Server.
To create a link to one or more user calendars, use this syntax:
http://hostname:port/[command.shtml]?calid=calid-1;calid-2; ... ;calid-n&view=viewname
Separate each calendar ID (calid) with a semicolon (;).
viewname can be overview, dayview, weekview, or monthview. (View can also be yearview, but it is not as useful.)
Note: If you are linking to only one calendar without the view (or another) option, omit command.shtml.
For example, to link to the default calendars for jsmith, enter:
http://calendar.sesta.com:8080/?calid=jsmith
To link to a resource calendar for an overhead projector with the calid overhead_projector10:
http://calendar.sesta.com:8080/?calid=overhead_projector10
However, to link to the default calendars for jsmith and tchang and display the calendars in day view, enter:
http://calendar.sesta.com:8080/command.shtml?calid=jsmith;tchang&view=dayv iew
