Table of contents:

* 1 Introduction
* 2 Installing and configuring Funambol ds-server
o 2.1 Installing Funambol ds-server
o 2.2 Replacing Hsqldb with Postgresql
o 2.3 Initializing the Funambol database and installing modules
o 2.4 Conflict resolution
* 3 Administering the Funambol ds-server
o 3.1 Starting the Funambol admin tool
o 3.2 Principals and principal autoprovisioning
o 3.3 Setting the timezone for the phones
o 3.4 Configuring the Funambol GroupDAV connector
* 4 Configuring the Nokia S60 phone
* 5 Securing Funambol with SSL
o 5.1 Enabling SSL support in Tomcat
o 5.2 SSL-support in Nokia S60-series phones
* 6 Working with the code
o 6.1 Funambol ds-server
o 6.2 Funambol synclets
o 6.3 Funambol GroupDAV connector
* 7 Debugging
o 7.1 Log files
o 7.2 Debugging event information corruption
o 7.3 Problems related to server's hostname/DNS name
* 8 Known bugs
o 8.1 Severe SSL support bug in Funambol startup script
o 8.2 Faulty email addresses sent by Zidestore
* 9 Links


1. Introduction

This guide is a compilation of information about synchronizing events between OpenGroupware.org server and Nokia S60 phones with Funambol data synchronization server and Funambol GroupDAV connector. The software versions I used were

* CentOS5 (Funambol) and CentOS4 (OpenGroupware.org)
* OpenGroupware.org 1.1.7 (Zidestore 1.5)
* Funambol GroupDAV connector 2.1
* Funambol data synchronization server bundle 6.5.14

On a basic level building a synchronization server for Nokia <-> OGo synchronization consists of several steps:

1. Installing Funambol
2. Configuring Funambol (adding SSL support, changing the database backend used)
3. Installing the Funambol GroupDAV connector (a bridge between Funambol and OGo)
4. Configuring the Funambol GroupDAV connector (adding synchronization targets)
5. Creating a new synchronization profile for the Nokia S60 phone
6. Uploading the Funambol server's SSL certificate to Nokia phone (if using SSL AND using an old Nokia S60 phone)
7. Creating redirection and packet filtering rules to allow connections to Funambol server (if it's inside a firewall)

After these steps you probably can synchronize most events between OGo and Nokia just fine. You will need to do some extra tricks to get allday events and other special events to work both ways. This is caused two major factors:

* Differences in interpretation of the iCalendar RFC
* Differences in the internal data representation of the calendaring programs

For example Nokia S60 calendaring program mimics MS Outlook's approach to iCalendars very closely to maintain compatibility with it. As an another example OpenGroupware.org and Nokia S60 calendar have different, incompatible recurring event and alarm implementations. This means that while most basic events synchronize just fine, problems start once you try to do something fancy, like get allday events synced correctly both ways back and forth.

Because synchronization between OGo and Nokia S60 phones is hardly plug-and-play, I've included a couple of chapters dedicated to troubleshooting and fixing problems. I have also documented all the pitfalls I encountered so that hopefully others can avoid them.


2. Installing and configuring Funambol ds-server


2.1. Installing Funambol ds-server

Installing the Funambol data synchronization server is pretty straightforward, given that you use the bundled version. You shouldn't need to do anything besides

# chmod 755 funambol-something.bin
# ./funambol-something.bin

For the sake of this guide I assume that you install Funambol to /opt/Funambol as the root user.


2.2. Replacing Hsqldb with Postgresql

If you wish to use postgresql instead of hsqldb, you need to install the PostgresSQL server first. In addition you will need the postgresql jdbc connector. In CentOS it's postgresql-jdbc. When postgresql is installed, you need to start it, as the first startup creates the configuration directory (/var/lib/pgsql/data) and the necessary configuration files. Next we can modify /var/lib/pgsql/data/pg_hba.conf to suit our needs:

# Database administrative login by UNIX sockets
local all postgres ident sameuser

# TYPE DATABASE USER CIDR-ADDRESS METHOD
# "local" is for Unix domain socket connections only
local all all ident sameuser

# IPv4 local connections:
# We don't want to use md5 passwords for testing and we trust anything coming from localhost.
# Funambol uses TCP/IP for communication so trusting Unix domain sockets is not enough.
#host all all 127.0.0.1/32 md5
host all all 127.0.0.1/32 trust

# IPv6 local connections:
host all all ::1/128 md5

If you don't feel lucky, edit postgresql's main configuration file (postgresql.conf) and increase the logging levels. Next restart postgresql with /etc/init.d/postgresql restart. Then from a terminal do

# sudo -s
# su - postgres
# createuser --password funambol
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) n
Password:
CREATE USER
# createdb -O funambol funambol

