Communications Suite Directory Server Setup Script (comm_dssetup.pl)

After you install the Communications Suite products and before you create initial configurations for these products, you must prepare Directory Server using the Communications Suite Directory Setup Script, (comm_dssetup.pl).

This chapter covers the following topics:

• Before You Run the comm_dssetup.pl Script
• Running the comm_dssetup.pl Script
• Manually Updating Schema Files
• Resolving Conflicting Calendar Server OID's in the LDAP Schema

Top

Before You Run the comm_dssetup.pl Script

This section covers information you need to understand before running the comm_dssetup.pl script, and contains the following topics:

• What the comm_dssetup.pl Script Does
• Directory Server Considerations for the comm_dssetup.pl Script
• Information You Need to Gather Before you Run the comm_dssetup.pl Script
• About the comm_dssetup.pl Script Schema Choices
• Access Manager Considerations
• Attribute Indexes Created by the comm_dssetup.pl Script

Top

What the comm_dssetup.pl Script Does

The comm_dssetup.pl script proceeds through three steps, as follows:

1. Collects your choices for utility options.
   For a list of the specific information this step requests, see Information You Need to Gather Before you Run the comm_dssetup.pl Script.
2. 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 for the comm_dssetup.pl Script that follows.
3. Runs the shell script created from your options choices. Your directory 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.

Top

Directory Server Considerations for the comm_dssetup.pl Script

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 comm_dssetup.pl script.
• You must run the comm_dssetup.pl script locally from the same machine as your directory server.
• You must run the comm_dssetup.pl script on every instance of every directory server that will be used with Comms Suite.
• If you add an additional machine that has Directory Server installed on it (such as a replica), at a future date, run the comm_dssetup.pl script against it, too.
• If you have customized your LDAP directory, the following considerations may apply:
  • If you have indexed some attributes, you may have to reindex those attributes after the comm_dssetup.pl script runs.
  • If you have added other .ldif files (schema definitions), they should not be affected, so no action should be necessary. However, back up your custom schema definition files before running the comm_dssetup.pl script.
  • For all customizations, including the first two just listed, stop the comm_dssetup.pl 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 directory.

Top

Information You Need to Gather Before you Run the comm_dssetup.pl Script

During the first step of the comm_dssetup.pl script, it requests information about your Directory Server. Prepare for this by gathering the information shown in the following table. (To help you keep track of this information, use Directory Server Installation Worksheet.)

Top

About the comm_dssetup.pl script Schema Choices

Communications Suite servers support the following schema choices:

• Sun LDAP Schema 2 native mode

Corresponds to comm_dssetup.pl script schema version choice 2. This is the default for a fresh installation.

• Sun LDAP Schema 1

Corresponds to the comm_dssetup.pl script schema version choice 1.

• Sun LDAP Schema 2 compatibility mode

Corresponds to comm_dssetup.pl script schema version choice 1.5.

If you are still trying to decide which schema to use, for further explanation, see Understanding Schema Choices in Sun Java Communications Suite 6 Deployment Planning Guide, and the Sun Java System Communications Services 6 2005Q4 Schema Migration Guide.

Top

Scheme 2 / Access Manager Considerations

If you are using Schema 2, Access Manager must be installed and configured.

If you select Scheme 2, and Access Manager is not installed, you will receive the following warning:

Access Manager has not been configured for this new user/group suffix
You can opt to continue, but you will not be able to use
features that depend on Access Manager

Note Do not use the Access Manager console to administer users. Use Delegated Administrator for administering Messaging and Calendar users.

Top

Attribute Indexes Created by the comm_dssetup.pl Script

Attribute indexes improve the performance of search algorithms. The tool offers to index attributes. If you choose to do so, it will add indexes for the all the Communications Suite products. Therefore, once you have run the indexing for one product, you do not need to reindex for other products. If you try to index the same attributes again, nothing happens. The tool calls db2index for each attribute being indexed, but only if the index does not already exist.

The following table lists all the attributes the comm_dssetup.pl 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/1316.1.

Should you decide to add further indexes on your own, instructions for adding indexes can be found in the Directory Server documentation.

Top

Running the comm_dssetup.pl Script

This section covers the following topics:

• To Run the comm_dssetup.pl script
• To Run the comm_dssetup.pl script in Interactive Mode
• To Run the comm_dssetup.pl script in Silent Mode

To Run the comm_dssetup.pl Script

1. On the server where Directory Server is installed, login as or become superuser (root).

2. Start Directory Server, if necessary.

3. Change to the /opt/SUNWcomds/sbin directory.

