Populating the Directory Via the SLAPD Server

Starting and Stopping SIMS Components	168
Gathering Data Used to Populate the Directory	168
Gathering Directory Data on Systems Using /etc Files	169
Gathering Directory Data on Systems Using NIS	170
Formatting Data Used to Populate the Directory	174
passwd File Format Rules for imldifsync(1M)	175
aliases File Format for imldifsync	178
Converting the Data to LDIF Format	184
Converting the Data to LDIF Format Using imldifsync(1M), and Adding Data to the Directory Using ldapmodify(1M).	186

When you populate the directory, you will perform the following steps:

---

Note - imldifsync(1M) replaces ldapsync(1M) in Sun Internet Mail Server 3.5, for the purposes of generating LDIF for use by SIMS. imldifsync supports the same interfaces as ldapsync, but in addition supports new features such as the client software Web Access. ldapsync is a deprecated interface and will be eliminated in a future release.

---

The LDIF attributes and interpretation rules needed by SIMS are listed starting on page 175,. Use these to write your own scripts or translation programs to convert passwd and alias file data into LDIF. We recommend that you use imldifsync(1M)at least as an experimental tool to help you understand how to write scripts that generate LDIF.

---

Note - After initially populating the directory with NIS/NIS+ user entries, you must also you must repopulate the directory whenever you update NIS or NIS+ with new email user entries. The procedure we describe for initially populating the directory (in the following sections) is the same procedure for repopulating the directory.

---

Starting and Stopping SIMS Components

You need to have slapd running while populating the directory, because imldifsync will communicate with slapd. The IMTA and imaccessd daemon should not be running as they rely on a correctly populated directory to work properly. These programs should be restarted after populating the directory.

To stop imaccessd and all SIMS components use:

/etc/init.d/im.server stop

When using ldapmodify, ldapadd, or ldapdelete to change what's in the directory, use the following command to ensure SLAPD is running.

/etc/init.d/slapd start

---

Note - The imaccessd process should never be killed using the kill -9 command. Use kill without the -9 argument. If kill -9 is used, run
imcheck -c before restarting imaccessd.

---

Gathering Data Used to Populate the Directory

You will be adding two types of data to the directory:

user information (from /etc/passwd or its equivalent)

user mail alias and distribution list data from /etc/mail/aliases or its equivalent.

This data may come from /etc files or from NIS or NIS+ databases. However it must be in a concise format before it can be converted to LDIF by imldifsync(1M)

The method for extracting distribution list data depends on whether your system is using NIS, NIS+, or /etc files. The following section details how to use the supplied tools to do this for simple user installations. If you have a complex installation you may prefer to write your own tools (using the supplied client side LDAP tools); in that case it is still recommended that you understand the following process before proceeding on your own.

Gathering Directory Data on Systems Using /etc Files

The steps below tell how to obtain user-passwd and mail-alias data from system files. When the SIMS IMTA is installed, mail alias and distribution list information is taken from the directory, rather than /etc/mail/aliases. Unless you set up a way for /etc/mail/aliases to update the directory, it will no longer be used. In this case, you should add a comment in the /etc/mail/aliases file to serve as a warning to other system administrators who attempt to add or update aliases.

$ su

Password: <Enter your root password>

---

Note - During this process be extremely careful to not edit /etc/passwd!

---

# cd /tmp

# sort /etc/passwd > passwd.tmp

# sort /etc/shadow > shadow.tmp

# join -j1 1 -j2 1 -o 1.1 2.2 1.3 1.4 1.5 1.6 1.7 -t: passwd.tmp 
shadow.tmp > passwd

# rm passwd.tmp shadow.tmp

---

Note - You may use the passwd and shadow file directly instead of the "join" above by using the "passwd-file" and "shadow-file" options in the imldifsync.conf file discussed below.

---

# cd /tmp

# cp /etc/mail/aliases aliases

:

Gathering Directory Data on Systems Using NIS

To obtain user-passwd and mail-alias data from system files, perform the following steps:

$ su

Password: <Enter your root password>

---

Note - During this process be extremely careful to not edit /etc/passwd!