You can verify that all went ok by doing

# psql -h localhost
Welcome to psql 8.1.8, the PostgreSQL interactive terminal.

Type: \copyright for distribution terms
\h for help with SQL commands
\? for help with psql commands
\g or terminate with semicolon to execute query
\q to quit

postgres=# \l
List of databases
Name | Owner | Encoding
-----------+----------+-----------
funambol | funambol | SQL_ASCII
postgres | postgres | SQL_ASCII
template0 | postgres | SQL_ASCII
template1 | postgres | SQL_ASCII
(4 rows)

postgres=# \q

Now that we have a user with a password, we can move on to configuring Funambol ds-server.

# nano $FUNAMBOL_HOME/ds-server/install.properties

Change the DBMS name to postgresql:

#
# The DBMS name. One of:
# - ansisql99
# - db2
# - hypersonic
# - mysql
# - oracle
# - postgresql
# - sqlserver
# - sybase
#
#dbms=hypersonic
dbms=postgresql

Also comment out all references to hsqldb:

#jdbc.classpath=../tools/hypersonic/lib/hsqldb.jar
#jdbc.driver=org.hsqldb.jdbcDriver
#jdbc.url=jdbc:hsqldb:hsql://localhost/funambol
#jdbc.user=sa
#jdbc.password=

Last and not definitely least configure the postgresql connector:

# PostgreSQL
# ==========
#
#jdbc.classpath=<somepath>/postgresql.jar
#jdbc.driver=org.postgresql.Driver
#jdbc.url=jdbc:postgresql://<hostname>/funambol
#jdbc.user=funambol
#jdbc.password=funambol

jdbc.classpath=/usr/share/java/postgresql.jar
jdbc.driver=org.postgresql.Driver
jdbc.url=jdbc:postgresql://localhost/funambol
jdbc.user=funambol
jdbc.password=funambol

Make sure that you use the same password you gave when you did createuser --password funambol. Next proceed with initializing the Funambol database and installing the modules. If you're unsure where the postgresql.jar is located, you can do the following:

rpm -q --filesbypkg postgresql-jdbc|less


2.3. Initializing the Funambol database and installing modules

The file $FUNAMBOL_HOME/ds-server/install.properties contains all the information Funambol needs to install itself on Tomcat or another application server. In this phase we install the Funambol GroupDAV connector modules (groupdav-2.1.s4j): First copy the groupdav-2.1.s4j to $FUNAMBOL_HOME/ds-server/modules. Next edit the file $FUNAMBOL_HOME/ds-server/install.properties:

modules-to-install=foundation-6.5.12,funambol-webdemo-client-6.5.9,funambol-phones-support-6.5.6,funambol-email-6.5.12,groupdav-2.1

Now you can install the modules. If you're not using the built-in hsqldb database you need to initialize Funambol's database before installing the modules. This is done from the directory $FUNAMBOL_HOME/ds-server by issuing

# cd /opt/Funambol/ds-server
# bin/install.sh

You can safely ignore any notices about missing tables. The database structure is now in place and modules have been installed. If the database structure has been created previously, you should use

# cd /opt/Funambol/ds-server
# bin/install-modules.sh

instead. It install just the modules and does not mess with the Funambol's internal database. After this you should be able to login to Funambol with the admin tool and see all the modules you installed.

Note: installing the funambol-phones-support removes all customized synclets. You can safely disable it's installation after it has been installed once. This way synclets are not overwritten.


2.4. Conflict resolution

Conflict resolution is used when both the SyncML client and SyncML server contain modified version of the same item (e.g. VCALENDAR entry). This means that we have to decide whether we give preference to client-side changes or to server-side changes. With Funambol (or SyncML in general?) it's not possible to merge the conflicting items interactively like with some proprietary desktop sync solutions.

Conflict resolution policy is defined in $FUNAMBOL_HOME/ds-server/config/com/funambol/server/engine/Strategy.xml:

<?xml version="1.0" encoding="UTF-8"?>
<java version="1.4.0" class="java.beans.XMLDecoder">
<object class="com.funambol.server.engine.Sync4jStrategy">
<void property="defaultConflictResolution">

