View source for Omldapsync HowTo - One

== About This Document ==
This document is intended to assist you in synchronizing a Scalix server with an LDAP directory.   OpenLDAP and Sun ONE Directory Server are used for examples; in the future it would be nice to include examples of omldapsync with Active Directory.  

We'll cover configuration of the LDAP server, creation of the omldapsync agreement, using the LDAP directory for authentication, and there will be an overview of how omldapsync works.

While writing this paper, the following software was used:
* Scalix 11.3.0 running on RedHat Enterprise 5.1 (Tikanga)
* OpenLDAP 2.3.35 running on Ubuntu 7.1 (Gutsy Gibbon)
* Sun ONE Directory Server  Version 5 2005Q4 (5.2 P6) running on Solaris 10 for X86

Many, many thanks to Karl Buchner for his paper Using omldapsync with OpenLDAP and Scalix 11.  A significant portion of this text was stolen directly from that document, with his permission.

== Preparing to synchronize with Scalix ==
=== Configure the Remote Directory ===
In order to synchronize the remote directory with Scalix, we must configure the remote server so that it is aware of some special Scalix attributes.  This is done via extending the remote directory's schema.  We must also ensure that the remote server is configured so that it will send back all the relevant entries.
==== OpenLDAP ====
The OpenLDAP schema files are typically located in ''/etc/ldap/schema'' or ''/etc/openldap/schema''.  

The OpenLDAP ''slapd.conf'' file is typically located in ''/etc/ldap'' or ''/etc/openldap''.

* Stop the OpenLDAP slapd server.
* Copy ''/var/opt/scalix/??/s/sys/ldapsync13.schema'' from the Scalix server to your OpenLDAP server's schema directory and ensure that the copied file is world readable. 
* Add an "include" statement to the ''slapd.conf'' file as follows, using a path appropriate to your environment:
 include         /etc/ldap/schema/ldapsync13.schema
* After the database directive for the directory you wish to synchronize with Scalix, ensure the following values are set in ''slapd.conf'' according to your environment:

 database        bdb
 suffix          "dc=mydomain,dc=net"
 rootdn          "cn=admin,dc=mydomain,dc=net"
 rootpw          {SSHA}EGBbPLdQg0o5RoUQBwIQBkymApuC/YFa
 directory       "/var/lib/ldap/mydomain"

* To generate an encrypted password, use the ''slappasswd'' command and enter the password when prompted.
* If you have multiple databases, they must each have their own directory.
* Ensure the ''sizelimit'' in ''slapd.conf'' is large enough for LDAP to return all the matching entries to omldapsync.
* Restart slapd. 

The ''ldapsync13.schema'' file does not require editing.

