Communications Suite InformationCommunications 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).
Topics:
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
What the comm_dssetup.pl Script Does
The comm_dssetup.pl 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 Before you Run the 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. For further information, see Directory Server Considerations for the comm_dssetup.pl Script. - 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 comm_dssetup.pl Script
The following is a list of the considerations for your LDAP directory:
comm_dssetup.pl is configuration tool that for local LDAP instances servers. Thus,
- You must install the comm_dssetup.pl script on every machine on which a Directory Server resides.
- You can use the Communications Suite installer to install just the dssetup package on each of the Directory Server hosts.
- You can manually copy the dssetup installation directory, for example:
scp -R /opt/sun/comms/dssetup root@<directory server host>:/tmp/dssetup/
- You must run the comm_dssetup.pl script on the same machine as your Directory Server. The tool runs locally for a specific instance (specified by path of directory server or path of instance).
- comm_dssetup.pl is installed into the "DirPrepTool-base", but can be run against any Directory Server instance on the local system. If you have multiple DIT's on one system, you can maintain/update one install of comm_dssetup.pl, and apply it to every Directory Server on the system.
comm_dssetup.pl must configure every Directory Server instance for the same DIT.
- A Directory Server must be installed, configured and running before you run the comm_dssetup.pl script.
- 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.
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 Configuration Worksheets - comm_dssetup.pl Script.)
| Information Item Needed | Default Value |
|---|---|
| Directory Server root path name | The default depends on the Directory Server version detected. The comm_dssetup.pl script does attempt to heuristically determine the value. |
| Which instance of Directory Server to use? (If more than one.) | The default depends on the Directory Server version detected. The comm_dssetup.pl script does attempt to heuristically determine the value. |
| Directory Manager Distinguished Name (DN) | "cn=Directory Manager" |
| 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) | The default depends on what is detected. The comm_dssetup.pl script does attempt to heuristically determine the value. |
| 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 comm_dssetup.pl script 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 Guide before running this utility. |
2. However, if you run comm_dssetup again, it defaults to the value that you chose the previous time. |
| If you choose Schema 1 or 1.5, you will need a DC tree. If the DC tree does not yet exist, the comm_dssetup.pl script 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. However, if you run comm_dssetup again, it defaults to the value that you chose the previous time. |
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, 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 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.
| Suffix | Attributes Indexed | Type of Indexes Added |
|---|---|---|
| User/Group | 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 comm_dssetup.pl Script
This section covers the following topics:
To Run the comm_dssetup.pl Script
- On the server where Directory Server is installed, login as or become superuser root.
- Start Directory Server, if necessary.*
- Change to the directory where you installed or copied the comm_dssetup.pl script.
- 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:
/usr/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.
/usr/bin/perl comm_dssetup.pl
To Run the comm_dssetup.pl Script in Silent Mode
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.
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.
comm_dssetup.pl Script 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>
Explanation of Options for Running comm_dssetup.pl Script 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 comm_dssetup.pl 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 | Specifies the 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 |
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
- Install Calendar Server 6.3.
- 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/schemawhere 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 Created by the comm_dssetup.pl Script. - 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:
- 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 - After you edit the 99user.ldif file, restart the Directory Server.
Comments (2)
May 29
benc2 says:
When we made the jump from docs.sun.com we lost the "what version was applied to...When we made the jump from docs.sun.com we lost the "what version was applied to my Directory Server" instructions:
http://docs.sun.com/source/819-7561/dirPrepTool.html#wp1035296
Jun 06
benc2 says:
For upgrade instructions, see: http://docs.sun.com/source/819-7561/dirPrepTool.h...For upgrade instructions, see: http://docs.sun.com/source/819-7561/dirPrepTool.html