Solaris ISP Server 2.0 Installation Guide

Integration Procedures

These procedures explain the steps you need to take to configure an existing installation of Sun Directory Services from Solaris ISP Server and an existing installation of Sun Internet Mail Server to interoperate and share subscriber data. These procedures assume that you have already installed the software on separate machines.

You do not need to install both products before you run the configuration procedures, but if you have not you may need to repeat steps later when more information is available.

The recommended order for the integration procedures is

Update the Sun Internet Mail Server directory using the sims2sisp script, and copy the output ldif file of users from the mail directory to the Solaris ISP Server directory host.
Update the Solaris ISP Server directory host using the sisp2sims script with the output file created by sims2sisp.

If the ldif file containing mail users from the Sun Internet Mail Server directory is unavailable when you update the Solaris ISP Server directory, you can run the addusers script when the ldif file is available.

If you want to undo the integration procedures, you can run undosims and undosisp to revert to the original configurations of the Sun Directory Services servers; these scripts will not remove entries from the directory, only change the configurations so that the Sun Internet Mail Server directory is no longer a slave.

To Update the Sun Internet Mail Server Directory:

Make sure that the Sun Directory Services component of Solaris ISP Server 2.0 has been installed on a machine.

A Solaris ISP Server 2.0 installation of Sun Directory Services is required because it includes the required scripts and schema changes that allow you to configure the Sun Internet Mail Server directory as a slave.

Create a temporary directory on the Sun Internet Mail Server host where you can store the packages you need to install.

Since you only need this directory until the packages are installed, use /tmp. For example,
# mkdir /tmp/sims/

Copy the sims_int.tar.Z file from the Solaris ISP Server directory host to the directory you just created on the Sun Internet Mail Server host.

This archive is installed to /etc/opt/SUNWisp/ldap/sunds/sims/ by default.

Log in to the Sun Internet Mail Server host, become superuser (root), and change directory to where the sims_int.tar.Z file is located:
simshost% su root Password: #cd /tmp/sims

Uncompress and unpack the archive to get the packages:
# zcat sims_int.tar.Z | tar xvf -
This will create a package directory for the SUNWixsim package. There may be other packages with locale-specific data if your version of the Solaris ISP Server software supports languages other than English.

Install all of the packages that are extracted from the archive:
# ls SUNWixsim # pkgadd -d . SUNWixsim
The package installs the scripts you will need in /opt/SUNWisp/ldap/sunds/sbin. You may install these to a different location using the -R option to pkgadd; for example
# pkgadd -R /tmp -d . SUNWixsim
installs the scripts in /tmp/ldap/sunds/sbin.

The configuration files required to update the Sun Directory Services configuration are copied to /etc/opt/SUNWisp/ldap/sunds/default.

Run the sims2sisp script, specifying the host name of the Solaris ISP Server directory and the distinguished name and password needed to bind to the Sun Internet Mail Server directory.

The script is installed in /opt/SUNWisp/ldap/sunds/sbin/ by default.

sims2sisp -h sispHost -D bindDN [-w bindPassword]

Note that the host is the Solaris ISP Server directory host; this names the host that localhost will be a slave to. The default port is 389.

The -w flag is optional. If you do not specify a password, the script will prompt you to enter one. Using -w to pass the password automatically may be insecure, and you should not use it.

For example:
# ./sims2sisp -h directory1 -D "cn=mailadmin,o=MyISP,c=US" Please enter the LDAP Administrator password:
The Sun Internet Mail Server directory has now been reconfigured as a slave and restarted. If there were any user entries in the directory, there will be a file named sims_users.ldif in the current directory.

Note -
The new users in the ldif output file from sims2sisp contain the same relative distinguished names they had in the Sun Internet Mail Server directory. If the tree structures in the two directories do not match, the entries may not be added because a parent node does not exist.

For example, in the Sun Internet Mail Server directory, the relative dn might be "ou=People,ou=subdomain,o=Organization,c=US." If the "ou=subdomain,o=Organization,c=US" node does not exist in the Solaris ISP Server directory, all of the users beneath this "ou=People" node will not be added.

Be sure to create the organizationalUnit entries you need in the Solaris ISP Server directory before you attempt to add the new user data.