<!-- ================================== -->
<!-- 0: CONFLICT_RESOLUTION_SERVER_WINS -->
<!-- 1: CONFLICT_RESOLUTION_CLIENT_WINS -->
<!-- 2: CONFLICT_RESOLUTION_MERGE_DATA -->
<!-- ================================== -->

<int>0</int>
</void>
</object>
</java>

As you can see, the file explains itself. You can also use the conflict resolution policy to avoid accidental disasters when it is necessary to do testing on production devices.


3. Administering the Funambol ds-server


3.1. Starting the Funambol admin tool

Navigate to $FUNAMBOL_HOME/admin/bin and then give the command ./funamboladmin. That will not work if you don't have write access to the Funambol directory. In that case change the permissions or try it again as the root user. Note that you can't administer Funambol servers through SSL - you need to connect to the insecure port (8080).


3.2. Principals and principal autoprovisioning

Principals are what Funambol to tie a user to a device. Creating principals by hand is not necessary anymore with Funambol 6.x, as all is taken care of during the first synchronization session. This is called principal autoprovisioning. Problems will occur if the user does a typo while entering his/her password or the password changes at a later date. This is because the Funambol connectors (e.g. GroupDAV connector use the Funambol password as the password for the services they connect to (e.g. OGo).


3.3. Setting the timezone for the phones

To get Nokia allday events (s.c. memos) and anniversaries working you need to define the phones timezone in Funambol admin tool. This is necessary because Nokia phones don't send timezone information with allday events (memos) or anniversaries. To change the device's timezone, navigate to Devices and select the correct phone and set the timezone. Make sure that you dont't set Funambol to convert event times to the specified timezone - otherwise times in normal events break. Also make sure that you set OGo / multi timezone all day event handling in GroupDAV connector settings to yes.


3.4. Configuring the Funambol GroupDAV connector

By now you should have installed the Funambol GroupDAV connector module (groupdav-2.1.s4j) during the Funambol module installation phase. This is not enough, however, because we need to create a new synchronization target (connector instance) that we synchronize Nokia with.

As S60 phones are able to keep in sync with only one calendar at time, it's extremely important to get the right calendar from Zidestore. The most important and useful calendars are probably the following:

* User's private events: /zidestore/dav/%USER%/Calendar
o this contains events that are marked private in OGo
* User's all events: /zidestore/dav/%USER%/Overview
o This _should_ contain all events that the attends. This is what usually shows up in the OGo web interface.

For more information on Zidestore calendars, take a look at http://www.opengroupware.org/en/users/docs/snippets/ZideStore/ZideStore-URLs.html. Note that Nokia S60 phones have no concept of attendee or user, whereas OGo does. This means that if you choose a calendar that contains other people's events, it can be difficult for the user to tell which event he or she is supposed to attend to - by using the phone's calendar, that is.

Once you've chosen your calendar, you can configure the GroupDAV connector via the Funambol admin tool. Navigate Modules -> GroupDAV -> BionicMessageGroupDAVConnector and create a new GroupDAV Calendar. The correct settings are something like this:

* SyncML ID: overview
* GroupDAV server: http://ogo.yourserver.com:80/
* Client data type: text/x-vcalendar
* Store location: /opt/Funambol/stores/groupdav-cal
* Calendar sources
o Source name: default
o Server path: /zidestore/dav/%USER%/Overview
* Use single log files: no
* OGo / multi timezone all day event handling: yes

With these settings you get the Overview calendar to the phone. This is probably what most people want.


4. Configuring the Nokia S60 phone

Once you've configured the Funambol GroupDAV connector, you can create a new synchronization profile in your Nokia phone. If you're using a very modern S60 phone, navigate to

* Tools -> Sync

If the phone is not really modern, go to

* Connect. -> Sync

instead. Then create a new synchronization profile with the following values:

* Sync profile name: OpenGroupware.org
* Applications
o Contacts
+ Include in sync: no
o Calendar
+ Include in sync: Yes
+ Remote database: overview (the same as the GroupDAV connector instance)
+ Synchronisation type: normal
o Notes
+ Include in sync: no
o Text message
+ Include in sync: no
o Bookmarks
+ Include in sync: no
* Connection settings:
o Server version: 1.2
o Server ID: funambol
o Data bearer: Internet
o Access point: Always ask (or your own choice)
o Host address: https://your.funambol.server/funambol/ds
o Port: 443
o User name: OGo username
o Password: OGo password
o Allow sync requests: Yes
o Accept all sync reqs.: Yes
o Network authentic.: No


5. Securing Funambol with SSL

5.1. Enabling SSL support in Tomcat

Securing traffic to the Funambol data synchronization server is a must unless you run Funambol entirely inside a secure (W)LAN or something. Otherwise all data, username and passwords are sent through the Internet in plain text, which is dangerous.

While it is possible to use trusted certificates (like those you can buy from Verisign or Thawte) with Funambol, it's much easier to create your own self-signed certificate at least for testing purposes. That's what we cover here. To create a new self-signed certificate, enter Funambol's built-in JRE's bin directory ($FUNAMBOL_HOME/toosl/jre-1.5.0/jre/bin). Then create a new Java keystore with the following command:

sync:/opt/Funambol/tools/jre-1.5.0/jre/bin# ./keytool -genkey -alias tomcat -keyalg RSA -storetype JKS -validity 730 -keystore /root/funambol65.jks
Enter keystore password: mypassword
What is your first and last name?
[Unknown]: my.server.address.here
What is the name of your organizational unit?
[Unknown]: Your OU
What is the name of your organization?
[Unknown]: Your organization
What is the name of your City or Locality?
[Unknown]: Your city
What is the name of your State or Province?
[Unknown]: Your state
What is the two-letter country code for this unit?
[Unknown]: Your countrycode
Is CN=t, OU=t, O=t, L=t, ST=t, C=fi correct?
[no]: yes

Enter key password for <tomcat>
(RETURN if same as keystore password): mypassword

Next edit the $FUNAMBOL_HOME/tools/tomcat/conf/server.xml file like this:

<Connector port="443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="/root/funambol65.jks"
keystorePass="mypassword"/>

This should work, but note that Tomcat is really picky about the connector definition format and there's a lot of misinformation floating around. If you don't specificy the keystoreFile Tomcat assumes it's in $HOME/.keystore of the user Funambol runs as (for example /root/.keystore).

NOTE: There's a severe bug in Funambol startup scripts that makes using self-signed certificates almost impossible. See the Known bugs section below for more information.


5.2. SSL-support in Nokia S60-series phones

All Symbian S60 phones that are less than a couple of years old (2004->) should support SyncML over SSL. The implementations are suboptimal, however. Even relatively modern (2007) S60 phones cat't handle untrusted certificates automatically. If we try to synchronize old Nokia S60 phone with a Funambol server that's using SSL and a self-signed certificate the synchronization just fails with "Server not responding" message. On the other hand, if we go the same server's Tomcat homepage with the built-in browser, it complains about the certificate but lets us proceed. Only in very recent Nokia S60 models (e.g. Nokia E51) the synchronization program is smart enough to ask the user whether he or she wants to trust the untrusted certificate.

If you have an older Nokia S60 phone you have to import Tomcat's SSL certificate to the Nokia. In addition the certificate name has to match the IP address (or hostname) of the Funambol/Tomcat server.

1 Enter the Tomcat startup screen with Mozilla Firefox, for example: firefox https://172.16.0.54
2 Accept the certificate
3 Download the "Certviewer plus" extension for Firefox and restart the browser
4 View Tomcat's certificate in "Certviewer plus" and save the certificate in DER format. This is the only format Nokia will accept.
5 Upload the DER certificate into some web server's path, for example /var/www/html/cert.der. Make sure you add the extension .der - we need that in the next step. You might also be able to open the certificate from an email instead.
6 By default Nokia's browser cannot comprehend what this .der file is. We need to tweak Apache's configuration so that it will tell what MIME type to associate with these .der files. This can probably be done in many ways, but I simply added a line AddType application/x-x509-ca-cert .der to /etc/httpd/conf/httpd.conf and reloaded Apache configuration with /etc/init.d/httpd reload. On Apache 1.x you need to add the mimetype to the file mime.types instead.

Navigating to the certificate's address should now trigger the certificate import wizard. If you failed to do the AddType (above), you will have to clear the browser's cache before retrying. Also note that some Nokia models have a bug which causes the selections made during the certificate import wizard to be disregarded. To check that the certificate was saved successfully and it's settings are correct, navigate to

Tools -> Settings -> Security -> Certif. management

and find the certificate you saved and do

Options -> Trust settings

and make sure that settings are like this:

* Internet: yes
* Online certif. check: no

If and when you need to update the certificate you should remove the old certificate before installing the new one. To do this, go to

Tools -> Settings -> Security -> Certif. management

and find the certificate you saved and remove it. Then follow the instructions for installing the new certificate as shown above.


6. Working with the code


6.1. Funambol ds-server

Funambol server does some modifications to the events itself. If this becomes a problem, the modifications can be reversed by either modifying the GroupDAV connector (Nokia -> OGo) or the output synclet (OGo -> Nokia. The output synclet is usually named NokiaS60out.bsh. If you really need to modify Funambol's core, refer to the links at the end of this document.


6.2. Funambol synclets

Synclets can be written to modify SyncML transactions in it's various phases, and also the data contained within the SyncML message. Synclets are written in Java beanshell and therefore require no compiling. Just modify a synclet and try syncing. If there's an error in synclet code, it's execution stops but the synchronization process is not otherwise affected.

So what can you do with synclets? For example you can fix invalid paths in SyncML URI's, modify the VCALENDAR entries contained within the SyncML message, etc. This is often useful because various vendors (Nokia, Microsoft, OGo) create invalid/incompatible VCALENDAR entries, which can in the worst case create exceptions during sync or other unwanted effects (such as event timeshifting) in the programs/devices they are synchronized to.

The synclets applied to a specific SyncML message are determined by two factors:

* The HTTP user agent Funambol is communicating with. For modern Nokia S60 phones this is usually Nokia SyncML HTTP Client. Note that Funambol goes through every synclet that the device's HTTP user agent matches. Therefore the SyncML message might get modified several times in a row. If possible, be as specific with the matching pattern or something unexpected might occur.

* Direction of the synchronization, either inbound or outbound. The Output pipeline is used when data is sent from Funambol to a device, for example from OGo to Nokia S60 phone. Input pipeline is used when data is coming into Funambol from outside (Nokia -> OGo). It is important to note that even though various connectors move information to/from Funambol, the connection between them and Funambol is outside Funambol's pipelines. For example when GroupDAV connector is pulling events from OGo Zidestore the data does not got through any synclets.

In Funambol 6.x the pipeline configuration is located in $FUNAMBOL_HOME/ds-server/config/com/funambol/server/engine/pipeline:

sync:/opt/Funambol/ds-server/config/com/funambol/server/engine/pipeline# ls
input output phones-support
sync:/opt/funambol-6.5-bundle-matthew/ds-server/config/com/funambol/server/engine/pipeline# ls input
001.0500.EnablePhoto.xml 100.3030.Nokia7200.xml 110.9000.Motorola.xml 120.1090.SonyEricssonP1I.xml
001.1000.SourceURIPrefix.xml 100.3030.NokiaS60.xml 110.9010.MotorolaHandango.xml 120.1100.SonyEricssonP990I.xml
100.1000.Nokia6101.xml 100.9000.Nokia.xml 110.9020.MotorolaEpoc.xml 120.2000.SonyEricssonEpoc.xml
100.1010.Nokia6111.xml 110.1000.MotorolaV3.xml 120.1000.SonyEricssonW8X.xml 120.9000.SonyEricsson.xml
100.1020.Nokia6131.xml 110.1020.MotorolaK1.xml 120.1010.SonyEricssonM600I.xml 130.1000.SiemensS55.xml
100.1050.Nokia7610.xml 110.1030.MotorolaV600.xml 120.1020.SonyEricssonZ52X.xml 130.1010.SiemensS5X.xml
100.2000.Nokia602X.xml 110.1035.MotorolaV600.xml 120.1030.SonyEricssonK800I.xml 130.1020.SiemensSK65.xml
100.2010.Nokia61X.xml 110.1040.MotorolaV3xx.xml 120.1040.SonyEricssonK608I.xml 130.1030.SiemensM55.xml
100.2020.Nokia623X.xml 110.1050.MotorolaPEBLU6.xml 120.1050.SonyEricssonK750I.xml 150.9000.Synthesis.xml
100.3000.Nokia6200.xml 110.1060.MotorolaV360.xml 120.1060.SonyEricssonV800.xml 160.1000.PanasonicX70.xml
100.3010.Nokia6610I.xml 110.1070.MotorolaV5XX.xml 120.1070.SonyEricssonT610.xml 170.1000.SyncEvolution.xml
100.3020.Nokia3220.xml 110.1080.MotorolaV8.xml 120.1080.SonyEricssonT68I.xml
sync:/opt/Funambol/ds-server/config/com/funambol/server/engine/pipeline# less input/100.3030.NokiaS60.xml

<?xml version="1.0" encoding="UTF-8"?>
<java version="1.5.0_08" class="java.beans.XMLDecoder">
<object class="com.funambol.foundation.synclet.BeanShellSynclet">
<void property="header">
<string>user-agent</string>
</void>
<void property="pattern">
<string>Nokia SyncML HTTP Client</string>
</void>
<void property="script">
<string>com/funambol/server/engine/pipeline/phones-support/bsh/NokiaS60in.bsh</string>
</void>
</object>
</java>

The actual synclets are located in $FUNAMBOL_HOME/ds-server/config/com/funambol/server/engine/pipeline/phones-support/bsh:

# ls
MotorolaEPOCXin.bsh Nokia6111in.bsh NokiaS60out.bsh SiemensSK65Xout.bsh SonyEricssonW8Xout.bsh
MotorolaEPOCXout.bsh Nokia6111out.bsh NokiaS60out.bsh.dist SonyEricssonEPOCXin.bsh SonyEricssonXin.bsh
MotorolaK1in.bsh Nokia6200in.bsh NokiaS60out.bsh.matthew SonyEricssonEPOCXout.bsh SonyEricssonXout.bsh
MotorolaPEBLU6in.bsh Nokia6200out.bsh NokiaS60out.bsh.rollbackdate SonyEricssonK608Iin.bsh SonyEricssonZ52Xin.bsh
MotorolaPEBLU6out.bsh Nokia6610Iin.bsh NokiaS60out.dist SonyEricssonK608Iout.bsh SonyEricssonZ52Xout.bsh
MotorolaV3xxin.bsh Nokia6610Iout.bsh NokiaXin.bsh SonyEricssonK750Iin.bsh SyncEvolutionin.bsh
MotorolaV3xxout.bsh Nokia7200in.bsh PanasonicX70in.bsh SonyEricssonK750Iout.bsh SyncEvolutionout.bsh
MotorolaV5XXin.bsh Nokia7610in.bsh PanasonicX70out.bsh SonyEricssonK800Iin.bsh SynthesisIn.bsh
MotorolaV600in.bsh Nokia7610out.bsh SiemensM55in.bsh SonyEricssonK800Iout.bsh SynthesisOut.bsh
MotorolaV8in.bsh Nokia9500out.bsh SiemensM55out.bsh SonyEricssonM600Iin.bsh commands
MotorolaV8out.bsh NokiaS40in.bsh SiemensS55Xin.bsh SonyEricssonM600Iout.bsh epoc
MotorolaXin.bsh NokiaS40out.bsh SiemensS5Xin.bsh SonyEricssonT610in.bsh iPodXout.bsh
MotorolaXout.bsh NokiaS60in.bsh SiemensS5Xout.bsh SonyEricssonV800in.bsh sonyericsson
Nokia3220out.bsh NokiaS60in.bsh.matthew SiemensSK65Xin.bsh SonyEricssonW8Xin.bsh

NOTE: Make sure that only one or few synclets modify the same parts of the message. This can be verified from Funambol ds-server's logs. Make sure that the device (e.g. phone model) is detected as early as possible (from the HTTP header, if possible). If you need to use same synclet for many devices, make sure there are checks in place to detected the model from device information (devInf). Most Funambol 6.5.12 synclets already have these checks in place.


6.3. Funambol GroupDAV connector

Current (2.1+) versions of the Funambol GroupDAV connector use the Maven (http://maven.apache.org) build system. This makes thing much easier if you need to modify the GroupDAV connector for any reason. You can get the links to latest GroupDAV connector versions and git sources from the connector's homepage at http://bionicmessage.net. Currently (23. May 2008) you can follow the procedure outline below:

First use git to obtain the sources:

# git clone git://repo.or.cz/funambol-groupdav-connector.git/
# git clone git://repo.or.cz/jgroupdav.git/

Now we have all the necessary things:

# ls
# funambol-groupdav-connector jgroupdav

When all sources have been downloaded we can try building the JGroupDAV libraries:

# cd jgroupdav
# mvn install

If that fails, try

# mvn -Dmaven.test.skip.exec=true install

instead. This command skips all tests and installs the jgroupdav-*.jar to $HOME/.m2/repository and makes it available to the actual Funambol GroupDAV connector build. Next you can proceed to building and installing funambol-groupdav-connector:

# cd funambol-groupdav-connector
# mvn install

Maven2 should take care of the dependencies automatically, but you might still encounter an error if the necessary Funambol modules are not available in $HOME/.m2/repository. In this case try rebuilding the jgroupdav (see above) and then try again. Once the funambol-groupdav-connector is has been built without errors, you can install the groupdav-2.1.s4j-file from the funambol-groupdav-connect/target directory to your Funambol-server's module directory ($FUNAMBOL_HOME/ds-server/modules) and reinstall the modules.

In case you build the connector and/or jgroupdav more than you might want to verify that old crap is removed before each build. You can do this with

# mvn clean

before running mvn install in jgroupdav or funambol-groupdav-connector directory. To verify that you really have the latest version take a look at the timestamp of the groupdav-2.1.s4j in the funambol-groupdav-connector/target directory.


7. Debugging


7.1. Log files

* Funambol data synchronization server's logs are in $FUNAMBOL_HOME/logs/ds-server/. Make sure to increase the logging level with the Funambol admin tool
* Tomcat logs are in $FUNAMBOL_HOME/tools/tomcat/logs/. They're useful when troubleshooting Funambol startup problems, especially when using SSL to secure transfers to Funambol/Tomcat.
* GroupDAV connector logs are by default in $FUNAMBOL_HOME/stores/groupdav-cal/.
* OpenGroupware.org logs are in /var/lib/opengroupware/ogo-*.log (in RedHat/CentOS). We're interested in ogo-zidestore-1.5-err.log and ogo-zidestore-1.5-out.log
* Nokia S60 synchronization logs are utterly useless.


7.2. Debugging event information corruption

It is quite common that synchronization causes problems with start and end times of some event types (mostly all-day or 24*n long events). This is not surprising given that Nokia and OGo interpret events differently and the events are at risk of being "fixed" at pretty much every point in the synchronization:

Flow of VCALENDARs from phone to OGo

In short: Nokia -> Funambol input pipeline (synclets) -> GroupDAV connector -> Zidestore

* Nokia sends the modified VEVENT to Funambol inside a SyncML message.
* The VCALENDAR enters the PipelineManager, which passes it to NokiaXin.bsh synclet.
* The VCALENDAR - and the VEVENT contained inside it - is modified by the synclet.
* After being modified in the input synclet the event enters GroupDAV connector.
* GroupDAV connector does it's own modifications to the VEVENT. This includes converting the event from Funambol-specific VEVENT Java object to ical4j Java object.
* GroupDAV connector sends the VEVENT to OGo Zidestore, which parses it and might do some modifications to it.
* Zidestore creates an OGo event based on the information in this Zidestore-parsed and modified VEVENT.

Flow of VCALENDARs from OGo to phone

In short: Zidestore -> GroupDAV connector -> Funambol output pipeline (synclets) -> Nokia

* GroupDAV connector requests OGo Zidestore to send recently modified VEVENTs to it.
* GroupDAV connector does some VCALENDAR parsing of it's own, including conversion of events from ical4j VEVENT objects to Funambol VEVENT objects.
* The VCALENDAR is modified by an output synclet (usually NokiaS60out.bsh).
* The VCALENDAR is sent to Nokia, which interprets it and adds it to it's calendar.

You can pinpoint the source of the problem by looking at Funambol's and GroupDAV connector's log files. Once the source of the problem is known, it's best to fix it as close to the endpoint (Nokia or OGo) as possible. That way the modified event doesn't get modified again before it reaches it's endpoint. For example, if an all-day event from OGo breaks when going to Nokia, it' best to fix it in the NokiaS60out.bsh synclet. Fixing it earlier might just cause it to be "refixed" before it reaches the phone.


7.3. Problems related to server's hostname/DNS name

If you're having problems starting Funambol, you might have a hostname problem. This is actually quite likely if you are deploying Funambol by just copying existing virtual machine images. The symptoms for this hostname problem are these:

* Funambol seems to start ok, but in reality only HSQLDB (port 9001) gets started.
* Starting the Funambol-bundled Tomcat with cd /opt/Funambol/tools/tomcat/bin works as advertized.

The reason for this problem can be found from Tomcat's logs after unsuccessful Funambol startup:

May 14, 2008 3:14:17 PM org.apache.catalina.connector.Connector pause
SEVERE: Protocol handler pause failed
java.net.UnknownHostException: server5.mycompany.com: server5.mycompany.com
at java.net.InetAddress.getLocalHost(Unknown Source)
at org.apache.jk.common.ChannelSocket.unLockSocket(ChannelSocket.java:484)

--- snip ---

May 14, 2008 3:14:18 PM org.apache.catalina.core.StandardService stop
INFO: Stopping service Catalina
May 14, 2008 3:14:18 PM org.apache.coyote.http11.Http11BaseProtocol destroy
INFO: Stopping Coyote HTTP/1.1 on http-8080
May 14, 2008 3:14:18 PM org.apache.catalina.core.AprLifecycleListener lifecycleEvent
INFO: Failed shutdown of Apache Portable Runtime
Error: Exception thrown by the agent : java.net.MalformedURLException: Local host name unknown: java.net.UnknownHostException: server.mycompany.com: server.mycompany.com

As you can see, the defined hostname (server.mycompany.com) is causing all the trouble. In RedHat/CentOS this issue can be fixed by editing the file /etc/sysconfig/network:

NETWORKING=yes
NETWORKING_IPV6=yes
# Replace old hostname with a valid one. Localhost is also a possibility.
HOSTNAME=my.servers.real.name

Next restart the server. The hostname should now be in line with DNS and the same problem should not occur.


8. Known bugs


8.1. Severe SSL support bug in Funambol startup script

This problem occured during upgrade from Funambol bundle v5 to v6.5. It has been reported as a bug to Funambol team (see http://forge.objectweb.org/tracker/?group_id=96):

[ #308424 ] Self-signed certificates in a Java Keystore file don't work with any other password than "changeit"

This issue has not been fixed yet (on 15th May 2008). The problem was so weird that it took over two days to debug it. Until the very end the problem seemed to lie in Tomcat. The real problem is, however, in Funambol's startup script, $FUNAMBOL_HOME/tools/bin/funambol.sh. The symptoms are these:

* If Tomcat is started with the Funambol startup script, Tomcat's SSL listener will consistently fail to come up if the Java keystore password and/or the certificate password are changed from the default ("changeit"). The log, catalina.out will tell "keystore was tampered with" or "could not retrieve key", depending on the JKS and Tomcat's configuration in server.xml.

* If Tomcat is started with Tomcat's own startup scripts, SSL listener will come up just fine with any given JKS/certificate password.

This problem is located in Funambol ds-server's startup script ($FUNAMBOL_HOME/ds-server/bin/start.sh):

*** start.sh.dist Sat Feb 2 11:16:00 2008
--- start.sh Sat Feb 2 11:11:23 2008
***************
*** 74,80 ****
JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Xmx512M"
JAVA_OPTS="$JAVA_OPTS -Dfunambol.ds.home=$FUNAMBOL_HOME"
JAVA_OPTS="$JAVA_OPTS -Djava.library.path=$FUNAMBOL_HOME/lib/$LIB_PATH"
! JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$FUNAMBOL_HOME/lib/security/cacerts"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=$JMX_PORT -Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false"

export JAVA_OPTS;
--- 74,81 ----
JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Xmx512M"
JAVA_OPTS="$JAVA_OPTS -Dfunambol.ds.home=$FUNAMBOL_HOME"
JAVA_OPTS="$JAVA_OPTS -Djava.library.path=$FUNAMBOL_HOME/lib/$LIB_PATH"
! # Commented out due to the strange SSL problem
! #JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=$FUNAMBOL_HOME/lib/security/cacerts"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=$JMX_PORT -Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false"

export JAVA_OPTS;

The javax.net.ssl.trustStore seems to cause problems with Tomcat certificates for some reason. It's not yet clear why this affects Tomcat's keystorePass in any way.

NOTE: the start.sh script gets overwritten if you reinitialize the database and modules with bin/install.sh. The change has to be applied again each time you do that.


8.2. Faulty email addresses sent by Zidestore

Zidestore will happily server invalid email addresses. This can happen in the following cases:

* An OGo group's email address is not defined. In this case Zidestore uses the group name as EMAIL in Zidestore. This rarely works an causes an exception while the VCALENDAR is parsed.
* An invalid email address has been defined for a user (e.g. äpärä.lapsi@myserver.com)


9. Links

* OpenGroupware.org homepage: http://www.opengroupware.org
* Funambol homepage: http://www.funambol.com
* Funambol community forge: https://www.forge.funambol.org/
* Funambol GroupDAV connector homepage: http://bionicmessage.net/
* Nokia discussion forums: http://discussion.forum.nokia.com