Difference between revisions of "Omldapsync HowTo - Two"

Revision as of 17:33, 17 July 2008

How it Works

omldapsync stores its information in /var/opt/scalix/??/s/ldapsync; this directory is created when the first omldapsync agreement is defined.

In the ldapsync directory are subdirectories, one for each omldapsync agreement.

The ldapsync.log file is also stored here. It records the execution of various omldapsync commands and their output. For example, you can see when agreements were created, when synchronizations ran, and if you run omldapsync with debugging enabled (-d option), you will also see the debugging output.

A New Agreement

When a new agreement is created, a subdirectory is created under /var/opt/scalix/??/s/ldapsync; the subidrectory has the same name as the sync agreement, for example /var/opt/scalix/??/s/ldapsync/13fubar.

Within this agreement subdirectory are the following files and directories:

sync.cfg 

this is the configuration file you edited when you created the agreement with the omldapsync -c 13fubar command. If you have errors in your log that suggest improper configuration of your agreement, you can edit this file directly or you can run omldapsync -c 13fubar again and elect to replace the old config file with the new.

sync.last 

a copy of your old sync.cfg file. If you totally mess things up and wish you could go back to your old config file, this is where you get it. Only one copy is stored, so you can only go back one version.

sync.log 

this is similar to the ldapsync.log file, but it only contains entries pertaining to the omldapsync agreement that has the same name as the agreement subdirectory, for example, 13fubar.

import 

this is the working directory for the import portion of the synchronization agreement.

export 

this directory is not used by a type 13 omldap synchronization agreement, because type 13 agreements only import data from the LDAP server; they don't export. It is created but will remain empty.

The First Synchronization

For demonstration purposes, we'll start with one simple (non-Scalix user) entry in the LDAP directory.

? cat /tmp/addmouse
dn: uid=MMouse,dc=mydomain,dc=net
givenName: Mildred
sn: Mouse
telephoneNumber: 800-555-1212
mail: mildred@fubar.mydomain.net
facsimileTelephoneNumber: 800-222-0000
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
uid: MMouse
preferredLanguage: en
cn: Mildred Mouse

OpenLDAP:

$ ldapadd -x -D cn=admin,dc=mydomain,dc=net -w secret -f /tmp/addmouse

SunONE:

$ ldapadd -D "cn=directory manager" -w secret -f /tmp/addmouse

Synchronize with the command omldapsync -u 13fubar; for output that is a little more informative you can enable debugging. While this isn't practical all the time, it is good tool for learning.

# omldapsync -u 13fubar -d1

After the synchronization is complete you can verify that the entry was imported.

# omsearch -e s=mouse
CN=Mildred Mouse/G=Mildred/S=Mouse/OU1=internet/ADMINISTERED-BY=ldapsync-13fubar/PHONE-1=800-555-1212/FAX=800-222-0000/FOREIGN-ADDR=uid\=MMouse,dc\=mydomain,dc\=net/INTERNET-ADDR=mildred@fubar.mydomain.net

The log file for this agreement, /var/opt/scalix/sb/s/ldapsync/13fubar/sync.log, has a fair amount of output because we used the -d1 option. Among other things, it shows the remote directory being searched and one entry found for adding:

2008-02-06 16:45:12 STATUS: search source directory on fubar.mydomain.net ...
2008-02-06 16:45:12 INFO: search base is dc=mydomain,dc=net
2008-02-06 16:45:12 INFO: ... 5 entries to check
2008-02-06 16:45:13 STATUS: find delta and perform mapping ...
2008-02-06 16:45:14 INFO: ... 0 entries to delete
2008-02-06 16:45:14 INFO: ... 1 entries to add
2008-02-06 16:45:14 INFO: ... 0 entries to modify

If you encounter problems, a good way to begin troubleshooting is to run omldapsync with the -d1 option and then examine your sync.log file.

In the import directory, a lot of new files have been created. Of particular interest is the add.curr file, which shows the entry as it came from the remote LDAP server, and again after it was added to the Scalix directory.

dn: uid=MMouse,dc=mydomain,dc=net
uid: MMouse
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
sn: Mouse
givenname: Mildred
mail: mildred@fubar.mydomain.net
nsUniqueID: 37906181-d43011dc-80eeab21-efb0ae03
cn: Mildred Mouse
facsimileTelephoneNumber: 800-222-0000
telephoneNumber: 800-555-1212