Copy the sims_users.ldif file to the Solaris ISP Server directory host, and complete the procedure "To Update the Solaris ISP Server Directory."

To Update the Solaris ISP Server Directory:

(Optional) Locate the sims_users.ldif file that was created when you updated the Sun Internet Mail Server directory. This file will be used to add the Sun Internet Mail Server users to the Solaris ISP Server directory.

Log in to the Solaris ISP Server host, become superuser (root), and change directory to /opt/SUNWisp/ldap/sunds/sbin:
sisphost% su root Password: # cd /opt/SUNWisp/ldap/sunds/sbin

Run the sisp2sims script, specifying the host name of the Sun Internet Mail Server directory; the distinguished name and password needed to bind to the Solaris ISP Server directory. Add full path name to the sims_users.ldif file if it is available:

sisp2sims -h simsHost [-p port] -D bindDN [-w bindPassword] [-f simsLDIFfile]

The -w flag is optional. If you do not specify a password, the script will prompt you to enter one. Using -w to pass the password automatically may be insecure, and you should not use it.

Note that the host is the Sun Internet Mail Server directory host; this names the host that the current host will be a master of. The default port is 389.

The -f option names an ldif file with user entries extracted from the Sun Internet Mail Server directory using sims2sisp. If this file is unavailable when you update the directory configuration, you will need to run addusers later. See the procedure "To Add Sun Internet Mail Server Users to the Solaris ISP Server Directory."

For example:
# sisp2sims -h mail1 -D "cn=ISPadmin,o=MyISP,c=US" -f /tmp/sims_users.ldif Please enter the LDAP Administrator password:
The Solaris ISP Server directory has now been reconfigured as a master of the Sun Internet Mail Server directory and restarted. Replication of the directories will begin if the Sun Internet Mail Server has already been configured as a slave.

Note -
The version of Sun Directory Services included with Sun Internet Mail Server 3.5 does not support the sunds or CRAM MD5 method of encrypting protected data (such as passwords). One of the integration steps performed is to convert the value of protected to crypt in the directory configuration file (dsserv.conf). You must use crypt for the replication with Sun Internet Mail Server to function properly.

If an entry cannot be added because it duplicates an existing entry, its distinguished name will be recorded in /tmp/duplicatesnnn.ldif, where nnn represents the process id of addusers.

Refer to the procedure "To Resolve Conflicts After Adding Users" for help with resolving duplicate data.

To Add Users to the Solaris ISP Server Directory:

This procedure assumes that you have run sims2sisp to generate an ldif file of users from the Sun Internet Mail Server directory and that you have run sisp2sims to reconfigure the Solaris ISP Server directory. If you have not completed these steps, please follow the procedures "To Update the Sun Internet Mail Server Directory:" and "To Update the Solaris ISP Server Directory:" instead of these steps.

Copy the sims_users.ldif file created by the sims2sisp script from the mail directory host to the Solaris ISP Server directory host.

Run the /opt/SUNWisp/ldap/sunds/sbin/addusers script. You will need to specify the dn and password needed to bind to the directory, the full path name to the sims_users.ldif file.

addusers -D bindDN [-w password] -f ldifFile

The -w flag is optional. If you do not specify a password, the script will prompt you to enter one. Using -w to pass the password automatically may be insecure, and you should not use it.

For example:
# ./addusers -D "cn=ISPadmin,o=MyISP,c=US" -f /tmp/sims_users.ldif Please enter the LDAP Administrator password:

The script will attempt to create the Sun Internet Mail Server users in the directory using both the ispSubscriber and the emailPerson object classes. If an entry cannot be added because it duplicates an existing entry, it will be recorded in /tmp/duplicatesnnn.ldif, where nnn represents the process id of addusers.

An attempted entry is considered a duplicate if the distinguished name and the userid attribute match an existing entry. For example, the following entries would be considered duplicates:
```
dn=cn="John Doe (jdoe)",ou="People",o=myisp,c=us
uid=jdoe
mail=John.Doe@myisp.net


dn=cn="John Doe (jdoe)",ou="People",o=myisp,c=us
uid=jdoe
mail=jdoe@virtual.net
```

