Syncphony Installation instructions

From Syncphony (inactive) Wiki
Jump to: navigation, search

Deutsch Englisch

Contents

Introduction

The installation instructions have been written in such a way that a user can work through them step by step. It is assumed that the Funambol and JBoss server are installed in the /opt/ directory, and that all components will be installed to the same computer. If you use another installation directory, change the path to the data accordingly. The installation package contains the following data:


Name Description
Installation-instructions.odt This document
Kolab-webadmin-extension-tarent-1.0.tar.gz Extension to the front-end of Kolab. Enables the selection of folders, calendars, etc. that should be synchronized.
kolab-ws-<version>.jar Web service to access the Kolab server
kolab-ws-connector-<version>.s4j Funambol connector that accesses the Web service
kolabws-ds.xml Configuration of database connection to the Web service
kolab-ws.properties Configuration of the Web service
login-config.xml Configuration of Web service authentication
mail-1.4.2-patched-tarent.jar IMAP library of the Web service
mysql-connector-java-5.0.8-bin.jar Database driver for the Web service
schema-MySQL.sql Database schema of the Web service


Installation requirements

Kolab Server

You must have Kolab Server (version 2.2.2) already installed on the system. The LDAP server contained in this version will be used for authentication and authorization of users for the Funambol server and the Web service. The username here corresponds to the e-mail address from the LDAP attribute mail of a user.

A group must also be assigned. The name of the LDAP group object and the DN (Distinguished Name) may be chosen by the user. To create a group object, it is recommended to use the class "groupOfNames" or "groupOfUniqueNames". The classes provide the member and uniqueMember attributes, with which a Syncphony user is authorized for synchronization. For an attribute to be valid, a user's complete DN must be entered.

Beispielgruppe.png


Screenshot of an example group configuration for user authorization in Syncphony.

In a later step of the instructions, it will be described how the software components Kolab Web service and Funambol Connector from Syncphony are set up, with which authentication and authorization for a group object on the LDAP server can be carried out. The files that must be used for this are called login-config.xml, ejb-jar.xml (Kolab Web service) and LDAPUserProvisioningOfficer.xml (Funambol Connector), and will be described later in the installation instructions.


Installing Java Development Kit

Make sure that Sun Java Development Kit (version 1.6) is installed, and that the JAVA_HOME variable is set accordingly. The Funambol and JBoss server (which will be mentioned again and used later in the instructions) must be started while using JDK version 1.6, in order for Syncphony to run.

Additional components

  • MySQl 5.0
  • Jboss Application Server (Version jboss-5.0.1.GA-jdk6)
  • JDBC driver (must be located in the directory /opt/jboss-5.0.1.GA/common/lib/)
  • Funambol-Server (Version 8.0.0)

Security advice for components

To run Syncphony, the JBoss Application Server (version jboss-5.0.1.GA-jdk6) requires the JBoss Web service Framework (JBossWS), which is included in most installation packages. However, there are important differences between versions of the Framework. It should be noted that JBossWS is not used in version jbossws-native-3.1.2.GA. Otherwise it is possible that passwords from the JBoss Application Server will be logged in plain text.


Jbossws.png

Screenshot of the runtime information of an installed version of JBoss Web service Framework. This information can be reached with the following link and an Internet browser: http://localhost:9080/jbossws. In order to view runtime information, the JBoss-Server must be started with the command ".run.sh -b 0.0.0.0".

Security notice: The server must not be started in active mode with the aforementioned command, but instead with ./run.sh, otherwise the configuration settings will be openly viewable.

Extension to Kolab Webadmin

In order to designate which folder should be synchronized, an extension to the Kolab user interface is required. This extension is integrated as the user kolab in the directory / in the following steps:

1. Extract the archive kolab-webadmin-extension-tarent-1.0.tar.gz

2. Open the file /kolab/etc/kolab/templates/imapd.annotation_definitions.template with a text editor and add the following line: /vendor/tarent/syncpref,mailbox,string,backend,value.shared value.priv,a

3. Run the command kolabconf in the directory /kolab/sbin

Installing Kolab Web service

Setting up MySQL database

This section will explain how to install the required database through the terminal. To install the database, first log in to MySQL with the following command:

mysql -u user --password=password 

Here, replace the word user with the name of the user who has access to the database. The word password after the equals sign must also be replaced with the corresponding password. Next, enter the following command to create the database:

create database kolabws;

At this point, select the database into which the database schema should be imported. The database can be selected with the following command:

use kolabws;