dn: uid=MMouse,dc=mydomain,dc=net
FOREIGN-ADDR: uid=MMouse,dc=mydomain,dc=net
UL-AUTHID: MMouse
objectClass: organizationalPerson
S: Mouse
G: Mildred
INTERNET-ADDR: mildred@fubar.mydomain.net
GLOBAL-UNIQUE-ID: 37906181-d43011dc-80eeab21-efb0ae03
CN: Mildred Mouse
FAX: 800-222-0000
PHONE-1: 800-555-1212
ADMINISTERED-BY: ldapsync-13fubar

This can be helpful when trying to figure out how data is being imported. You can see the data brought in from LDAP and the data applied to Scalix. For example, you can see that the Scalix GLOBAL-UNIQUE-ID takes the same value as the LDAP userUUID or the nsUniqueID, and that the INTERNET-ADDR is derived from the mail attribute. The mapping table is used to define how particular attributes get their values assigned.

The Second Synchronization

Now we'll add a second entry to our LDAP directory.

? cat /tmp/addduck
dn: uid=DDuck,dc=mydomain,dc=net
uid: DDuck
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
givenName: Dora
sn: Duck
cn: Dora Duck
mail: dora.duck@fubar.mydomain.net

OpenLDAP:

$ ldapadd -x -D cn=admin,dc=mydomain,dc=net -w secret -f /tmp/addduck

SunONE:

$ ldapadd -D "cn=directory manager" -w secret -f /tmp/addduck

Synchronize to the Scalix server:

# omldapsync -u 13fubar -d1

Two entries in the LDAP directory match our criteria for synchronization. There are no modifications or deletions, but there will be one addition:

2008-02-07 08:45:27 STATUS: search source directory on fubar.mydomain.net ...
2008-02-07 08:45:27 INFO: search base is dc=mydomain,dc=net
2008-02-07 08:45:28 INFO: ... 2 entries to check
2008-02-07 08:45:28 STATUS: find delta and perform mapping ...
2008-02-07 08:45:30 INFO: ... 0 entries to delete
2008-02-07 08:45:30 INFO: ... 1 entries to add
2008-02-07 08:45:30 INFO: ... 0 entries to modify

You can verify the entry was added with an omsearch command:

# omsearch -e s=duck
CN=Dora Duck/G=Dora/S=Duck/OU1=internet/ADMINISTERED-BY=ldapsync-13fubar/FOREIGN-ADDR=uid\=DDuck,dc\=mydomain,dc\=net/INTERNET-ADDR=dora.duck@fubar.mydomain.net

Here's what's going on behind the scenes. omldapsync searches the Scalix SYSTEM directory and the LDAP directory and stores the combined results in search.curr. In our example of a newly created LDAP directory and a new omldapsync agreement, it just found two entries. One is Mildred Mouse and one is Dora Duck.

omldapsync then compares search.curr to search.last, and applies the differences to the Scalix directory. In our case, Mildred Mouse is in both files but Dora Duck is only in search.curr so Dora Duck will be added to the Scalix SYSTEM directory.

If the synchronization was successful, omldapsync stores the results of search.curr to search.last, and moves search.last to search.last.[0-9]. After search.last.1 is used, then search.last.2 will be used, then 3,4...9,0,1,2 and it continues in a cycle.

If the synchronization encountered problems, search.curr will be kept on disk so that corrections can be made and the synchronization can be run again against the current snapshot.

If you're using this document as a tutorial and executing the commands as they're discussed, you can examine the files in the /var/opt/scalix/??/s/ldapsync/13fubar/import directory. You'll see that the most recent search.last.# file contains the results of the search when only Mildred Mouse was returned. The search.last file contains the results of the most recent search, when Mildred Mouse and Dora Duck were found.

Subsequent Synchronizations

In subsequent synchronizations, you may see the following files get created or updated, depending on what occurred during the sync. Additions to this section of the document would be most welcome.

add.curr 

only created if new entries exist in LDAP which need to be added to Scalix.

add.curr.dist 

distribution lists (groups) to be added to Scalix.

add.cur.memb 

members to be added to distribution lists (groups).

add.curr.user 

The user entries which are to be added (as opposed to group entries to be added).

add.pass 