==== Sun ONE Directory Server ====
* Ensure the sizelimit is large enough for LDAP to return all the matching entries to omldapsync.
** Login to the System Server Console and double-click the Directory Server for your host.
** Select the Configuration tab -> Performance node -> Client Control tab 
** Set the Size limit and save.
* Update the schema so Sun ONE Directory Server is aware of the special Scalix attributes.  There are two methods for updating the schema file.  You may use the Directory Server Console, or you may edit the schema files directly.
===== Editing the schema via the Directory Server Console (preferred method) =====
* Login to the System Server Console and double-click the Directory Server for your host.
* Select the Configuration tab -> Schema node -> Attributes tab -> Create button
* Create the attributes according to the following table: 
{|border="1" align="center"
! Attribue Name
! OID
! Separate 
! Description
! Syntax
! Multi-valued
|-
| scalixScalixObject
| 1.1.10
| 
| boolean TRUE or FALSE for creating scalix mailbox/PDL object.  If this is set to FALSE and the object is matched by the omldapsync filter, a Contact entry/Internet user is created. If set to true, a  mailbox is setup. For Group/PDL objects, this must always be set to true
| Boolean
| no
|-
| scalixMailnode
| 1.1.11
| ,
| Comma-separated org units for object.s mailnode. This is the Mailnode name as defined when the Scalix server was setup. In Multi-server environments, this is used to select on which server the object is to be created.
| DirectoryString
| no
|-
| scalixAdministrator
| 1.1.12
| 
| Boolean TRUE or FALSE for admin capability. If set to TRUE, the user created will have full Scalix admin capabilites.
| Boolean
| no
|-
| scalixMailboxAdministrator
| 1.1.13
| 
| Boolean TRUE or FALSE for Mailbox Admin capability. A user with this flag set to TRUE can access ANY mailbox on a server through mboxadmin signon. This is usually only used for migration tools and typically not exposed through LDAP.
| Boolean
| no
|-
| scalixServerLanguage
| 1.1.14
| 
| Message catalog language for client. This is one of the Scalix-sup
ported languages found in /var/opt/scalix/nls/om_langs
| DirectoryString
| no
|-
| scalixEmailAddress
| 1.1.15
| 
| List of SMTP addresses of user. This is a multi-valued attribute. The order is important as the first of these values is used as the outgoing from address of the user.
| DirectoryString
| yes
|-
| scalixLimitMailboxSize
| 1.1.16
| 
| mailbox size limit for the user in MB
| Integer
| no
|-
| scalixLimitOutboundMail
| 1.1.17
| 
| As Sanction on Mailbox quota overuse, stop user from sending mail. Set to TRUE or FALSE
| Boolean
| no
|-
| scalixLimitInboundMail
| 1.1.18
| 
| As Sanction on Mailbox quota overuse, stop user from receiving mail.  Set to TRUE or FALSE
| Boolean
| no
|-
| scalixLimitNotifyUser
| 1.1.19
| 
| As Sanction on Mailbox quota overuse, notify the User by eMail.
Set to TRUE or FALSE
| Boolean
| no
|-
| scalixHideUserEntry
| 1.1.20
| 
| Hide User Entry from Addressbook. Set to TRUE or FALSE
| Boolean
| no
|-
| scalixMailboxClass
| 1.1.21
| 
| Class of User Mailbox FULL or LIMITED. This maps to Premium or Standard users as defined by Scalix User licensing policy
| DirectoryString
| no
|}
* Select the Object Classes tab and create the Object Classes according to the following table
{|border="1" align="center"
! Name
! Parent
! OID
! Required
! Allowed
|-
| scalixUserClass
| top
| 1.2.10
| scalixMailnode
scalixScalixObject
| scalixAdministrator
scalixEmailAddress
scalixHideUserEntry
scalixLimitInboundMail
scalixLimitMailboxSize
scalixLimitNotifyUser
scalixLimitOutboundMail
scalixMailboxAdministrator
scalixMailboxClass
scalixServerLanguage
|-
| scalixGroupClass
| top
| 1.2.11
| scalixMailnode
scalixScalixObject
| displayname
scalixEmailAddress
scalixHideUserEntry
|}
*Immediately after making the above changes, stop and restart the Directory Server.
 # /usr/sbin/directoryserver restart 

NOTE:  If you choose to use the Directory Server Console to define the Scalix attributes, you must restart the server immediatley after making your changes.  Restarting the server saves your modifications to the 99user.ldif file permanently and prevents other modifications made from the command line or the console from overwriting your changes.
===== Editing the Schema File Directly =====
The Sun ONE Directory Server schema files are typically located in ''ServerRoot/slapd-serverID/config/schema''.  
* Edit the ''90Scalix.ldif'' file in the appendix of this document, replacing fubar with your host name and mydomain and net with values appropriate to your own domain.  You  must also update the userdn and groupdn values.   
* Stop the Sun ONE Directory Server.
* Copy the 90Scalix.ldif to your Sun ONE Directory Server's schema directory.  
* Ensure that the file is world readable.
* Restart the Sun ONE Directory Server.
 # /usr/sbin/directoryserver restart 

NOTE: If you replicate your schema amongst multiple servers,  the replicated schemas will store the definitions from ''90Scalix.ldif'' in their ''99user.ldif'' file.

=== Active Directory ===
The steps for setting up Active Directory for synchronization with Scalix are documented in the Scalix Setup and Configuration Guide, in the chapter entitled "Integrating with Active Directory".

Basically the steps are as follows:
*Installing the Schema Extensions
*Installing the GUI Extensions
*Setting Up Synchronization Agreements

NOTE: There are a couple of errors in the section that describes how to set up the synchronization agreement; bugs have been logged.  The errors are described below in " Create omldapsync Agreement" under the type 11 agreement.