Into this database, import the SQL script named schema-MySQL.sql from the kolab-sync-<version> package, using the following command:

source ~/schema-MySQL.sql

Here, replace the tilde (~) with the file path in which the file schema-MySQL.sql is located. Next, use the following command to log out of MySQL:

quit

Customizing JBoss ports

If both the Funambol and JBoss servers will be operated on the same machine, the ports of JBoss server must be customized. To do so, in the file /opt/jboss-5.0.1.GA/server/default/deploy/jbossweb.sar/server.xml replace the entry Port 8080 with Port 9080 , and replace the entry Port 8009 with Port 9009 .

Customizing IMAP library

The file /opt/jboss-5.0.1.GA/common/lib/mail.jar must be replaced with the file mail-1.4.2-patched-tarent.jar from the kolab-sync-<version> package.

Configuring database connection

If the given parameters for DB-host/name do not meet your specifications, the data in the file kolabws-ds.xml from the kolab-sync-<version> package must be modified as follows:

 <connection-url>
 	jdbc:mysql://localhost:3306/kolabws
 </connection-url>

In addition, the user who possesses access rights to the database must also be configured.

<user-name>user</user-name>

<password>password</password>

Afterward, copy the file to the directory /opt/jboss-5.0.1.GA/server/default/deploy/ .

Configuring access to LDAP server

The file login-config.xml from the kolab-sync-<version> package must be copied to the directory /opt/jboss-5.0.1.GA/server/default/conf/ and the following section must be edited:

 <module-option name="java.naming.provider.url">
 	ldap://sync.example.net:389/
 </module-option>
 <module-option name="bindDN">
 	cn=user,cn=internal,dc=sync,dc=example,dc=net
 </module-option>
 <module-option name="bindCredential">password</module-option>
 <module-option name="baseCtxDN">dc=sync,dc=example,dc=net
 </module-option>
 <module-option name="rolesCtxDN">
 	cn=groups,dc=sync,dc=example,dc=net
 </module-option>


The text in the XML tag with the attribute value java.naming.provider.url must contain the host address and the port of the LDAP server. The settings bindDN and bindCredential do not refer to those of the user to be authenticated, but rather those of a user who has the rights to search for another user who wants to be authenticated using the LDAP server. For the baseCtxDN option, you must define the LDAP branch in which employees should be searched for. In the rolesCtxDN option, you must define the branch in which the group object is found.

Configuring Web service

In the file kolab-ws.properties in the kolab-sync-<version> package, the settings for the e-mail server must now be configured:

Name Description
imap.host The hostname of the computer on which the Kolab IMAP server is installed
imap.port The port of the IMAP server. The standard setting is 143 (or 993 with SSL encryption).
imap.ssl If SSL encryption is used, the parameter value “true” must be entered. Otherwise the value “false” must be used.

Finally, this file is copied to the /opt/jboss-5.0.1.GA/server/default/conf/ directory. Afterward, the JBoss server should be restarted using the command /opt/jboss-5.0.1.GA/bin/run.sh

For authorization using the Web service, you must configure the name of the LDAP group object which lists all the members who are allowed to use the Web service. The name is pre-configured in the file ejb-jar.xml and is called synchronization_group. The file is located in the .jar archive kolab-ws-<version>.jar. In order to change the name of the LDAP group, the archive must first be unpacked. Then open the file ejb-jar.xml in the directory META-INF and replace all pre-defined group names (synchronization_group) with the desired new group names.

Afterward the folder can be packaged again as a .jar archive. Check to make sure that the structure of the new .jar archive matches that of the original (distributed) .jar archive. If while packaging the files, an empty top-level folder is accidentally created, the Web service will not work.

Installing Web service

The file kolab-ws-<version>.jar from the kolab-sync-<version> package should be copied into the /opt/jboss-5.0.1.GA/server/default/deploy/ directory. In order to check whether the previous steps were successfully completed, access the URL http://localhost:9080/jbossws/services in a browser, after the JBoss server has been restarted. The JBoss server must be restarted with the following command, in order to be able to check that the setup is correct:

./run.sh -b 0.0.0.0

In the browser window, the following two endpoints should now both be listed: jboss.ws:context=kolab-ws,endpoint=KolabServicePortTypeImpl jboss.ws:context=kolab-ws,endpoint=KolabServiceStatusPortTypeImpl Security advice: The server should be stopped, and then restarted with the following command:

./run.sh

If the server is not restarted, all the configuration settings of the JBoss server may be openly viewable.


Testing the Webservice