The entries to be added which pass all the tests and actually get added to Scalix.

delete.curr 

only created if entries have been removed from LDAP and need to be deleted from Scalix.

delete.curr.user 

The users to be deleted (as opposed to groups).

delete.fail 

The entries which can't be deleted for some reason. The log file will show the reason.

delete.pass 

The entries which actually get deleted from Scalix.

empty.to.prev 

When modifying a distribution list (group), a changetype: modify is done to the group in LDAP. The modification is replace: member and a complete member list is provided. During omldapsync, this behavior is imitated; first all members are deleted and then all members are added. empty.to.prev lists the members to be deleted so that the distribution list is empty. Then the entire accurate membership list is added.

membadd.pass 

Members to be added to distribution lists (groups) that pass all the test criteria.

membdelete.pass 

Members to be deleted from distribution lists (groups) that pass all the test criteria.

member.curr 

Entries that are already members of the Scalix directory, whether internet users or Scalix account holders. Used during modifications.

member.curr.dist 

A subset of member.curr; it contains distribution lists (groups).

member.curr.memb 

Seems to be the same as member.curr.dist.

member.curr.user 

A subset of member.curr; only the user entries (as opposed to group entries).

search.curr 

Basically the result of a search against the SYTEM driectory combined with an ldapsearch against the LDAP directory. Only retained if omldapsync fails; usually by the time you look at the files, this one has been renamed to search.last. If it exists, its contents are used rather than doing a new ldapsearch. The contents of add.curr, delete.curr, modify.curr, etc. are built by comparing search.curr to search.last.

search.last 

When omldapsync completes successfully, search.curr is renamed to search.last.

search.last.[0-9] 

archival copies of search.last. The files are not rotated; that is, search.last.0 does not always contain the results of the search immediately prior to search.last. Rather, search.last is written to search.last.1, then search.last.2, then search.last.3, and so on. After search.last.9 is written, it starts over and search.last.0 will be written, then search.last.1, search.last.2, and so on.

search.temp 

Whenever temp.curr is written to, the old temp.curr goes into search.temp.

temp.curr 

The current search results. Usually this matches search.last but if there are errors and search.curr is retained rather than being written to search.last, temp.curr will match search.curr.

util.input

util.log

Converting an Entry to a Scalix Account

In this section we will go over the steps required to provision a new mailbox on Scalix by adding and/or modifying entries in OpenLDAP. In this exercise, we will convert "Dora Duck" to a Scalix user.

First, create a file to be used with the ldapmodify command. The file below assigns a value to all the Scalix attributes. You will probably never use all the attributes but it's nice to see what is available. For an explanation of what they do, see the documentation in the schema (a copy is provided in the appendices).

$ cat /tmp/duckmod
dn: uid=DDuck,dc=mydomain,dc=net
changetype: modify
replace: objectClass
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
objectClass: scalixUserClass
-
add: scalixScalixObject
scalixScalixObject: TRUE
-
add: scalixMailnode
scalixMailnode: mail,node
-
add: scalixEmailAddress
scalixEmailAddress: dora.duck@fubar.mydomain.net
scalixEmailAddress: DDuck@mydomain.net
scalixEmailAddress: dora@mydomain.net
-
add: scalixAdministrator
scalixAdministrator: TRUE
-
add: scalixMailboxAdministrator
scalixMailboxAdministrator: FALSE
-
add: scalixServerLanguage
scalixServerLanguage: ENGLISH
-
add: scalixLimitMailboxSize
scalixLimitMailboxSize: 500
-
add: scalixLimitOutboundMail
scalixLimitOutboundMail: TRUE
-
add: scalixLimitInboundMail
scalixLimitInboundMail: FALSE
-
add: scalixLimitNotifyUser
scalixLimitNotifyUser: TRUE
-
add: scalixHideUserEntry
scalixHideUserEntry: FALSE
-
add: scalixMailboxClass
scalixMailboxClass: FULL

Now in this modification file, I've included all the Scalix attributes just to make a fairly complete example. To convert an LDAP entry to a Scalix user account, the minimum you must do is add the scalixUserClass objectClass, and the scalixScalixObject and scalixMailnode attributes. The rest are optional.

Update the LDAP entry.

OpenLDAP:

$ ldapmodify -x -D cn=admin,dc=mydomain,dc=net -w secret \
-f /tmp/duckmod      