---

# cd /tmp

# getent passwd > passwd

3.

Change directory to /tmp and issue the ypcat(1) command as shown to create a mail aliases file for use by imldifsync:

# cd /tmp   # ypcat -k mail.aliases > /tmp/aliases.tmp   # sed 's/ /: /' /tmp/aliases.tmp > /tmp/aliases   # rm aliases.tmp

Gathering Directory Data on Systems Using NIS+

To obtain user-passwd and mail-alias data from system files, perform the following steps:

$ su

Password: <Enter your root password>

---

Note - During this process be extremely careful to not edit /etc/passwd!

---

# cd /tmp

# getent passwd > passwd

3.

Change directory to /tmp and issue the niscat(1) command as shown to create a mail aliases file for use by imldifsync:

# cd /tmp   # niscat mail_aliases.org_dir > /tmp/aliases.tmp   # sed 's/ /: /' /tmp/aliases.tmp > /tmp/aliases   # rm /tmp/aliases.tmp

Formatting Data Used to Populate the Directory

This section describes how to format the user, mail-alias, and distribution list data to successfully populate the directory.

User information must be in the format defined in passwd(4), or as you would find in /etc/passwd. An LDIF file will be generated from different fields of each user entry, and user entries will be cross referenced with user alias information (from data you provide of the format found in aliases(4)) to create LDIF attribute definitions used by SIMS. The imldifsync(1M)command which generates LDIF output makes certain rigid assumptions about the format of the gecos field of a user passwd entry:

passwd File Format Rules for imldifsync(1M)

The imldifsync command converts information in the passwd file to LDIF, which is the format required for adding entries to the directory database. If you do not specify your own conversion program or script with the option --G, imldifsync(1M) uses a default conversion program which expects the gecos field to be in the following format:

...:given-name surname, generation-qualifier - comment:...

The gecos field is the fifth field in the sequence of colon-separated fields in the passwd file.

An example gecos-parsing script which can be used with the -G option is in
/opt/SUNWmail/dir_svc/samples/imgecos2cn.sh, and may be specified in the imldifsync.conf file (discussed below) via the gecos2cn-prog option.

A gecos field that does not conform exactly to this format may still be parsed successfully by imldifsync, and in this case an LDIF directory entry will be created for it; however, a warning message will be generated for each syntactical error that imldifsync encounters, and the resulting attributes may differ from those expected, requiring administrators to make extra efforts to manually ensure the generated LDIF is useful for SIMS.

The following rules are applied when imldifsync parses the gecos field:

Rule 1 -- General Format