=== Create omldapsync Agreement ===
The  man page for omldapsync is very good; refer to it for more complete information.

omldapsync agreements can be of several different types, depending on whether you want to synchronize with an Exchange 5.5 directory, Sun ONE Directory Server,  Active Directory, OpenLDAP, etc.  The commonly used types are 
*11 - Import from Acitve Directory to Scalix
*13 - Import from OpenLDAP or Sun ONE Directory Server to Scalix
*21 - Import/Export address information between Exchange 5.5 and Scalix
These types are discussed in more detail below.  

The import-only agreements are used for managing all users from a central (LDAP) directory.  The import/export agreement is used to keep address books synchronized between disparate systems.

It is advisable to name your agreements according to what type of agreement it is and the LDAP host with which it is associated.  This makes it easy to tell at a glance what the agreement is intended to do.
==== The type 11 Agreement ====
This is documented in the [[Howtos/AD_Integration#Building_the_omldapsync_Agreement|AD Integration HowTo]].

==== The Type 13 Agreement ====


Assuming we are going to synchronize with a host named fubar.mydomain.net,  we would create our agreement as follows.  On the Scalix server:

 omldapsync -c 13fubar
 INPUT: Select sync agreement type to create (21): 13
 INPUT: Edit config file now y/n (n): y
 INPUT: Use vi to edit y/n (n): y

Update the following with values appropriate to your environment; values given are for illustration only.  The purpose of these fields is explained in the configuration file you are editing.

 JAVA_HOME=/usr/java/jre1.5.0_13
 EX_HOST=fubar.mydomain.net
 EX_LOGON=cn=admin,dc=mydomain,dc=net (for synchronizing with OpenLDAP servers)
 EX_LOGON=cn=Directory Manager (for synchronizing with Sun ONE Directory Servers)
 EX_PASS=secret
 IM_HOST=sxlab.mydomain.net
 IM_CAA_URL=<nowiki>http://sxlab.mydomain.net/caa/</nowiki>
 IM_CAA_NAME=sxadmin
 IM_CAA_PASS=sxpass
 EX_ATTR (for synchronizing with Sun ONE Directory Servers only, change entryUUID to nsUniqueId)
 EX_BASE1=cn=users,dc=mydomain,dc=net
 EX_GUID=entryUUID (for synchronizing with OpenLDAP servers)
 EX_GUID=nsUniqueId (for synchronizing with Sun ONE Directory Servers)

You may also want to modify the following values:
 IM_DELETE_MAILBOX

For synchronizing with Sun ONE Directory Servers only, change the following line 
 from
 entryUUID|GLOBAL-UNIQUE-ID|*|*
 to
 nsUniqueId|GLOBAL-UNIQUE-ID|*|*

 INPUT: Compare old config to new y/n (n):  n
 INPUT: Replace old config with new y/n (?):  y
 INPUT: Attempt to test data extraction now y/n (n):  n

==== The type 21 agreement ====
To be written - feel free to contribute!

=== Synchronize the Directories ===
You can synchronize in interactive mode or with a single command.  The interactive mode is friendlier and easier to understand ; the single command is useful for scheduling synchronization from cron.  You must be root to run omldapsync. 

Interactively:
 # omldapsync -i 13fubar
 2008-02-07 09:16:17 INFO: command line is /opt/scalix/bin/omldapsync -i 13fubar
 2008-02-07 09:16:18 STATUS: Interactive for 13fubar started ########
 Common tasks menu for syncid 13fubar
 0. Display this menu
 1. Configure the LDAP dir sync settings
 2. Force a complete (re)load of the directory
 3. Update the directory after some changes
 4. Accept previous error and update directory
 5. Skip previous error and update directory
 6. Update the directory and prompt for error
 7. Modify all sync records from the directory
 8. Delete all sync records in the directory
 d. Toggle debug mode from current setting <0>
 n. Toggle test mode from current setting <>
 q. Quit
 INPUT: Please enter an option (0): 3        

Single command:<br/>
There are command line  equivalents for the above; see the man page for more detailed information on these and other command line options.  To update the directory after some changes (option 3 above), you would run
 $ omldapsync -u 13fubar