Or, if you need it, a .zip file is available at /opt/SUNWcomds/lib.

4. Run the comm_dssetup.pl script in either silent mode or in interactive mode.

For further steps, see To Run the comm_dssetup.pl Script in Interactive Mode or To Run the comm_dssetup.pl Script in Silent Mode.

To run the tool script, use the version of Perl included as a shared component and automatically installed by the installer. After installation, Perl can be found in the following directory:

ds-svr-base/bin/slapd/admin/bin/perl

To Run the comm_dssetup.pl Script in Interactive Mode

To run the comm_dssetup.pl 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.
1. Welcome and Introduction Panel

Press Enter to continue, or type no and then press Enter to exit.

2. Installation Root of Directory Server Panel

Specify the location of the installation root of the Directory Server, or press Enter to accept the default.

3. 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.

Enter the number corresponding to your choice, and then press Enter. Or, to accept the default, press Enter without entering a number.

4. Directory Manager Distinguished Name (DN) Panel

This screen has two parts, entering the Directory Manager DN and the Directory Manager's password.
4a. 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 and Messaging Server configuration.

Enter the Directory Manager DN, or press Enter to accept the default.

4b. 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:

5. User and Group Directory Server Panel

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 programs for communications services, like csconfigurator.sh.)

If your answer is Yes, you must specify a user and group base suffix for your Organization Tree.

6. User and Group Base Suffix Panel

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, Communications Suite servers, and Access Manager.

7. Schema Type Panel

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 comm_dssetup.pl script will terminate. You must install Access Manager before rerunning the comm_dssetup.pl script.

8. 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.

In the Schema Type Panel described earlier, 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.

9. Series of Questions Panel

This next screen asks a series of questions about updates to your directory.

9a. 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:

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.

9b. 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 Created by the comm_dssetup.pl Script.

To approve indexing, press Enter.

If you have already performed this indexing step for the same attributes, answer no.

9c. 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.

10. Summary of Settings Panel

Before the comm_dssetup.pl script updates the Directory Server configuration, it displays a summary of your settings and then asks if you want to continue.

If you chose Schema 2 Native Mode in Running the comm_dssetup.pl Script, 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 rerun the script.

If you want to continue, press Enter. The comm_dssetup.pl script generates an LDIF file and a shell script. The names of the files it creates are as follows:

/var/tmp/dssetup_timestamp.ldif

/var/tmp/dssetup_timestamp.sh

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
   Will Create suffix o=comms-config
   Will Create suffix o=pab
   Will Create suffix o=PiServerDb
 
 Checking to see that uid uniqueness plugins are turned off
   Plugin is already disabled
 
 Adding indexes
   Adding Indexes for User/group Tree (backend:mailQA)
     Checking indexes for icsCalendar
       New indexes and Reindexing required
       ReIndex will happen for index type icsCalendar
     Checking indexes for mailAlternateAddress
       New indexes and Reindexing required
       ReIndex will happen for index type mailAlternateAddress
     Checking indexes for ou
       No new indexes required
     Checking indexes for uniqueMember
       No new indexes required
     Checking indexes for cosspecifier
       New indexes and Reindexing required
       ReIndex will happen for index type cosspecifier
     Checking indexes for member
       No new indexes required
     Checking indexes for mailEquivalentAddress
       New indexes and Reindexing required
       ReIndex will happen for index type mailEquivalentAddress
     Checking indexes for inetCos
       New indexes and Reindexing required
       ReIndex will happen for index type inetCos
     Checking indexes for mailUserStatus
       New indexes and Reindexing required
       ReIndex will happen for index type mailUserStatus
     Checking indexes for memberOf
       New indexes and Reindexing required
       ReIndex will happen for index type memberOf
     Checking indexes for icsCalendarOwned
       New indexes and Reindexing required
       ReIndex will happen for index type icsCalendarOwned
     Checking indexes for groupid
       New indexes and Reindexing required
       ReIndex will happen for index type groupid
     Checking indexes for mail
       New indexes and Reindexing required
       ReIndex will happen for index type mail
   Adding Schema2 specific Indexes for User/Group Tree (backend:mailQA)
     Checking indexes for inetDomainBaseDN
       New indexes and Reindexing required
       ReIndex will happen for index type inetDomainBaseDN
     Checking indexes for mailDomainStatus
       New indexes and Reindexing required
       ReIndex will happen for index type mailDomainStatus
     Checking indexes for sunOrganizationAlias
       No new indexes required
     Checking indexes for sunPreferredDomain
       No new indexes required
     Checking indexes for o
       No new indexes required
     Checking indexes for associatedDomain
       No new indexes required
   Adding Indexes for PAB Tree (backend:pabdb2)
     Checking indexes for memberOfPAB
       New indexes and Reindexing required
       ReIndex will happen for index type memberOfPAB
     Checking indexes for memberOfManagedGroup
       New indexes and Reindexing required
       ReIndex will happen for index type memberOfManagedGroup
     Checking indexes for un
       New indexes and Reindexing required
       ReIndex will happen for index type un
     Checking indexes for memberOfPABGroup
       New indexes and Reindexing required
       ReIndex will happen for index type memberOfPABGroup
   Adding Indexes for New PAB Tree (backend:PiServerDbdb2)
     Checking indexes for MemberOfPiBook
       New indexes and Reindexing required
       ReIndex will happen for index type MemberOfPiBook
     Checking indexes for MemberofPiGroup
       New indexes and Reindexing required
       ReIndex will happen for index type MemberofPiGroup
     Checking indexes for displayname
       New indexes and Reindexing required
       ReIndex will happen for index type displayname
 
 Checking to see if DN needs to be created for suffixes
 Generating ldif for Creating Search Templates
 
 Generating ldif for installer metadata
   Generating ldif for Adding schema for installer metadata
   Generating ldif for Creating DN: o=comms-config
   Generating ldif for Creating DN: cn=CommServers,o=comms-config
 The following files have been created:
    /var/tmp/dssetup_20080825160233.sh
    /var/tmp/dssetup_20080825160233.ldif
 
 Running /var/tmp/dssetup_20080825160233.sh will make changes to the Directory
   You can run this file now or at a later time
 Ready to execute the script now.