The given-name, surname, and generation-qualifier must start with an alphabetic character, can contain alphabetic characters, dashes (-) and single quotes ('), and must end with either an alphabetic character or a period (.). With the specific exceptions described in "Rule 4 -- Surnames" on page 176, uppercase and lowercase characters have no special significance.

The following examples would be converted to valid LDIF directory entries:

:Alice Mary White:

:Philip O'Connor, Jr.:

:John-Paul Simon - mktg consultant:

The following examples would generate a warning message:

:+Aaron J. Brown:

:Esther Great!:

:Mary Anderson *sales*:

Rule 2-- Comments

Anything that follows a space-dash-space sequence ( - ) is interpreted as a comment; also, anything that is enclosed in double quotes or in brackets, even in a non-matching pair, is interpreted as a comment. There can be multiple comments in a single gecos field.

For example:

:Kevin Ascot - Sales Mgr.: the comment is "Sales Mgr."

:Brian Scott (surgeon): the comment is "surgeon"

:Ellen Chelly [CONTRACTOR]: the comment is "CONTRACTOR"

:Ross "the expert" Brand: the comment is "the expert"

:Janice Evans (Quality Group}: the comment is "Quality Group"

:Robert (Bob) Jones - Mktg: the comments are "Bob" and "Mktg"

Rule 3-- Generation-Qualifiers

If there is a comma anywhere in the gecos field (except in comments), the words that follow it are interpreted as a generation-qualifier. The generation-qualifier is optional, but if present, it must not be blank.

The following examples would be converted to valid LDIF directory entries:

:John Smith,Jr.:

:John Smith, Senior:

The following examples would generate a warning message:

:John Smith,:

:John Smith, - Snr:

Rule 4 -- Surnames

The surname is either the last word in the gecos field, or the last word before either a generation-qualifier or a comment. If there is only one word in the gecos field, it is assumed to be the surname. If there are no words in the gecos field, the username is assumed to be the surname.

For example:

:Kate Black: the surname is "black"

:Ann Mary Wells: the surname is "Wells"

:John Smith, Jr.: the surname is "Smith"

:Erwin David BLINK - Engineer: the surname is "BLINK"

Surnames can also consist of several words. In this case, the capitalization is used to distinguish between words that are part of the given-name and words that are part of the surname.

Words that immediately precede the surname, and that are also either all uppercase or all lowercase are interpreted to be part of the surname. This allows naming prepositions such as "le" or "de" in french, and "von" or "van" in german, to be interpreted correctly.

For example:

:Jean-Pierre le GAD: the surname is "le GAD"

:Joe van der Graf: the surname is "van der Graf"

:Jose MARCOS SOUZA: the surname is "MARCOS SOUZA"

:Franz Josef von Bismark: the surname is "von Bismark"

Note the unexpected effect that the application of this rule may have if the gecos field is all lowercase or all uppercase, or if there is an initial letter preceding the surname.

For example:

:gerhard ellis sumner: the surname is "gerhard ellis sumner"

:ADRIENNE CHIU (sales): the surname is "ADRIENNE CHIU"

:Peter K. Wolff: the surname is "K. Wolff"

Rule 5 -- Given-Name

Once the other components of the gecos field have been identified, the remaining words are interpreted as the given-name.

For example:

:Jean-Pierre le GAD: the surname is "gerhard ellis sumner"

:Joe van der Graf: the given-name is "Joe"

:Jose MARCOS SOUZA: the given-name is "Jose"

:Franz Josef von Bismark: the given-name is "Franz Josef"

:Peter K. Wolff: the given-name is "Peter"

If your user passwd information does not meet this criteria then you have three alternatives:

Convert the passwd data to the above format required by imldifsync(1M), using your own custom written scripts to modify the gecos field. Run imldifsync using that data.

Write your own gecos parsing script as documented in the imldifsync manpage, using the example gcos2cn.sh, in /opt/SUNWmail/ldap/samples, and pass that to imldifsync(1M) via the -G flag

Do not use imldifsync at all, but instead write your own LDIF generator that produces LDIF entries with the attributes that SIMS requires.

aliases File Format for imldifsync

The imldifsync(1M) command makes assumptions about the format of the mail aliases file used as input. The command uses the information in the aliases file to generate attributes for an entry. The expected format for the aliases file is described below.

---

Note - Refer to the manpage for the aliases(4) file for general usage information.

---

Rule 1 -- General Format for User Aliases

For each user, the aliases file must contain two lines in the following format:

userid: first.lastname   first.lastname: userid@mailhost

where:

When the aliases file contains this type of information for a user, imldifsync(1M) creates the following attributes:

preferredRfc822Originator with value first.lastname@maildomain

preferredRfc822Recipient with value userid@mailhost.maildomain

rfc822Mailbox with values first.lastname@mailhost.maildomain, userid@mailhost.maildomain, and also with the same value as preferredRfc822Originator

mailDeliveryOption with value mailbox

mailHost with value mailhost.maildomain

---

Note - The maildomain in the attribute values is the mail domain declared in the configuration file for the imldifsync command. This mail domain must be the same as the one declared in the slapd.conf configuration file.

---

For example, the aliases file contains the following lines for user Allyn Robinson:

arobin: allyn.robinson   allyn.robinson:arobin@cloud

The imldifsync command extracts the following attributes and attribute values from this information:

preferredRfc822Originator: allyn.robinson@Marketing.XYZ.COM   preferredRfc822Recipient: arobin@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn.robinson@cloud.Marketing.XYZ.COM   rfc822Mailbox: arobin@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn.robinson@Marketing.XYZ.COM   mailDeliveryOption: mailbox   mailHost: cloud.Marketing.XYZ.COM

Rule 2 -- Handling Differing User IDs

The user ID supplied on the first line can be different from the user ID on the second line.

userid1: first.lastname   first.lastname: userid2@mailhost

In such cases, imldifsync(1M) creates the mailDeliveryOption attribute with the value forward, and also creates a mailForwardingAddress attribute.

For example, the aliases file could contain the following lines for user Allyn Robinson:

arobin: allyn.robinson   allyn.robinson:jconnors@cloud

The imldifsync command extracts the following attributes and attribute values from this information:

preferredRfc822Originator: allyn.robinson@Marketing.XYZ.COM   mailForwardingAddress: allyn.robinson@cloud.Marketing.XYZ.COM   mailForwardingAddress: jconnors@cloud.Marketing.XYZ.COM   mailDeliveryOption: forward

Combining Rule 1 and Rule 2

You can combine the general format described in Rule 1 with the format described in Rule 2, as follows:

userid1: first.lastname   first.lastname: userid1@mailbox, userid2@mailhost

In such cases, imldifsync(1M)creates the mailDeliveryOption attribute with the values mailbox and forward, and creates the mailForwardingAddress attribute.

For example, the aliases file could contain the following lines for user Allyn Robinson:

arobin: allyn.robinson   allyn.robinson:arobin@cloud, jconnors@cloud

The imldifsync command extracts the following attributes and attribute values from this information:

preferredRfc822Originator: allyn.robinson@Marketing.XYZ.COM   preferredRfc822Recipient: arobin@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn.robinson@cloud.Marketing.XYZ.COM   rfc822Mailbox: arobin@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn.robinson@Marketing.XYZ.COM   mailForwardingAddress: jconnors@cloud.Marketing.XYZ.COM   mailDeliveryOption: mailbox   mailDeliveryOption: forward   mailHost: cloud.Marketing.XYZ.COM

Rule 3-- Handling Nicknames

An aliases file can contain more than two lines per user, in which case, the format to observe is:

userid: first.lastname   nickname1:first.lastname   nickname2:first.lastname   first.lastname: userid@mailhost

In such cases, the imldifsync(1M) command creates the rfc822Mailbox attribute with an extra value for each nickname.

For example, the aliases file could contain the following lines for user Allyn Robinson:

arobin: allyn.robinson   arobinson: allyn.robinson   allyn: allyn.robinson   allyn.robinson: arobin@cloud

The imldifsync command extracts the following attributes and attribute values from this information:

preferredRfc822Originator: allyn.robinson@Marketing.XYZ.COM   preferredRfc822Recipient: arobin@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn.robinson@cloud.Marketing.XYZ.COM   rfc822Mailbox: arobin@cloud.Marketing.XYZ.COM   rfc822Mailbox: arobinson@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn@cloud.Marketing.XYZ.COM   rfc822Mailbox: allyn.robinson@Marketing.XYZ.COM   mailDeliveryOption: mailbox   mailHost: cloud.Marketing.XYZ.COM

Rule 4-- Handling File Names in Aliases

A user alias in the aliases file can contain a file name, following this format:

userid: first.lastname   first.lastname: filename

where filename must start with a slash ( / ).

In such cases, imldifsync(1M) creates the mailDeliveryOption attribute with the value "file", and also creates a mailDeliveryFile attribute.

For example, the aliases file could contain the following lines for user Allyn Robinson:

arobin: allyn.robinson   allyn.robinson:/var/allyn/mail

The imldifsync command extracts the following attributes and attribute values from this information:

preferredRfc822Originator: allyn.robinson@Marketing.XYZ.COM   mailForwardingAddress: allyn.robinson@cloud.Marketing.XYZ.COM   mailDeliveryFile: /var/allyn/mail   mailDeliveryOption: forward   mailDeliveryOption: file

Rule 5-- Handling Program Names in Aliases

A user alias in the aliases file can contain a program name, following this format:

userid: first.lastname   first.lastname: |programName

Note that the pipe ( | ) symbol is required to introduce a program name.

In such cases, imldifsync(1M)creates the mailDeliveryOption attribute with the value "program", and also creates a mailProgramDeliveryInfo attribute.

For example, the aliases file could contain the following lines for user Allyn Robinson:

arobin: allyn.robinson   allyn.robinson:|/bin/cat

The imldifsync command extracts the following attributes and attribute values from this information:

preferredRfc822Originator: allyn.robinson@Marketing.XYZ.COM   mailForwardingAddress: allyn.robinson@cloud.Marketing.XYZ.COM   mailProgramDeliveryInfo: /bin/cat   mailDeliveryOption: forward   mailDeliveryOption: program

Rule 6-- General Format for Group Aliases

For each group (distribution list), the aliases file must contain two lines in the following format:

owner-aliasname: owner1 [owner2 ...]   [aliasname-request: processor]   aliasname: user1, user2, user3 ...

where:

A person with an entry in the directory

A person known by an rfc822 mail address without an entry in the directory

A program, introduced by the pipe ( | ) symbol

A file, introduced by a slash ( /)

Depending on where you obtained your data (/etc files, NIS, NIS+) you may have to further format data.

Converting the Data to LDIF Format

LDIF (LDAP Data Interchange Format) is a canonical data form used to represent entries in LDAP databases. Currently a draft-Internet-RFC, LDIF is designed to be a transportable intermediate data form that is portable between LDAP directories. Data must be converted to LDIF before it can be added to the directory. Administrators may use one of several methods to generate LDIF:

Use the supplied imldifsync(1M) program to synchronize input data with data already added to the directory (if such exists).

Write your own scripts or programs to generate LDIF based on passwd, user alias, and distribution list data.

---

Note - Although this section will involve two files; passwd data first, alias/distribution-list data second, both user passwd and user alias information will be required in the first pass. Do not continue until you have both data-sets ready to use.

---

A Few Words About imldifsync(1M)

imldifsync(1M) does several things:

maps password and alias entry information into LDIF output.

correlates password file user entries with alias file user entries.

creates certain LDIF attribute values based on passwd and alias input.

fabricates certain DNs required by slapd if they are not present in the ldbm.

synchronizes changes in the input password and alias files and converts those differences to LDIF. imldifsync may be used to periodically synchronize the LDAP directory with changes to the password and alias files (for example, if users are added or deleted to the password file).

The default configuration file, imldifsync.conf, is installed in
/etc/opt/SUNWmail/dir_svc/imldifsync.conf. Converting data using imldifsync is a two phase process. First, the user/passwd data is converted, then the mail-alias/groups data. You will need two separate configuration files, one for each phase. We will call these two files passwd.conf and aliases.conf.

The SIMS installation GUI will set certain values in the default imldifsync.conf based on your input. You should keep track of the settings by keeping an untouched copy of imldifsync.

---

Note - The imldifsync.conf file is readable only by root, because the file contains the "bind-DN" and "ldap-passwd" directives, which the SIMS install GUI will set based on what you enter as your Administrative password. You should be aware that anyone with this bind-DN and password can change any aspect of the Directory contents or configuration, and guard the bind-DN and password appropriately.

---

You should be sure that the following lines in the imldifsync.conf are set to values which make sense in the context of your location, organizational structure, and/or Directory Information Tree (DIT):

bind-DN = "cn=Admin, o=XYZ, c=US"

CN is the administrator name provided during installation.

ldap-passwd = "secret"

This is the administrator password provided during the installation.

---

Note - This information is used for ldapadd, ldapmodify, ldapdelete and ldapsearch binding and access checking. Anyone with this information can modify your directory and can get into the Administration Console. Protect your information accordingly!

---

group-base = "ou=Groups, ou=eng, o=XYZ, c=US"

base = "ou=people,ou=eng,o=XYZ,c=US"

This information defines the DIT within your directory, and is used as arguments to directory queries, including using the -b flag of ldapsearch(1). These will be set to a value based on input to the SIMS installation procedure.

mail-domain = "Marketing.XYZ.COM"

super-domain = "XYZ.COM"

This information is used to generate LDIF used by SIMS to determine if incoming mail matches recipients in the LDAP Directory. They should match the DNS domain name in which the SIMS server is operating.

Converting the Data to LDIF Format Using imldifsync(1M), and Adding Data to the Directory Using ldapmodify(1M).

# cd /etc/opt/SUNWmail/dir_svc

# cp imldifsync.conf imldifsync.conf.SIMS3.5

# vi imldifsync.conf

2.

Uncomment the mode = users, mail-server, passwd-file, and aliases-file files, and change the mail-server, passwd-file, and aliases-file values as shown:

mail-server = "<mailserverhostname>.<fully qualified domain name>"   passwd-file = "/tmp/passwd"   aliases-file = "/tmp/aliases"   mode = users

In the above example, your mailserverhostname should be the name of the mailserver hostname on which you're running SIMS, and the fully qualified domain name should be equivalent to the mail-domain attribute in imldifsync.conf.

By default the imldifsync.conf file contains two lines like this:

add-val = { "mailFolderMap: SUN-MS" }   ignore-attr = { "mailFolderMap" }

"SUN-MS" is the recommended mailstore for SIMS. However if you chose to use the "/var/mail" type of message store during your Install, you should change "SUN-MS" to "UNIX V7".

You may choose to add other attributes here as well, but there are two rules that must be followed:

Only attributes from the default SIMS schema may be added in this way. User created attributes cannot be added through this interface.

As shown in the example, only attributes which have values common to all users (for the user data generation pass) or groups (for the group/alias-data generation pass) should be added here.

3.

Create two copies of the imldifsync.conf files, one for users (for example, users.conf) and one for user aliases/distribution lists (for example, groups.conf).

# cp imldifsync.conf users.conf   # cp imldifsync.conf groups.conf

4.

Edit the groups.conf file, change the add-val line as shown below and change the mode token from users to groups.

add-val = { "associatedDomain: <same value as mail-domain> }   mode = groups

mail-domain value should be lower down in the same file.

5.

If you want to set a user mail store quota edit users.conf.

The SIMS default setting is "no limit." To set a space limit, modify the mailQuota attribute as follows:

add-val = { "mailQuota: <quota in bytes>" , "mailFolderMap: SUN-MS" }

where <quota in bytes> would be 10000000 if you wanted to set a mail space quota of 10 megabytes. See "Message Store Quota Enforcement" on page 148 for detailed information on setting quotas.

6.

Convert the user data to LDIF format.

Use the imldifsync command to generate formatted user data (LDIF) by issuing the following command:

# /opt/SUNWmail/sbin/imldifsync -c users.conf > /tmp/users.ldif

7.

Populate the directory with the user LDIF formatted data.

This must be done before running imldifsync during the alias-data generation pass because imldifsync compares existing data in the directory to newly generated data to determine what will be generated as the groups data.

Use the ldapmodify command to add the new entries to the directory:

# /opt/SUNWmail/bin/ldapmodify -D bind-DN -w ldap-passwd -f /tmp/ users.ldif

Refer to the bulleted section above for bind-DN and ldap-password information.

---

Note - If you already have some entries in the Directory database you should specify the -c argument to ldapmodify in addition to those above, so that ldapmodify will continue to the new entries. ldapmodify will otherwise exit if it tries to add an entry that is already in the Directory.

---

# /opt/SUNWmail/sbin/imldifsync -c groups.conf > /tmp/groups.ldif

9.

Populate the directory with the aliases/distribution-list LDIF formatted data.

Use the ldapmodify command to add the new entries to the directory:

# /opt/SUNWmail/bin/ldapmodify -D bind-DN -w ldap-passwd -f /tmp/ groups.ldif

Refer to the bulleted section above for bind-DN and ldap-password information.

---

Note - If you already have some entries in the Directory database you should specify the -c argument to ldapmodify in addition to those above, so that ldapmodify will continue to the new entries. ldapmodify will otherwise exit if it tries to add an entry that is already in the Directory.

---