Sun Java Communications Suite 5 Installation Guide

Chapter 8 Directory Preparation Tool (comm_dssetup.pl)

After installing the Communications Suite products and before provisioning and using the servers, you must prepare Directory Server using the Directory Preparation Tool (comm_dssetup.pl). This is a separately installed component. In the installer, you must select the Directory Preparation Tool. This chapter covers the following topics:


Note –

If you had an earlier version of Calendar Server or Messaging Server installed, you might need to migrate your LDAP directory entries from Schema 1 to Schema 2.

Do not run the configuration utility described in this chapter until you have read the Sun Java System Communications Services 6 2005Q4 Schema Migration Guide. It instructs you on the timing and options for running the configuration utilities.


Before You Run the Directory Preparation Tool

This section covers information you need to understand before running the Directory Preparation Tool, and contains the following topics:

What the Directory Preparation Tool Does

The Directory Preparation Tool 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 Directory Preparation Tool.

  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 Directory Preparation Tool 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.

Directory Server Considerations for the Directory Preparation Tool

The following is a list of the considerations for your LDAP directory:

Information You Need to Gather Before you Run the Directory Preparation Tool

During the first step of the Directory Preparation Tool, 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.)

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 Mode

[For more information on how to choose a schema, see About the Directory Preparation Tool 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 6 2005Q4 Schema Migration Guidebefore running this utility. ]

1

Root suffix (if using Schema 1 or Schema 2 Compatibility Mode) [If you choose Schema 1 or 1.5, you will need a DC tree. If the DC tree does not yet exist, the Directory Preparation Tool creates only the root suffix node, its does not create the rest of the DC tree. You must create the rest of your DC tree yourself.]

o=internet

Update schema? [If this Directory Server is being used for user/group data, you must have a config directory containing the schema files.]

yes 

Add Directory Server indexes? [If you answer yes, the Directory Preparation Tool does the indexing for Messaging Server and Calendar Server, even if you are not using both of them.]

yes 

About the Directory Preparation Tool Schema Choices

Communications Suite servers support the following schema choices:

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

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. Use Delegated Administrator for administering Messaging and Calendar users.


Attribute Indexes Created by the Directory Preparation Tool

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 Directory Preparation Tool 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.

Suffix 

Attributes Indexed 

Type of Indexes Added 

User/Group

mail

pres, eq, approx, sub

mailAlternateAddress

pres, eq, approx, sub

mailEquivalentAddress

pres, eq, approx, sub

member

eq

cosspecifier

pres

 

User/Group (for Access Manager – Schema 2)

inetDomainBaseDN

pres, eq

sunPreferredDomain

pres, eq

associatedDomain

pres, eq

o

pres, eq

sunOrganizationAlias

pres, eq

 

DC Tree (for Schema 1)

inetDomainBaseDN

pres, eq

inetCanonicalDomainName

pres, eq

 

Personal Address Book (PAB)

memberOfManagedGroup

pres, eq

memberOfPAB

pres, eq

memberOfPABGroup

pres,eq

un

eq

icsCalendar

pres, eq, approx, sub

icsCalenarOwned

pres, eq, approx, sub

 

New PAB

displayname

pres, eq, sub

MemberOfPiBook

eq

MemberofPiGroup

eq

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

Running the Directory Preparation Tool

This section covers the following topics:

ProcedureTo Run the Directory Preparation Tool

  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 Directory Preparation Tool in either silent mode or in interactive mode.

    For further steps, see Running the Directory Preparation Tool or Running the Directory Preparation Tool.

    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

ProcedureTo Run the Directory Preparation Tool in Interactive Mode

To run the Directory Preparation Tool 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


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

  2. Installation Root of Directory Server Panel


    Please enter the full path to the directory where the 
            Sun Java System Directory Server was installed.
    Directory server root [/var/opt/mps/serverroot]

    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.


    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.

  4. Directory Manager Distinguished Name (DN) Panel

    This screen has two parts, entering the Directory Manager DN and the Directory Manager’s password.

    1. First the script asks you for the distinguished name (DN) of the Directory Manager:


      Please enter the directory manager DN [cn=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.

    2. Then the script asks for the Directory Manager’s password.


      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:


      Detected DS version 5.2

      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:


      Directory Server not running or not listening to port 389.
      Detected DS version 0.0
      Please correct the problem and re-run this script.
  5. User and Group Directory Server Panel


    Will this directory server be used for users/groups [Yes]:

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


    Please enter the Users/Groups base suffix [o=usergroup]:

    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


    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 Tool will terminate. You must install Access Manager before rerunning the Directory Preparation Tool.


  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. If you chose Schema 2 Native Mode, you will not be asked this question.


    Please enter the DC Tree base suffix [o=internet]:

    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.

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

    2. 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 Directory Preparation Tool.


      Do you want to configure new indexes [yes]:

      To approve indexing, press Enter.

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

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


      Reindex now [yes]?

      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 Directory Preparation Tool 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 Running the Directory Preparation Tool, 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 Directory Preparation Tool 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
    
    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 
    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.
  11. Running the Script


    Do you want to continue [yes]:

    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

To Run the Directory Preparation Tool in Silent Mode

Directory Preparation Tool Silent Mode Instructions

To run the Directory Preparation Tool in silent mode, issue the Perl command followed by a string of options using the syntax shown in Directory Preparation Tool Silent Mode Syntax. All of the option arguments are required. Table 8–1describes 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.

Directory Preparation Tool Silent Mode Syntax

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


perl comm_dssetup.pl
    -i yes|no
    -R yes|no
    -c DirectoryServerRoot
    -d DirectoryInstance
    -r DCTreeSuffix
    -u UserGroupSuffix
    -s yes|no
    -D DirectoryManagerDN
    -w DirectoryManagerPassword
    -b yes|no -t 1|1.5|2
    -m yes|no
   [-S PathtoSchemaFiles]
               
Table 8–1 Explanation of Options for RunningDirectory Preparation Tool in Silent Mode

Option and Argument 

Description 

-i yes|no

Answers the question: “Do you want to configure new indexes?” 

yes Add new Directory Server indexes.

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 Tool 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: 

  • 1 Sun LDAP Schema 1

  • 1.5 Sun LDAP Schema 2 Compatibility Mode

  • 2 Sun LDAP Schema 2 Native Mode

-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

Manually Updating Schema Files

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


ProcedureTo 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 Directory Preparation Tool.

  6. Restart the Directory Server.

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

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:


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