11. Running the Script

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_20080825160233.sh 
 -D "cn=Directory Manager" 
 -j /var/tmp/dssetup_20080825160233.pw 

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
Stopping Directory Server
 Directory Server instance '/var/opt/SUNWdsee/dsins1' stopped
Starting Directory Server
 Directory Server instance '/var/opt/SUNWdsee/dsins1' started: pid=1234
Creating Suffix o=comms-config
Done Creating o=comms-config
Creating Suffix o=pab
Done Creating o=pab
Creating Suffix o=PiServerDb
Done Creating o=PiServerDb
 
Applying ldif file /var/tmp/dssetup_20080825160233.ldif
 ldap_add: Already exists
 
modifying entry cn=schema
modifying entry cn=schema
adding new entry o=comms-config
adding new entry cn=CommServers,o=comms-config
 
rejects to /var/tmp/dssetup_20080825160233.ldif.rej status = 0
ldapmodify returned 0
Done Applying ldif file /var/tmp/dssetup_20080825160233.ldif

....(entries are indexed)....

Successful Completion. 
Consult /var/tmp/dssetup_20080825160233.log for details

Top

To Run the comm_dssetup.pl Script in Silent Mode

• comm_dssetup.pl Script Silent Mode Instructions
• comm_dssetup.pl Script Silent Mode Syntax

Top

comm_dssetup.pl Script Silent Mode Instructions

To run the comm_dssetup.pl script in silent mode, issue the Perl command followed by a string of options using the syntax shown in comm_dssetup.pl Script Silent Mode Syntax. All of the option arguments are required. Table 8--1 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.sh

Depending 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.

Top

comm_dssetup.pl Script Silent Mode Syntax

The following are all the options for running in the silent mode:

Explanation of Options for Running comm_dssetup.pl Script in Silent Mode

Top

Manually Updating Schema Files

If for any reason, you have decided not to run the comm_dssetup.pl 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

1. Install Calendar Server 6.3.
2. Stop Calendar Server, if it is running.
3. Stop Directory Server, if it is running.
4. 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.
   
5. 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 Created by the comm_dssetup.pl Script.
6. Restart the Directory Server.

If you receive object identifier (OID) errors, see Resolving Conflicting Calendar Server OID's in the LDAP Schema.

Top

Resolving Conflicting Calendar Server OID's in the LDAP Schema

If your LDAP schema contains conflicting OID's, 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:

This problem can occur when you install Calendar Server 6.3 and you also had an older Calendar Server release that dynamically updated your Directory Server 99user.ldif file.
To resolve the conflicting OID's, perform the following two steps:

1. Edit the 99user.ldif file and remove the older OID's. For Calendar Server 6.3, the following table lists the specific OID's that might cause problems.

   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

2. After you edit the 99user.ldif file, restart the Directory Server.