The correct installation of the webservice can be tested e.g. with soap UI. You need to import the WSDL file from the service by specifying the URL http://host:9080/kolab-ws/KolabServicePortTypeImpl?wsdl (Host needs to be changed). After creating the project you also need to include the following WS-Security header into SOAP requests (change username and password):

   <soapenv:Header>
      <wss:Security xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wss:UsernameToken>
            <wss:Username>user</wss:Username>
            <wss:Password>pass</wss:Password>
         </wss:UsernameToken>
      </wss:Security>
   </soapenv:Header>

Setting up Funambol Connector

Installing Funambol Connector

The file kolab-ws-connector-<version>.s4j from the kolab-sync-<version> package must be copied to the /opt/Funambol/ds-server/modules/ directory. Afterward, use a text editor to modify the file /opt/Funambol/ds-server/install.properties with the following value: modules-to-install= kolab-ws-connector-<version> Do not include the file extension .s4j in this line. With the command

/opt/Funambol/bin/funambol start

start the Funambol Server. Afterward, using the command

/opt/funabol/bin/install-modules

install and initialize the module. Installation progress will be shown in the terminal. For each module, it will be asked whether a database should be added. For the module kolab-ws-connector-<version> the question must be answered with Yes (Y, Enter), so that a database is added; for all other modules, enter No (N, Enter).

Configuring access to the LDAP server

The file /opt/Funambol/config/com/funambol/server/security/LDAPUserProvisioningOfficer.xml is used to configure access to the LDAP server for authentication and authorization to the Web service. The following entries can be configured: The hostname of the LDAP server.

<void property="ldapServer">
    <string>sync.example.net</string>
</void>


Under ldapPort the port of the LDAP Server is specified.

<void property="ldapPort">
    <int>389</int>
</void>


Use bindDn to enter the DN (distinguished name) of the user who is allowed to search using the LDAP server. Under bindCredential it is required to enter the corresponding password.

<void property="bindDn">
    <string>cn=user,cn=internal,dc=example,dc=net/string>
</void>
<void property="bindCredential">
    <string>password</string>
</void>


Under baseDn enter the DN in which to search for the user who should be authenticated using the LDAP server.

<void property="baseDn">
    <string>ou=People,dc=jboss,dc=example,dc=net</string>
</void>

Under roleDn insert the DN in which the synchronization group can be found.

<void property="roleDn">
    <string>ou=Roles,dc=jboss,dc=example,dc=net</string>  
</void>

Under ldapUrl the URL and the corresponding port of the LDAP server must be configured. The file LDAPUserProvisioningOfficer.xml must then be saved.

<void property="ldapUrl">
    <string>ldap://sync.example.net:389/</string>
</void>


Under userRole the predefined group synchronization_group should be replaced with the group to which a Syncphony user should be authorized.

<void property="userRole">
    <string>synchronization_group</string>
</void>


Under roleFilter, depending on the group object being used, the attribute must be defined, whose value contains the DN of the user who is allowed to use Syncphony. For example, if the group object "groupOfNames" is used, then the attribute is called "member". For the group object "groupOfUniqueNames" the attribute is called "uniqueMember".

<void property="roleFilter">
    <string>member</string>
</void>

Configuring Funambol Connector

To configure Funambol Connector, the Funambol Administration Tool is required. The Funambol Administration Tool can be found in the directory /opt/Funambol/admin/bin/ and can be started in the terminal with the following command:

./funamboladmin

In the dialog field to log in to the server, enter the hostname or the IP address of the Funambol Server. The default username is admin and the password is sa. In the directory tree under Modules/foundation/FunambolFoundationConnector/PIM Calendar SyncSource the entries cal, scal, event, task and stask must be deleted. In the same directory tree Modules/foundation/FunambolFoundationConnector/ under the entry PIM Contact SyncSource, the entries card and scard should also be deleted.

In addition, under Notes SyncSource (Modules/foundation/FunambolFoundationConnector/) the entries note and snote must also be deleted. Finally, navigate to the Modules/kolab-ws/kolab-ws-connector/Kolab Ws Calendar SyncSource/ directory. Here, by right-clicking on Kolab Ws Calendar SyncSource and choosing Add SyncSource, add five entries. The parameters “Kolab WS Host” and “Kolab WS Port” are the same in all entries, and correspond to the values that define how the Web service is accessible.

SyncSource.png

Screenshot of an example configuration for calendar synchronization.


Kolab WS Host:			localhost
Kolab WS Port:			9080

The other parameters must be entered as follows:

Source URI:				cal
Event:					yes
Task:					yes
Drop-Down Menü:			text/x-vcalendar

Source URI:				event
Event:					yes
Task:					no
Drop-Down Menü:			text/x-vcalendar

Source URI:				scal
Event:					yes
Task:					no
Drop-Down Menü:			text/x-vcalendar

Source URI:				stask
Event:					no
Task:					yes
Drop-Down Menü:			text/x-s4j-sift
	
Source URI:				task
Event:					no
Task:					yes
Drop-Down Menü:			text/x-vcalendar		

In the directory Modules/kolab-ws/kolab-ws-connector/Kolab Ws Contact SyncSource/ the following entries must be entered:

Source URI:				card
Drop-Down Menü:			text/x-vcard 

Source URI:				scard
Drop-Down Menü:			text/x-vcard

For the parameters “Kolab WS Host” and “Kolab WS Port” the values listed above must be saved.

The configuration of notes is adjusted under Modules/kolab-ws/kolab-ws-connector/Kolab Ws Note SyncSource/ . The following entries must be inserted there:

Source URI:				note
Drop-Down Menü:			text/plain

Source URI:				snote
Drop-Down Menü:			text/x-s4j-sifn

For the parameters “Kolab WS Host” and “Kolab WS Port” the values listed above must be saved.

Integrating LDAP server configuration

To allow authentication and authorization to the Web service to function, the file LDAPUserProvisioningOfficer.xml must be integrated into the Funambol Server, using the Funambol Administration Tool. For this, you must connect to the Funambol Server through the Funambol Administration Tool as described in the previous section. Under the menu item "Server Settings" and the sub-item Officer, the entry: com/funambol/server/security/UserProvisioningOfficer.xml in com/funambol/server/security/LDAPUserProvisioningOfficer.xml should be changed and saved using the Save button. After the entry LDAPUserProvisioningOfficer.xml there should be no spaces. Finally, the Funambol-Server must be restarted so that the file LDAPUserProvisioningOfficer.xml can be used.

Fun admin ldap conf.png

Screenshot of the integration of the file LDAPUserProvisioningOfficer.xml using the Funambol Administration Tool. This file controls authentication and authorization to Syncphony.

Setting up a mobile device

To be able to use a mobile device for synchronization, a SyncML client must be present on the device. Many mobile devices have a SyncML client pre-installed. If a SyncML client is not present, it must be installed. Some clients (so-called Funambol plugins) can be downloaded from the Funambol website via the following link: https://www.forge.funambol.org/download/ With the following link you will find documentation for all the different available clients: https://www.forge.funambol.org/download/documentation.html After the installation, the synchronization functions will be integrated in the mobile device. Before these functions can be used, you must enter the URL of the Funambol Server, an LDAP username (e-mail address of the user) and the corresponding password. The server URL is:

http://host:8080/funambol/ds

The hostname of the Funambol Server must correspond to what you enter in the URL. The default port setting for the Funambol Server is 8080. Depending on the SyncML client, it may be necessary to assign a database to the PIM objects (contacts, calendar, tasks and notes). The databases for the PIM objects are named as follows:

Contacts: card
Calendar: cal
Tasks: task
Notes: note

Running software update

This section describes how to run a software update to the system, when a previous installation has already been run on the system, as described in sections 2 through 5.

Updating Funambol Connector

The Web service can be updated on a running JBoss server. However, it may be useful to monitor the server log under /opt/jboss-5.0.1.GA/server/default/log/server.log during the process, in order to notice any potential errors that may occur. If errors do occur, the server may need to be restarted. To update the Web service, the old Web service with the name kolab-ws-<old-version>.jar in the directory /opt/jboss-5.0.1.GA/server/default/deploy/ must first be deleted. Afterward a new file kolab-ws-<version>.jar must be copied into this directory.

Funambol Connector aktualisieren

The Funambol Connector can be updated on a running Funambol Server. For security reasons, a backup of the file /opt/Funambol/config/com/funambol/server/security/LDAPUserProvisioningOfficer.xml should first be made. This configuration file will be overwritten during installation, and must be replaced by the backup version after installation. For this reason it is advised to temporarily rename the file (for example, LDAPUserProvisioningOfficer.xml.backup).

The installation runs as described above. In the file /opt/Funambol/ds-server/install.properties it is only necessary to update the system version. At the end, the backup configuration file must be put back into the same directory. The name of the file must be LDAPUserProvisioningOfficer.xml as before. The file with the same name, which was created during the installation, can be overwritten by the backup configuration file.