|
| |
| Sun Java System Calendar Server Administration Guide | |
Chapter 2
Configuring Your LDAP DirectoryAfter you install Calendar Server, and before running it, you must configure it. It is important that you run the two configuration programs in the following order:
- comm_dssetup.pl – Configures the Sun Java System Directory Server LDAP directory as described in this chapter.
- csconfigurator.sh – Configures Calendar Server as described in Chapter 3, "Configuring Calendar Server".
This chapter covers comm_dssetup.pl and contains the following topics:
Updating Your LDAP DirectoryThere are several determining factors for deciding which method to use to update your LDAP directory:
For a list of the LDAP directory servers supported by Calendar Server 6 2004Q2, refer to the Calendar Server 6 2004Q2 Release Notes on the following Web site:
http://docs.sun.com/coll/CalendarServer_04q2
If your users are already stored in a non-Sun LDAP directory, the simplest solution for deploying the Calendar Server is to upgrade your directory server to the Sun Java System Directory Server.
For information about installing and configuring a Directory Server, see:
http://docs.sun.com/coll/DirectoryServer_04q2
You Have Sun Java System Directory Server
If you are using Sun Java System Directory Server for your LDAP directory, after you have installed Calendar Server 6 2004Q2 or Messaging Server 6 2004Q2, run comm_dssetup.pl once on each server where Directory Server is running.
If you add an additional LDAP server (such as a replica) at a future date, run comm_dssetup.pl against it.
Run comm_dsstup.pl before you run the configuration program.
For instructions, see Updating with comm_dsetup.pl.
Note
Before running comm_dssetup.pl, if you have customized your Directory Server, read You Have Customized Directory Server to see how running comm_dssetup.pl might affect your customizations.
You Have Customized Directory Server
The following considerations should be addressed before running comm_dssetup.pl:
- If you have customized your Directory Server by indexing some attributes, you may have to re-add the indexes after comm_dssetup.pl runs.
- If you have added other .ldif schema definitions, they should not be affected, so no action should be necessary. As always, though, it would be prudent to back up your custom schema definition files before running comm_dssetup.pl.
- For all customizations, including the first two just listed, stop comm_dssetup.pl after it generates the script and before it actually updates the LDAP directory. Then inspect the script to evaluate how its proposed actions will affect your LDAP directory. Take whatever actions you think necessary to protect your customizations before running the script against your LDAP.
You Do Not Use a Sun Product for Your Directory Server
If you are not using a Sun product for your directory server, you can use the script generated by comm_dssetup.pl (without actually running the script) to understand the updates you need to make to your non-Sun LDAP directory. See the instructions for running comm_dssetup.pl that follow.
Updating with comm_dsetup.plThe Directory Server Setup Perl script (comm_dssetup.pl) configures Directory Server for Calendar Server 6 and Messaging Server 6. The comm_dssetup.pl script prepares the Directory Server by setting up new LDAP schema, index, and configuration data.
This section describes:
Functions of comm_dssetup.pl
The comm_dssetup.pl utility proceeds through three steps, as follows:
- Collects your choices for utility options.
For a list of the specific information this step requests, see Gathering Information Needed to Run comm_dssetup.pl.
- Generates a shell script and LDIF file from your options choices that will be used to modify the LDAP directory. If you are not using a Sun product for your directory server, or have customized your Directory Server, stop the process here without running the shell script and follow the guidelines in the following sections: You Have Customized Directory Server or You Do Not Use a Sun Product for Your Directory Server.
- Runs the shell script created from your options choices. Your LDAP is modified accordingly.
At the end of each step, the utility asks you if you want to continue. No changes are made to the LDAP directory until the third step.
Requirements to Run comm_dssetup.pl
The requirements to run comm_dssetup.pl include:
- You must run comm_dssetup.pl before you run the Calendar Server configuration program, csconfigurator.sh.
- Directory Server must be installed, configured, and running.
- You must run comm_dssetup.pl on the same server where Directory Server is running.
- If you are using Schema 2, Identity Server must be installed and configured.
- You must run comm_dssetup.pl as superuser (root).
Gathering Information Needed to Run comm_dssetup.pl
During the first step of comm_dssetup.pl, you must to provide the following information. (To help you keep track of this information, use Appendix A, "Directory Configuration Worksheet".)
- What is the Directory Server root path name? The default is /var/mps/serverroot.
- If you have multiple instances of Directory Server, which instance do you want to use for Calendar Server 6 2004Q2?
- What is the Directory Manager Distinguished Name (DN) and password? The default DN is "cn=Directory Manager".
- Will the Directory Server be used for Users and Groups? That is, do you want to use Directory Server to store both configuration and user data (yes) or configuration data only (no)? The default is both (yes).
- If the Directory Server will be used for Users and Groups, what is the User and Group root suffix? The default is o=usergroup.
- Which version of the schema do you want to use?
For more information, see Deciding Which Schema to Use. Note, if you have one version of the schema installed and want to upgrade to a higher level, refer to the Sun Java System Communications Services Schema Migration Guide before running this utility.
- Do you want to update the schema (yes/no)? The default is yes. If you answer yes, you must have a config directory containing the schema files.
- Do you want to configure new Directory Server indexes (yes/no)? The default is yes. For Calendar Server, comm_dssetup.pl adds indexes for the icsCalendar and icsCalendarOwned attributes.
Deciding Which Schema to Use
Calendar Server supports Sun LDAP Schema 1 and Sun LDAP Schema 2, in either native or compatibility mode.
If you are still trying to decide which schema to use, refer to material in the Sun Java Enterprise System Technical Overview, the Sun Java Enterprise System Installation Guide and to the Sun Java System Communications Services Schema Migration Guide.
Table 2-1lists simplified guidelines summarize how you might choose the schema to use for your installation.
If you choose Schema 1, for provisioning and administration, use the Calendar Server utilities, such as csuser, csdomain, and csresource, as described in this document.
If you choose Schema 2, for provisioning and administration, use the User Management Utility bundled with the product. For information about the User Management Utility, see the Sun Java System Communications Services 6 2004Q2 User Management Utility Administration Guide.
There are some exceptions to this rule. The old Schema 1 calendar utilities can be used, or in some cases, must be used for certain functions, such as creating calendars for users and resources. (if auto-provisioning is turned on, it only works for user calenders. You must specifically create all resource calendars using csresource.)
Running comm_dssetup.pl
The comm_dssetup.pl script is zipped together with the schema files that it will add to the Directory Server. The name of the file is dssetup.zip. It can be found in the following directory:
/opt/SUNWics5/cal/install/
If you can’t find the dssetup.zip file, you can construct one yourself by zipping the comm_desetup.pl file (/opt/SUNWics5/cal/sbin/) and the contents of the schema directory (/opt/SUNWics5/cal/sbin/schema) into a file called dssetup.zip.
To run comm_dssetup.pl:
- On the server where Directory Server is installed, login as or become superuser (root).
- Start Directory Server, if necessary.
- If Calendar Server is installed on this same machine, change to the /opt/SUNWics5/cal/sbin directory.
Or, if Calendar Server is not installed on this machine, then do the following:
- Run the comm_dssetup.pl script in either Silent Mode or Interactive Mode. To run this script, use the version of Perl included with Directory Server 5.x:
ds_svr_base/bin/slapd/admin/bin/perl
Silent Mode
To run comm_dssetup.pl in silent mode, use the following syntax.
Table 2-2 Lists the options used to run comm_dssetup.pl in silent mode. All of the arguments are mandatory. The table lists the options and gives a description of each.
Table 2-2 Directory Server Setup Script (comm_dssetup.pl) Options
Option
Description
-i yes|no
Answers the question: “Do you want to configure new indexes?”
yes–Add new Directory Server indexes. comm_dssetup.pl adds indexes for the icsCalendar and icsCalendarOwned attributes.
no–Do not add indexes.
-R yes|no
Answers the question: “Do you want to reindex now?”
-c DirectoryServerRoot
Directory Server root path name.
For example: /usr/sunone/servers-d DirectoryInstance
Directory Server instance subdirectory.
For example: slapd-varrius-r DCTreeSuffix
DC tree root suffix. (for Schema 1 and Schema 2 compatibility modes only)
For example: o=internet
-u UserGroupSuffix
User and Group root suffix. For example: o=isp
-s yes|no
Answers the question: “Do you want to update the schema?”
yes–Update the schema. You must have a config directory with the schema files.
no–Do not update schema.
-D DirectoryManagerDN
Directory Manager Distinguished Name (DN). The value must be enclosed by double quotation marks (") to allow comm_dssetup.pl to interpret a value with a space correctly.
For example: "cn=Directory Manager"
-w DirectoryManagerPassword
Directory Manager DN password.
-b yes|no
Answers the question: “Will this directory server be used for users and groups?”
yes–Use this directory to store both configuration and user group data.
no–Use this directory to store only configuration data.
-t 1|1.5|2
Schema version:
-m yes|no
Answers the question: “Do you want to modify the directory server?”
yes–Modify the Directory Server without prompting the user.
no–Do not modify the Directory Server without prompting the user.
-S PathtoSchemaFiles
Path to the directory where the schema files are located. For example: ./schema
Example
perl comm_dssetup.pl -i yes -c /var/mps/serverroot -d slapd-ketu -r o=internet -u o=usergroup" -s yes -D "cn=Directory Manager" -w password -b yes -t 1 -m yes -R yes
When you run in silent mode, comm_dssetup.pl displays a summary similar to Step Summary of Settings for Interactive Mode before making actual changes to your Directory Server.
Interactive Mode
To run in interactive mode, you run the comm_dssetup.pl script without any arguments and then enter your choices as you are prompted.
- Welcome and Introduction
# perl comm_dssetup.pl
Welcome to the Directory Server preparation tool for Sun Java System Communications Services.
(Version 6.1 Revision 0.1)
This tool prepares your directory server for use by the
Communications Services which include Messaging, Calendar and their components.
The logfile is /var/tmp/dssetup_YYYYMMDDHHSS
Do you want to continue [y]:
Press Enter to continue, or type no and then press Enter to exit.
- Installation Root of Directory Server
Please enter the full path to the directory where the Sun Java System Directory Server was installed.
Directory server root [/var/mps/serverroot]
Specify the location of the installation root of the Directory Server.
- Directory Server Instance
Please select a directory server instance from the following list:
[1] slapd-varrius
Which instance do you want [1]:
If multiple instances of Directory Server reside on the server, choose the one that will be configured with Calendar Server.
- Directory Manager Distinguished Name (DN)
The Directory Manager DN (cn=Directory Manager) is the administrator who is responsible for the user and group data in the Organization Tree. Be sure that the Directory Manager DN you specify in this script is the same DN that you set up for your Directory Server installation as well for as your Calendar Server configuration.
- User and Group Directory Server
If you answer Yes, you must specify a User and Group base suffix for your Organization Tree.
If you answer No, it is assumed that this directory instance is used to store only configuration data, and skip to Step 9. After you finish running this script against the configuration directory instance, you need to run this script against the directory instance that stores user and group data before you run the configuration program for Calendar Server.
- User and Group Base Suffix
The User and Group base suffix is the top entry in the Organization Tree that holds the name space for user and group entries. Be sure that the User and Group base suffix you select is the same as what you specified for Directory Server and Calendar Server.
If you installed Identity Server, be sure the suffix specified in Identity Server installation is the same as what you specify for this question. If you do not use the same suffix, Calendar Server will not recognize your Identity Server installation.
- Schema Type
There are 3 possible schema types:
1 - schema 1 for systems with iMS 5.x data
1.5 - schema 2 compatibility for systems with iMS 5.x data that has been converted with commdirmig
2 - schema 2 native for systems using Identity Server
Please enter the Schema Type (1, 1.5, 2) [1]:
Choose the version of the schema you are planning to use:
- Domain Component (DC) Tree Base Suffix
In Step 7, if you chose Option 1 or 1.5, you will be asked to provide your DC tree base suffix. If you chose Option 2, you will not be asked this question.
The DC tree mirrors the local DNS structure and is used by the system as an index to the Organization tree that contains the user and group data entries. The DC tree base suffix is the name of the top entry on the DC tree. You can either choose the default (o=internet) or another name.
- Updating Schema Files
If you answer Yes, comm_dssetup.pl adds new elements to your schema. Update the directory with the new schema files each time you install a new version of Calendar Server or Messaging Server.
- Configuring New Indexes
If you answered Yes to Step 5, you will be asked if you want to configure new indexes, which can improve the performance of directory searches.
comm_dssetup.pl calls db2index for each attribute being indexed, and only if the index does not already exist.
For Calendar Server, comm_dssetup.pl adds indexes for the icsCalendar and icsCalendarOwned attributes. This will improve performance of search algorithms, so answer Yes.
Table 2-3 lists the various attributes indexed by comm_dssetup.pl, grouped by suffix category, and lists the type of indexes created for each attribute. For more information about Directory Server indexing, see:
Table 2-3 Attributes Indexed by comm_dssetup.pl
Suffix
Attributes Indexed
Type of Indexes Added
User/Group
inetMailGroupStatus
pres,eq
inetUserStatus
pres,eq
pres,eq,approx,sub
mailAlternateAddress
pres,eq,approx,sub
mailEquivalentAddress
pres,eq,approx,sub
mailHost
pres,eq,approx,sub
mailUserStatus
pres,eq
member
eq
ou
pres
cosspecifier
pres
createtimestamp
eq
modifytimestamp
eq
DC Tree
inetDomainBaseDN
pres,eq
inetCanonicalDomainName
pres,eq
inetDomainStatus
pres,eq
mailDomainStatus
pres,eq
mailRoutingHosts
pres,eq,approx,sub
dc
pres
createtimestamp
eq
modifytimestamp
eq
Personal Address Book (PAB)
memberOfManagedGroup
pres,eq
memberOfPAB
pres,eq
memberOfPABGroup
pres,eq
un
eq
createtimestamp
eq
modifytimestamp
eq
icsCalendar
pres,eq,approx,sub
icsCalendarOwned
pres,eq,approx,sub
New PAB
displayname
pres,eq,sub
MemberOfPiBook
eq
MemberofPiGroup
eq
- Reindex Now?
You can choose to do the indexing now, or you can do it at a later time. If you choose to defer the indexing, rerun the script with indexing turned on when it is convenient. Indexing can take a long time, but the Directory Server is still functional, that is, is not put into read only mode during indexing.
- Summary of Settings
Before comm_dssetup.pl updates the Directory Server configuration, it displays a summary of your settings and then asks if you want to continue.
Here is a summary of the settings that you chose:
Server Root : /var/mps/serverroot/
Server Instance : slapd-varrius
Users/Groups Directory : Yes
Update Schema : yes
Schema Type : 1
DC Root : o=internet
User/Group Root : o=usergroup
Add New Indexes : yes
Reindex New Indexes Now: yes
Schema Directory : ./schema **
Directory Manager DN : cn=Directory Manager
Now ready to generate a shell script and ldif file to modify the Directory.
No changes to the Directory Server will be made this time.
Do you want to continue [y]:
If you chose Option 2 (Schema 2 - Native Mode) in Step 7, the DC Root will be the same value that you entered for the User/Group Root.
To change any of your settings, enter No and re-run the script.
If you continue, comm_dssetup.pl creates the following LDIF file and shell script to update the Directory Server indexes and schema (although it does not run the script at this time):
/var/tmp/dssetup_timestamp.ldif
/var/tmp/dssetup_timestamp.sh- Running the Script
The configuration program does not run the script created in the previous step unless you answer Yes when it asks if you want to continue.
Enter Yes to run the dssetup_timestamp.sh script now or No to exit. If you exit, you can run the /var/tmp/dssetup_timestamp.sh script later.
Manually Updating Schema FilesIf for any reason, you have decided not to run the comm_dssetup.pl generated script, the following directions allow you to manually update your schema files for the following directory servers:
If you have conflicting OIDs after updating the schema files, see Resolving Conflicting OIDs in the LDAP Schema Directory.
Sun Directory Servers
The Sun Java System Directory Server 5 2004Q2, Sun™ ONE Directory Server 5.2 and iPlanet™ Directory Server 5.1 LDAP schema extensions used by the Calendar Server are defined in the 60iplanet-calendar.ldif file.
The Calendar Server installation program installs this file in the /opt/SUNWics5/cal/config/schema directory.
Note
If you update your LDAP server schema manually and then later upgrade Calendar Server, you must manually update the LDAP server schema again. Calendar Server cannot automatically update a directory server schema after the schema has previously been updated manually.
To update Directory Server manually:
- Install Calendar Server 6 2004Q2.
- Stop Calendar Server, if it is running.
- Stop Directory Server, if it is running.
- Copy the 60iplanet-calendar.ldif file to the following directory on the machine where your directory server is running:
dir_svr_base/slapd-hostname/config/schema
where dir_svr_base is the Directory Server installation directory and hostname identifies the machine.
- Restart the Directory Server. If you receive OID errors, see Resolving Conflicting OIDs in the LDAP Schema Directory.
- Configure Calendar Server by running the csconfiguration.sh program.
For instructions on configuring Calendar Server, see Chapter 3, "Configuring Calendar Server".
Netscape Directory Server
For Netscape Directory Server 4.12 or 4.16, the LDAP schema extensions used by the Calendar Server are defined in the following files:
These files are available in the /opt/SUNWics5/cal/config directory.
To update Netscape Directory Server 4.12 or 4.16 manually:
- Install Calendar Server 6.0.
- Copy the LDAP schema files (um50-common-schema.conf and ics50-schema.conf) from the /opt/SUNWics5/cal/config directory to the following directory on the server where your directory server is running:
server-root/slapd-hostname/config
where hostname is the name of the server. For example, on Solaris and other UNIX systems:
/usr/Netscape/Server4/slapd-sesta/config
- Stop Calendar Server, if it is running.
- Stop Directory Server, if it is running.
- Edit the ns-schema.conf file (in the same directory in which you copied the um50-common-schema.conf and ics50-schema.conf files.) At end of the file, if they are not already present, add the following lines to include these files.
On Solaris and other UNIX systems:
include /netscape/server4/slapd-hostname/config/um50-common-schema.conf
include /netscape/server4/slapd-hostname/config/ics50-schema.conf
On Windows 2000 systems:
include "C:\Netscape\Server4\slapd-hostname\config\um50-common-schema.conf"
include "C:\Netscape\Server4\slapd-hostname\config\ics50-schema.conf"
where hostname is the name of the server where the directory server is running.
Note
Be sure to add the lines in the order shown above so that um50-common-schema.conf is included before ics50-schema.conf.
- Restart the Netscape Directory Server. If you receive OID errors, see Resolving Conflicting OIDs in the LDAP Schema Directory.
- Configure Calendar Server.
For instructions on configuring Calendar Server, see Chapter 3, "Configuring Calendar Server".
Resolving Conflicting OIDs in the LDAP Schema DirectoryIf your LDAP schema directory contains conflicting Object Identifiers (OIDs), the Directory Server does not know which OID to use and returns an error message. For example, the following message indicates a conflicting OID for the icsCalendarUser object class:
[24/Apr/2004:23:45:28 -0700] dse - The entry cn=schema in file 99user.ldif is invalid, error code 20 (Type or value exists) - object class icscalendaruser: The name does not match the OID. Another object class is already using the name or OID.
[24/Apr/2004:23:45:28 -0700] dse - Please edit the file to correct the reported problems and then restart the server.
This problem can occur when you install Calendar Server 6 2004Q2 and you also had an older Calendar Server release that dynamically updated your LDAP server schema 99user.ldif file.
To resolve the conflicting OIDs, you must edit the 99user.ldif file and remove the older OIDs. For Calendar Server 6 2004Q2, Table 2-4 shows the specific OIDs that might cause problems.
Table 2-4 Calendar Server OIDs in the LDAP Schema Directory
Object Class
Old OID
New OID
icsCalendarUser
2.16.840.1.113730.3.2.141
1.3.6.1.4.1.42.2.27.9.2.2
icsCalendarResource
2.16.840.1.113730.3.2.143
1.3.6.1.4.1.42.2.27.9.2.3
icsCalendarDomain
2.16.840.1.113730.3.2.144
1.3.6.1.4.1.42.2.27.9.2.4
After you edit the 99user.ldif file, restart the Directory Server.