To Resolve Conflicts After Adding Users:

After you run sisp2sims or addusers to create entries for the Sun Internet Mail Server users in the Solaris ISP Server directory, look for the file /tmp/duplicatesnnn.ldif (where nnn is a process id number).

If the file does not exist, there were no conflicting entries that could not be resolved.

The duplicatesnnn.ldif file contains the dn of original entries for adding users to the directory. Examine each corresponding entry in the sims_users.ldif file to determine whether it represents:
- A true duplicate which can be edited so that the emailPerson attributes are added to the existing ispSubscriber entry;
- A duplicate that occurred because the new entry or the existing entry has incorrect or incomplete data in its dn or userid attribute.

For true duplicates, you can modify the ldif entries so that they modify (rather than replace) the existing entry, then use the modified ldif file with /opt/SUNWconn/bin/ldapmodify to update the directory.

If you do not have this type of entry, skip these steps and go to Step 4
1. Copy sims_users.ldif to another file, such as /tmp/modify.ldif
2. Edit the new file and first remove all entries that you do not want to convert to modify entries.
3. Add a changetype: modify line after each dn that needs to be modified.
4. For a changetype: add entry, all of the attributes are simply listed. For the changetype: modify entries, each new attribute must be preceded by an add: attributeName line.
  
  For example, the line
  
  mailDeliveryOption: mailbox
  
  would be changed to
```
add: mailDeliveryOption
mailDeliveryOption: mailbox
```
5. Delete attributes that you do not need to add.
  
  There may be attributes that you do not need to add. It is likely that the existing attribute already contains all of the required attributes except for the emailPerson object class and its attributes. For example, you will not have to modify the userid attribute since that already exists and has the correct value in the directory.
  
  Be sure not to delete the dn attribute. It is required for ldapmodify to determine which entry to modify.
6. Check the format of the file. Each entry should have the following format:
```
dn: cn="First Last",ou=People,ou=ADomain,o=Organization,c=US
changetype: modify
add: objectClass
objectClass: emailPerson
add: mailDeliveryOption
mailDeliveryOption: mailbox
add: rfc822Mailbox
rfc822Mailbox: uname@ADomain.Organization.com
add: mailQuota
mailQuota: 0
...
```
  This data is just an example. The actual attributes and form of the distinguished name may be different for your data.
7. Run ldapmodify to add the data to the directory.
  
  You will need to specify the distinguished name and password required to bind to the directory to make changes and the name of the input file. You should use the -n to preview the changes and any potential problems before you perform any actual changes. You may also want to use the -c option so that ldapmodify continues after encountering an error (instead of halting at the first error).
  
  For example:
  % cd /opt/SUNWconn/bin % ./ldapmodify -n -c -D "cn=admin,o=Organization,c=US"\ -w secret -f /tmp/updates.ldif

For duplicates that result from incorrect or incomplete data in the directory or the input file, you will need to correct the entry that is causing the problem.

For example, if an entry could not be added because it has the same userid value as an entry in the directory, you must change either the Solaris ISP Server directory entry or the entries in the ldif file to use a new userid.

To Undo Directory Configuration Changes:

The undosims and undosisp commands allow you to restore the configurations of the Sun Directory Services servers to the state before you ran sims2sisp or sisp2sims. These scripts remove the master and slave configurations. Changes to entries in the directory are not undone.

If you have reconfigured both directories, you should undo the configuration changes on both machines. If you only undo one configuration, the other server will still be configured to act as a master or slave.

To undo the configuration of the Solaris ISP Server directory server, log on to the machine and become superuser (root), then run /opt/SUNWisp/ldap/sunds/sbin/undosims.

The script automatically removes the configuration parameters that caused the data to be replicated to the Sun Internet Mail Server directory and restarts the directory service.

To undo the configuration of the Sun Internet Mail Server directory server, first copy the script /opt/SUNWisp/ldap/sunds/sbin/undosisp to the machine.

Next, log on to the Sun Internet Mail Server directory host, become superuser (root), and execute the undosisp script.

The script automatically removes the configuration parameters that caused the directory to be a slave and restarts the directory service.