|
| |
| Sun Java System Calendar Server 6 2005Q1 Administration Guide | |
Chapter 2
Directory Preparation Script (comm_dssetup.pl)After you install Calendar Server, and before starting Calendar Server services, you must configure it. It is important that you run the two configuration programs in the following order:
- Directory Preparation Script (comm_dssetup.pl)–The Directory Preparation Script configures Directory Server for Calendar Server 6 and Messaging Server 6. It prepares the Directory Server by setting up new LDAP schema, index, and configuration data.
- Calendar Server Configuration Program (csconfigurator.sh)–The Calendar Server Configuration Program configures Calendar Server. It is described in Chapter 3, "Calendar Server Configuration Program (csconfigurator.sh)".
This chapter covers the Directory Preparation Script and contains the following topics:
Installing the Directory Preparation ScriptIn earlier versions of Java Enterprise System, this utility was bundled with Messaging Server and Calendar Server and did not have to be separately installed. However, starting with Java Enterprise System 2005Q1, the script is now a separately installable shared component.
To install the Directory Preparation Script, choose one of the following methods:
- Java Enterprise System installer–At the component selection panel, select the Directory Preparation Script. (Selecting Directory Server automatically selects the Directory Preparation Script, too.)
- If you are upgrading from an earlier version of Java Enterprise System and are not using the Java Enterprise System installation program, download the following patches:
As installed, the Directory Preparation Script is found in the following directory:
For detailed instructions on upgrading to Calendar Server 6 2005Q1, see the Sun Java Enterprise System Upgrade and Migration Guide.
Before You Run the Directory Preparation ScriptThis section covers information you need to understand before running the Directory Preparation Script, and contains the following topics:
What the Directory Preparation Script Does
The the Directory Preparation Script script proceeds through three steps, as follows:
- Collects your choices for utility options.
For a list of the specific information this step requests, see Information You Need to Gather.
- 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. For further information, see Directory Server Considerations that follows.
- 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.
Directory Server Considerations
The following is a list of the considerations for your LDAP directory:
- A directory server must be installed, configured and running before you run the Directory Preparation Script.
- You must run the Directory Preparation Script on the same machine as your directory server.
- You must run the Directory Preparation Script on every machine on which a directory server resides.
- If you add an additional machine (such as a replica) at a future date, run the Directory Preparation Script against it, too.
- For a list of the LDAP directory servers supported by Calendar Server 6 2005Q1, refer to the Calendar Server 6 2005Q1 Release Notes on the following Web site:
- If you have customized your LDAP directory, the following considerations may apply:
- If you have indexed some attributes, you may have to re-add the indexes after the Directory Preparation Script 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 the Directory Preparation Script.
- For all customizations, including the first two just listed, stop the Directory Preparation Script 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.
- If you are not using a Sun product for your directory server, the simplest solution for deploying the Calendar Server is to upgrade your directory server to the Sun Java System Directory Server.
Information You Need to Gather
During the first step of the Directory Preparation Script, it requests information about your Directory Server. Prepare for this by gathering the information shown in Table 2-1. (To help you keep track of this information, use Appendix A, "Directory Configuration Worksheet".)
Table 2-1 Information Needed to Run the Directory Preparation Script
Information Item Needed
Default Value
Directory Server root path name
/var/opt/mps/serverroot
Which instance of Directory Server to use? (If more than one.)
N/A
Directory Manager Distinguished Name (DN)
“cn=DirectoryManager”
Directory Manager’s Password
N/A
Directory Server being used for user/group data? (yes), or configuration data only (no)?
yes
User and group root suffix (if yes to previous question)
“o=usergroup”
Schema version? (pick one of the following) *
1–Schema 1
1.5–Schema 2 Compatibility Mode
2–Schema 2 Native Mode1
root suffix (if using Schema 1 or Schema 2 Compatibility Mode) **
“o=internet”
Update schema? ***
yes
Add Directory Server indexes? (adds icsCalendar, icsCalendarOwned) ****
yes
* For more information, see About the Schema Choices. 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.
** If the DC tree does not yet exist, the Directory Preparation Script creates only the node. You must create the rest of the DC tree yourself.
*** If you answer yes, you must have a config directory containing the schema files.
**** If you answer yes, the Directory Preparation Script does the indexing for Messaging Server, Calendar Server, and Communications Express even if you are not using all of them.
About the Schema Choices
Calendar Server supports the following schema choices:
If you are still trying to decide which schema to use, for further explanation, see 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-2 lists simplified guidelines which summarize why you might choose each of the schema versions for your installation.
Access Manager Considerations
If you are using Schema 2, Access Manager must be installed and configured.
Note
Do not use the Access Manager console to administer users. For information on how to administer users, see Chapter 14, "Administering Users and Resources."
Attribute Indexes
Attribute indexes improve the performance of search algorithms. The script offers to index attributes. If you choose to do so, it will add indexes not only for Calendar Server, but also for Messaging Server and Communications Express. Therefore, once you have run the indexing for one product, you do not need to reindex for the other product. In deed, if you try to index the same attributes again, nothing happens. The script calls db2index for each attribute being indexed, but only if the index does not already exist.
Table 2-3 lists all the attributes the Directory Preparation Script indexes, grouped by suffix category. It also lists the type of indexes created for each attribute. For more information about Directory Server indexing, see:
http://docs.sun.com/coll/CalendarServer_05q1
Should you decide to add further indexes on your own, instructions for adding indexes can be found in the Directory Server documentation:
http://docs.sun.com/doc/817-7613
Running the Directory Preparation ScriptThis section covers the following topics:
To Run the Directory Preparation Script
- On the server where Directory Server is installed, login as or become superuser (root).
- Start Directory Server, if necessary.
- Change to the /opt/SUNWcomds/sbin directory.
Or, if you need it, a .zip file is available at /opt/SUNWcomds/lib
- Run the Directory Preparation Script in either silent mode or in interactive mode. For further steps, see To Run in Silent Mode or To Run in Interactive Mode.
To run this script, use the version of Perl included as a shared component automatically installed with the Java Enterprise System installer, or. After installation, it can be found at the following directory:
ds_svr_base/bin/slapd/admin/bin/perl
To Run in Silent Mode
To run the Directory Preparation Script in silent mode, issue the perl command followed by a string of options using the syntax shown in Code Example 2-1. All of the option arguments are required. Table 2-4 describes the options.
The utility creates the following LDIF file and shell script to update the LDAP directory indexes and schema:
/var/tmp/dssetup_timestamp.ldif
/var/tmp/dssetup_timestamp.shDepending on the option values you pass in, the utility will either proceed to update the Directory Server by executing the new script, or not. If you have chosen not to proceed with the update, you can check the script and make any desired modifications before running the actual update at a later time.
Code Example 2-1 Syntax of comm_dssetup.pl with options
Table 2-4 Directory Preparation Script (comm_dssetup.pl) Options
Option and Argument
Description
-i yes|no
Answers the question: “Do you want to configure new indexes?”
yes–Add new Directory Server indexes. the Directory Preparation Script 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?” The -m option must be “yes” also for this to take effect.
-c DirectoryServerRoot
Directory Server root path.
For example: /var/opt/mps/ldap-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: dc=varrius,dc=sesta,dc=com
-u UserGroupSuffix
User and group root suffix. For example: dc:west,dc=sesta,dc=com
-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 the Directory Preparation Script 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
To Run in Interactive Mode
To run the Directory Preparation Script in interactive mode, run the script without any arguments and then enter your choices for the questions asked.
The following numbered list gives panel by panel instructions on how to use the interactive mode script.
- Welcome and Introduction Panel
# cd /opt/SUNWcomds/sbin
# ./comm_dssetup.pl
Welcome to the Directory Server preparation tool for Sun Java System communications services.
(Version 6.3 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 Panel
Specify the location of the installation root of the Directory Server, or press Enter to accept the default.
- Directory Server Instance Panel
If multiple instances of the Directory Server reside on this machine, the program lists them and asks you to choose one.
Please select a directory server instance from the following list:
[1] slapd-varrius
Which instance do you want [1]:
Enter the number corresponding to your choice, and then press Enter. Or, to accept the default, press Enter without entering a number.
- Directory Manager Distinguished Name (DN) Panel
This panel has two parts, entering the Directory Manager DN and the Directory Manager’s password.
- First the script asks you for the distinguished name (DN) of the Directory Manager:
The Directory Manager DN, which defaults to cn=Directory Manager, is the administrator 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.
Enter the Directory Manager DN, or press Enter to accept the default.
- Then the script asks for the Directory Manager’s password.
Enter the password for the Directory Manager and press Enter.
The program checks to see if the Directory Server is running and listening on port 389 (the default port).
If successful, it displays the detected version as shown in the example that follows:
If unsuccessful, it tells you that it could not detect a Directory Server running, or listening on port 389. It directs you to fix this problem before allowing you to continue. The script exits. The example below shows this output:
Enter No if this directory instance is used to store only configuration data, or press Enter to accept the default.
If you enter No, then you must also run this script against the directory instance that stores user and group data. (Do this before you run the configuration program csconigurator.sh.)
If your answer is Yes, you must specify a user and group base suffix for your Organization Tree.
The user and group base suffix is the top entry in the LDAP Organization Tree. Be sure that the suffix you select here is the same suffix you specify for Directory Server, Calendar Server, and Access Manager.
- Schema Type Panel
There are 3 possible schema types:
1 - schema 1 for systems with Calendar or Messaging 5.x data
1.5 - schema 2 compatibility for systems with Calendar or Messaging 5.x data that has been converted with the Schema Migration Utility commdirmig
2 - schema 2 native for systems using Access Manager
Please enter the Schema Type (1, 1.5, 2) [1]:
Enter the schema type, or press Enter to accept the default.
Note
To use Schema 2 (options 1.5 or 2), Access Manager must be installed and configured. Otherwise, the Directory Preparation Script will terminate. You must install Access Manager before rerunning the Directory Preparation Script.
- Domain Component (DC) Tree Base Suffix Panel
If you chose Schema 1 or Schema 2 Compatibility Mode, you will be asked to provide your DC tree base suffix. If you chose Schema 2 Native Mode, you will not be asked this question.
In Step 7, if you chose Schema 1 or Schema 2 Compatibility Mode, you will be asked to provide your DC tree base suffix. If you chose Schema 2 Native Mode, 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.
Enter a suffix, or press Enter to accept the default.
- Series of Questions Panel
This next panel asks a series of questions about updates to your LDAP.
- Updating Schema Files
At this point the program checks to see if your schema has the correct schema elements. If your schema is missing some elements, it prints the following message:
Detected bad schema elements in 99user.ldif. It is recommended that you update the schema.
Do you want to update the schema files [yes]:
Answer Yes to add required new elements to your schema. You need to update the directory with the new schema files each time you install a new version of Calendar Server or Messaging Server.
Answer No if you want to delay updating the schema files.
- Configuring New Indexes
If you chose to update the schema in the previous step, you will be asked if you want to configure new indexes. For more information about indexing attributes, see Attribute Indexes.
To approve indexing, press Enter.
If you have already performed this indexing step for the same attributes, answer no.
- 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.
If you want to do the indexing at a later time, answer no, otherwise, press Enter and accept the default.
- Summary of Settings Panel
Before the Directory Preparation Script 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/opt/mps/serverroot/
Server Instance : slapd-varrius
Users/Groups Directory : yes
Update Schema : yes
Schema Type : 1
DC Root : o=internet
User/Group Root : dc=red,dc=sesta,dc=com
Add New Indexes : yes
Reindex New Indexes Now : yes
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 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 want to continue, press Enter. The Directory Preparation Script generates an LDIF file and a shell script. The names of the files it creates are as follows:
If you chose to continue, you will see messages printed out as the program works. The following is an example of the output you will see:
Generating files...
Checking to see if Suffixes need to be added
Checking to see that uid uniqueness plugins are turned off
Adding indexes
Adding Indexes for User/group Tree (backend:userRoot)
Checking indexes for member
No new indexes required
Checking indexes for mailAlternateAddress
No new indexes required
Checking indexes for mail
No new indexes required
Checking indexes for mailEquivalentAddress
No new indexes required
Checking indexes for cosspecifier
No new indexes required
Adding Indexes for DC Tree (backend:internetdb2)
Checking indexes for inetCanonicalDomainName
No new indexes required
Checking indexes for inetDomainBaseDN
No new indexes required
Adding Indexes for PAB Tree (backend:pabdb2)
Checking indexes for memberOfPAB
No new indexes required
Checking indexes for icsCalendar
No new indexes required
Checking indexes for un
No new indexes required
Checking indexes for memberOfPABGroup
No new indexes required
Checking indexes for icsCalendarOwned
No new indexes required
Checking indexes for memberOfManagedGroup
No new indexes required
Adding Indexes for New PAB Tree (backend:PiServerDbdb2)
Checking indexes for MemberOfPiBook
No new indexes required
Checking indexes for MemberofPiGroup
No new indexes required
Checking indexes for displayname
No new indexes required
Checking to see if DN needs to be created for suffixes
(Continuation of the text generated by the script)
Generating ldif for installer metadata
Generating ldif for Adding schema for installer metadata
Generating ldif for updating DN for cn=CommServers,o=comms-config
The following files have been created:
/var/tmp/dssetup_20041209114027.sh
/var/tmp/dssetup_20041209114027.ldif
Running /var/tmp/dssetup_20041209114027.sh will make changes to the Directory
You can run this file now or at a later time
Ready to execute the script now.
Press Enter to accept the default setting (yes). The dssetup_timestamp.sh script runs against your LDAP directory. If you do not want to run the script now, enter No to exit. If you exit, you can run the /var/tmp/dssetup_timestamp.sh script at a later time.
The following is an example of the text output generated while the script is running:
Running /var/tmp/dssetup_20041209114027.sh -D "cn=Directory Manager" -j /var/tmp/dssetup_20041209114027.pw
Stopping Directory Server
Updating Schema files...
Copying 20subscriber.ldif
Copying 50ns-delegated-admin.ldif
Copying 50ns-mail.ldif
Copying 50ns-mlm.ldif
Copying 50ns-msg.ldif
Copying 50ns-value.ldif
Copying 55ims-ical.ldif
Copying 56ims-schema.ldif
Copying 70sun-schema2.ldif
Copying 71sun-am.ldif
Copying 60iplanet-calendar.ldif
Copying 50ns-iabs.ldif
Copying 98ns-dummy-uwc.ldif
Copying 70delgated-admin.ldif
Copying /var/tmp/99user_20041209114027.ldif to /var/opt/mps/serverroot/slapd-varrius/config/schema/99user.ldif
Starting Directory Server
Applying ldif file /var/tmp/dssetup_20041209114027.ldif
modifying entry cn=schema
modifying entry cn=schema
modifying entry cn=CommServers,o=comms-config
Done Applying ldif file /var/tmp/dssetup_20041209114027.ldif
rejects to /var/tmp/dssetup_20041209114027.ldif.rej status = 0
Successful Completion. Consult /var/tmp/dssetup_20041209114027.log for details
Manually Updating Schema FilesIf for any reason, you have decided not to run the Directory Preparation Script generated script, the following directions allow you to manually update your schema files for Sun Java System Directory Server.
Note
If you update your LDAP directory schema manually and then later upgrade Calendar Server, you must manually update the LDAP server schema again. Calendar Server cannot automatically update the schema after the it has previously been updated manually.
To Update Your LDAP Directory Manually:
- Install Calendar Server 6 2005Q1.
- 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.
- If you want to index attributes, as the configuration program does, do it at this point. For a list of the attributes the configuration program indexes, see Attribute Indexes.
- Restart the Directory Server. If you receive object identifier (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, "Calendar Server Configuration Program (csconfigurator.sh)".
Resolving Conflicting OIDs in the LDAP Schema DirectoryIf your LDAP schema directory contains conflicting 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 2005Q1 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 2005Q1, Table 2-5 shows the specific OIDs that might cause problems.
Table 2-5 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.44
icsCalendarResource
2.16.840.1.113730.3.2.143
1.3.6.1.4.1.42.2.27.9.2.45
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.