Sun ONE:

$ ldapmodify -r -D "cn=directory manager" -w secret \
-f /tmp/duckmod             

You'll get an error if you have any typos or syntax errors in your file, but to verify all the changes took place as expected, you can search for the entry:

OpenLDAP:

$ ldapsearch -x -b dc=mydomain,dc=net cn="dora duck"

Sun ONE:

$ ldapsearch -b dc=mydomain,dc=net "cn=dora duck"

# DDuck, mydomain.net
dn: uid=DDuck,dc=mydomain,dc=net
uid: DDuck
givenName: Dora
sn: Duck
cn: Dora Duck
mail: dora.duck@fubar.mydomain.net
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: scalixUserClass
scalixScalixObject: TRUE
scalixMailnode: mail,node
scalixAdministrator: TRUE
scalixEmailAddress: dora.duck@fubar.mydomain.net
scalixEmailAddress: DDuck@mydomain.net
scalixEmailAddress: dora@mydomain.net
scalixMailboxAdministrator: FALSE
scalixServerLanguage: ENGLISH
scalixLimitMailboxSize: 500
scalixLimitOutboundMail: TRUE
scalixLimitInboundMail: FALSE
scalixLimitNotifyUser: TRUE
scalixHideUserEntry: FALSE
scalixMailboxClass: FULL

Now we're ready to synchronize those changes into the Scalix server:

# omldapsync -u 13fubar -d1

NOTE: There is a minor bug with omldapsync which causes an error to occur if the scalixAdministrator attribute is in the modification. If this occurs, simply re-run omldapsync -u and the second iteration will run without incident.

Once the synchronization has completed, you can see that the entry is no longer merely an entry in the directory, but a full Scalix user:

# omshowu -n duck
Authentication ID: DDuck
Globally Unique ID: d55dafbe-8872-102c-9d8b-d586cd1e6306
User Name : Dora Duck /CN=Dora Duck
MailNode : mail,node
Internet Address :  dora.duck@fubar.mydomain.net=DDuck@mydomain.net=dora@mydomain.net
System Login : 60550
Password : unset
Admin Capabilities : YES
Mailbox Admin Capabilities : NO
Language : ENGLISH
Mail Account: Unlocked
Last Signon : Never.
Receipt of mail : ENABLED
Service level : 0
Excluded from Tidying : NO
Recovery Folder visible : NO
User Class : Full
SIS URL : sxidx://sxlab.mydomain.net/09a000005fb1fb74-121.0.861.291

NOTE: When assigning multiple email addresses, remember that the order is significant! When a Scalix account has multiple email addresses, it will receive messages addressed to any of the addresses. When the account sends out a message, the first email address will be used for the From and Reply-To values in that sent message.

The Password

You may have noticed in the exercises with Dora Duck, the account was created with the password unset. Even if we give Dora Duck a password on the LDAP system, her Scalix account will be created with the password unset. This is because passwords are encrypted in LDAP, and there is no way to "unconvert" the password for storage in Scalix.

So... what to do?

There are four options:

• Let the user login with his LDAP password. Don't let people change their password from the email client. This restricts password control to an outside application.
• Let the user login with their LDAP password, and if they opt to change their password from within the email client, the password in the LDAP directory gets changed.
• Let the user log in with either their email *or* their LDAP password. They can change their email password from the email client, but not their LDAP password. The two passwords are not synchronized; either one will work for login, but only the email password can be changed from the email client.
• Let the user log in with his email password only. The email and LDAP passwords are completely separate and unrelated (though the user could set them to the same value if he chose).

Outside Application

Let the user login with his LDAP password. Don't let people change their password from the email client. This restricts password control to an outside application.

• Add sxadmin and any other existing accounts to the LDAP directory as outlined in the section "Integrating Existing Scalix Mailboxes into LDAP".
• In /var/opt/scalix/??/s/sys/pam.d, edit the following files (create them if they do not exist):
  
  • ual.remote
    
  • smtpd.auth
    
  • pop3
    

The contents of the above files should be as follows:

auth sufficient om_ldap
auth required pam_deny 
account required om_auth 
password required om_auth 
session required om_auth

• Edit or create /var/opt/scalix/??/s/sys/pam.d/omslapdeng with the following contents:

auth sufficient om_ldap
auth sufficient om_auth 
auth required pam_deny 
account required om_auth 
password required om_auth 
session required om_auth

• Edit or create /var/opt/scalix/??/s/sys/om_ldap.conf:

host=fubar.mydomain.net
search=subtree
base=dc=mydomain,dc=net
filter=uid=%s
tls=off

• Restart Scalix

omshut; omrc

Change LDAP Password from email Client

Let the user login with their LDAP password, and if they opt to change their password from within the email client, the password in the LDAP directory gets changed. For more information on this, see the HowTo entitled "Using OpenLDAP for password management" in the Scalix Wiki.

• The user must have userPassword set in the LDAP directory.
• On the Scalix server, you must have pam_ldap and/or nssldap installed.
• Edit /etc/ldap.conf; the binddn and bindpw are optional:

# Your LDAP server. Must be resolvable without using LDAP.
host fubar.mydomain.net
	
# The distinguished name of the search base.
base dc=mydomain,dc=net

# The LDAP version to use (defaults to 3
# if supported by client library)
ldap_version 3

# The distinguished name to bind to the server with.
# Optional: default is to bind anonymously.
binddn cn=directory manager

# The credentials to bind with.
# Optional: default is no credential.
bindpw secret

• If you do not have SSL enabled, be sure you have it commented out in /etc/ldap.conf.
• In /var/opt/scalix/??/s/sys/pam.d, edit the following files (create them if they do not exist):
  • ual.remote
  • smtpd.auth
  • pop3
  • omslapdeng
• The contents of the above files should be as follows:

auth required om_om2authid
auth sufficient /lib/security/pam_ldap.so ignore_unknown_user
auth sufficient om_auth use_first_pass
auth required pam_deny
account sufficient om_auth
account required /lib/security/pam_ldap.so
password required om_auth preauth
password required om_om2authid
password required /lib/security/pam_ldap.so
session required /lib/security/pam_ldap.so

• Edit or create /var/opt/scalix/??/s/sys/om_ldap.conf:

host=fubar.mydomain.net
search=subtree
base=dc=mydomain,dc=net
filter=uid=%s
tls=off

• Edit /var/opt/scalix/??/s/sys/pam.d/pamcheck:

auth required om_debug
account required om_debug
session required om_debug
password required om_debug
auth required om_om2authid
auth required /lib/security/pam_ldap.so
account required /lib/security/pam_ldap.so
password required om_om2authid
password required /lib/security/pam_ldap.so
session required /lib/security/pam_ldap.so

• Restart Scalix

omshut; omrc

• Test the configuration with sxpamauth; note that you only use the surname, not the entire UID:

# sxpamauth -vvv duck
pam_start_om("pamcheck", "duck")
pam_authenticate()
Password:
pam_acct_mgmt()

Authenticated

Dual Passwords

Let the user log in with either their email *or* their LDAP password. They can change their email password from the email client, but not their LDAP password. The two passwords are not synchronized; either one will work for login, but only the email password can be changed from the email client.

• The user must have userPassword set in the LDAP directory
• In /var/opt/scalix/??/s/sys/pam.d, edit the following files (create them if they do not exist):
  • ual.remote
  • smtpd.auth
  • pop3
  • omslapdeng
• The contents of the above files should be as follows:

auth sufficient om_ldap
auth sufficient om_auth 
auth required pam_deny 
account required om_auth 
password required om_auth 
session required om_auth

• Edit or create /var/opt/scalix/??/s/sys/om_ldap.conf:

host=fubar.mydomain.net
search=subtree
base=dc=mydomain,dc=net
filter=uid=%s
tls=off

• Restart Scalix

omshut; omrc

Separate email Password

Let the user log in with his email password only. The email and LDAP passwords are completely separate and unrelated (though the user could set them to the same value if he chose).

When a new account gets created in Scalix due to having scalixUserClass, scalixScalixObject, and scalixMailnode set in the LDAP directory, the following steps should be taken:

• Set the password:

ommodu {authentication-id|-o name[/mailnode]} -p password

• Auto-expire the password.

ommodu {authentication-id|-o name[/mailnode]} -e

You can use scripts to set and auto-expire the password. Both of these steps are optional, but auto-expiration is especially recommended. This is done in order to prevent undetected, unwanted access to an account.