Views

From bionicmessage documentation wiki

1 Install and sync instructions
2 Advanced administration topics

Install and sync instructions

Introduction

The BionicMessage GroupWare Sync server is a custom distribution of the Funambol 6.5.14 Device Sync server intended for use with GroupWare servers that implement the GroupDAV standard. There are additions such as the Citadel email connector and a groupware authentication backend.

Installation

NOTE: As the install script mentions Funambol will come up on port 8080. You may already have something running on this port. If you do, shut it down for now. You can change the port Funambol is on after the install script is done

The setup process has changed from the previous bundles. The installation of the server is now done by a script launched automatically by the extractor binary. If you downloaded the 'BYO JRE' version, you will need to:

ln -s /opt/jdk1.5.0 java #symbolic link to existing jdk
./install.sh #Run installer

The install script will ask for the server you are using, the server and port its webserver is on. If you are running Citadel, you will also be asked for the server the Citadel is actually running on.

For the initial install you need to answer 'y' to the Funambol install script when it asks to create the databases.

After Funambol has installed itself, the install script will then bring up the server. Once the server is running post-configuration occurs. You will be asked if you wish to authenticate users against your groupware server, or stay with the default Funambol method of creating users in its database with any credentials they use.

During post configuration a set of sync sources are automatically set up, so if everything is done right, thats all you need to do to start syncing!

Configuring your device and syncing

You will need to configure your device's SyncML software with the following information:

SyncML Server	http://yourserver:8080/funambol/ds
Username	The same username you use to login to your Groupware
Password	The same password you use to login to your Groupware
Calendar URI	groupdav-cal-v (groupdav-cal-s for Funambol clients). Note: If you are using a Synthesis client disable filtering. If you are using a Symbian device where calendar's and task's are treated as one you need to use groupdav-s60-v.
Task URI (not for OpenGroupware)	groupdav-task-v (groupdav-task-s for Funambol clients)
Addressbook URI	groupdav-addr-v (groupdav-addr-s for Funambol clients)
Mail	mail (Using Funambol clients and Citadel only)

With this configuration you should be ready to sync all your data. Where possible, on first sync, do each data type separately incase one of them fails.

Advanced administration topics

Structure

Note the layout of the server bundle:

Funambol bundle structure	Subdirectory	Description
ds-server		Funambol DS-Server main directory
	modules	Drop any future GroupDAV connector updates (groupdav-2.0.s4j) into here
	config	Funambol configuration files
admin		Funambol administration tool
tomcat		Apache tomcat 5.5 application/web server
	conf	Tomcat configration. Modify server.xml to change http port
database		Funambol's configuration database.
java		Java runtime. (If you are running non-x86, you could drop your JRE here)
logs		Funambol's log files are within this directory
stores		The Funambol GroupDAV and Citadel mail connectors store information about each sync client here
postconfig		The postconfig tool - responsible for setting the authentication backend and setting up sync sources as seen earlier
Main directory scripts
start.sh		Starts the Funambol server
stop.sh		Stops the Funambol server
install.sh		Clean install's the Funambol server
update-modules.sh		Runs Funambol's update-modules script, for use after the fnbl-get tool or when you manually install modules
postreconfig.sh		Runs the postreconfig.sh should you need to perform actions provided by the postconfig tool manually

Post install configuration

Funambol administration tool

The Funambol administration tool can be used to configure GroupDAV sync settings and other aspects of the Funambol server, such as authentication.

Lauch it by entering the admin/bin directory and running funamboladmin:


cd admin/bin

./funamboladmin

Note: Users of OS X Leopard will have to launch the administration tool another way due to a bug:

sh platform6/lib/nbexec --clusters funamboladmin

After startup, login, by going to the File menu and clicking login.

There may be a delay when logging in, be patient.

If login fails, stop and start server again to be sure. If problem persists, see the troubleshooting section.

The left hand pane of the Funambol administration tool lists available configuration options and modules. Of interest to us is the ‚'groupdav' module. Expanding Modules->groupdav->BionicMessageGroupDAVConnector shows two choices:

Calendar (including task sync)
Contacts

Double clicking on contacts or calendar will take you to a source configuration screen.

GroupDAV Calendar and Address sync

Sync source configuration options

Calendar sync source automatically created during installation

Addressbook sync source automatically created during installation

Each sync source has various configuration options:

SyncML Source	Clients will use this URI to tell Funambol they want to sync with this source
GroupDAV Server	GroupDAV server in http://host:port/ format Reminder: Ensure you specify the port number, even if the server is on port 80! Note: Where possible, avoid SSL (https://) server connections. You would need to add the GroupDAV servers SSL certificate to the Java key store.
Data format	Funambol offers two sets of data formats:* IMC vCal/vCard ‚Äì used by just about all SyncML clients text/x-vcalendar (Events and Tasks) text/x-vcard Funambol SIF XML format ‚Äì format used by Funambol clients, recommended as data format compatibility is better text/x-s4j-sife (Events) text/x-s4j-sifc (Contacts) text/x-s4j-sift (Tasks)
Store locaton	Each GroupDAV sync source requires a 'store' for databases and sync logs. Ideally, this should be a directory within the Funambol bundle WARNING: Ensure correct permissions with this directory and the entire Funambol installation to prevent non-Funambol local users from viewing others data.
GroupDAV Source	(From connector version 2.0 onwards, the infrastructure supports multiple backend sources, however, this functionality is beyond the scope of this guide) The source(s) on the GroupDAV server to sync, i.e /groupdav/Calendar/ (Citadel) /zidestore/dav/%USER%/public/Calendar/ (OpenGroupware) Some OpenGroupware users also use the /zidestore/dav/%USER%/Overview backend, which shows everything. For servers such as OpenGroupware where the username is part of the source URL, use ‚'%USER%' in its place. The GroupDAV connector will substitute the user name from the client into this URL.
Symbian mixed todo mode	For use with devices running Symbian S60. Read the note on the next page.
Use single log files	By default, to assist with debugging and bug fixing, the connector will output two log files (connector and storelog) for each sync, uniquely timestamped. This setting changes this behavior to reuse the same log file, recommended for production environments.
OGo/Zidestore all day fix (GMT-relative all day)	Under this setting, when all day events are created/modified on the device, they are formatted in a way that OpenGroupware WebUI would detect. (With OpenGroupware WebUI it is advisable to enter in hours manually rather than use all day events) Note: With this option Funambol needs to know the timezone of each device syncing. This is the same process as Synthesis mentioned below.

Click ‚Save settings to activate the sync source. Should you want to reconfigure it later, just expand the Calendar/Contact type node.

CalDAV based time filtering

As of GroupDAV Connector 2.2, the connector can obtain a list of objects from the server via a CalDAV query. This functionality can be used to filter the events processed by the connector and eventually synced to the device. At the time of writing this functionality has only been tested on eGroupware SVN versions.

Component	Component to filter, i.e VEVENT
Property	Leave blank for now, empty placeholder property for CalDAV property based filtering, if needed.
Start	A date-time in rfc2445/ical2 format, i.e 20080514T120000Z
End	As above

Setting up proper encoding for SIF based sources (older Funambol clients)

As of Funambol 6.5.14 these steps are no longer required for newer clients, but some clients, such as the Java Demo/Test client still need it.

When using SIF based sync sources (i.e text/x-s4j-sif*), the data coming in and out of the sync source needs to be 'wrapped' in a way that separates it from the SyncML stream, which is also XML. Base64 encoding is used to achieve this. Also, you can encrypt the data with DES for added security.

Click on Server Settings in the administration tool tree
Click Configure on the Data Transformation Manager row.
Click the + ‚plus button on the Data Transformations group to add a new configuration row, and enter in the SyncML ID of the sync source, and ‚b64, respectively.

For more information, see ‚'Manually Enabling Encryption/Encoding' in the Funambol Administration guide.

Syncing calendars and tasks on Symbian (S60/UIQ) devices

Note: The install script creates a special source for Symbian devices: 'groupdav-s60-v'.

Symbian S60 devices sync the calendar and todo as a whole and need special treatment by the connector. All you need to do when creating a sync source is:

Click on the empty row below the default calendar source and add a new one: tasks pointing to your servers task source, i.e ‚/groupdav/Tasks/ for Citadel.

Note the output type should be text/x-vcalendar

Sync sources configured for S60 devices cannot be used by other devices/clients.

Post-sync configuration for Palm Synthesis event sync

After the first sync, you need to configure the timezone for your Palm device in the Funambol administration tool. As you did in the post-install configuration, start and log into your Funambol server.

Double-Click the Devices node in the left pane to access the devices panel
List all the devices known to the server by clicking the ‚Search button
Select your device from the table and click ‚Edit
Select your timezone from the dropdown
Tick Convert dates to this timezone
Fill in the type and description fields to keep Funambol happy.
Click Save.
Configure Synthesis to sync against your GroupDAV Calendar sync source
Sync.

Citadel Push Email

The install scripts will install the Citadel Email connector if you specified the Citadel server type during install time. You can use this to achieve "Push Email" functionality with Citadel and clients such as:

The Funambol Windows Mobile (PocketPC and Smartphone) client (recommended)
The Funambol J2ME client (Many modern mobile phones)

Options for push notification

Currently there are two methods available to send a new email notification to a phone:

Using Funambol's CTP server technology - which keeps an open TCP session between the phone and server (even behind operator NAT).
Using a SMS gateway (i.e Clickatell) to send a WAP Push message

CTP has an advantage in that there is no cost per message, but will drain battery, and seems to take a megabyte or two per day on top of any email traffic. If CTP sessions drop due to network or device problems the session usually does not come back until the user manually syncs. SMS has an advantage in that it will not drop battery, but there is a small cost per message.

Note: When the default notification type is changed devices will have to be deleted within the Funambol admin tool and then resynced in order to use them.

CTP Server

The CTP server has been included with the bundle distribution, and should be a 'plug and play' affair. However, you first have to set JAVA_HOME:

From the root dir of the bundle (i.e where ./install.sh is):
export JAVA_HOME=`pwd`/java # or where your JRE is
cd ctp-server
bin/ctpserver.sh start # append -debug for console output

SMS notification

Example Clickatell/SMS configuration

The bundle includes the 'BMClickatell' notification configured to use the Clickatell SMS gateway, however, is capable of using equally capable gateways provided they have a HTTP API.

To use SMS notification, run postreconfig while the server is running:

./postreconfig.sh setusepostnotify

You then need to use the administration tool to set your username, password and API ID detail. The SMS component is under smsnotify->bmclickatell .

For each user and device you wish to use push with you need to set its phone number, in international format (i.e 61430004010 for an Australian mobile number) in the Devices section of the Funambol admin tool.

URL field format

Should you wish to use the SMS notification component with another gateway, consider the URL format:

http://api.clickatell.com/http/sendmsg?api_id=%s&user=%s&password=%s&to=%s&udh=%s&data=%s

Key	Value
api_id	The API ID used to identify this connection with Clickatell. Mapped to the last field in the configuration screen
Username	Gateway username
Password	Gateway password
To	Phone number of device sending notification to. Must be in international format
UDH	User data field of SMS in Hex.
Data	Data field of SMS in Hex

When using a different gateway you must specify the URL fields in the exact same order.

Configuring Citadel to notify Funambol when new email arrives

Citadel needs to be configured to tell Funambol when email arrives. This needs to be done on two levels: system and user.

Citadel system push configuration

The system configuration involves entering the Funambol server, sync source and administrator password in Citadel. This can be done via Webcit or the command line Citadel client by logging in as the Administrator and going to the site configuration.

Citadel user push configuration

Each user wishing to use push email then needs to login via webcit and goto their Advanced settings page and then to Edit your push email settings and set their preference to use Funambol.

Troubleshooting

Enabling verbose logging

In the Funambol administration tool, logging can be configured in Server Settings->Logging. Turning up the verbosity can reveal more about server and connector operations.

Enabling debug mode logging

For security reasons, Funambol doesn't disclose the contents of sync items in the log file. This behavior can be changed by changing -Dfunambol.debug=false to -Dfunambol.debug=true

Tomcat stderr file

tools/tomcat/catalina.out catches stdout and stderr output, which often contains exceptions which miss the logger.

Connector/Store logs

Connector and store logs for each sync source can be found in the store directory you configured for your sync source. These log communication with the GroupDAV server and any errors encountered by the sync source.

Installing connector updates

fnbl-get downloading module updates

The server bundle contains a custom updating tool called fnbl-get, which will compare timestamps of the module archives in your ds-server installation to those on the server, and offer to upgrade them while keeping configuration in place.

To run the updater you have to stop the server first and then run the update script:

./stop.sh
./upgrade-modules.sh

For each module installed fnbl-get will compare the modification timestamps and offer to download a new version. After downloading all updates, the Funambol module installer script will run, and like the initial setup, ask if you want to overwrite the database for each module. As each module is already installed you should answer 'n' when asked.

Forcing a module update

If need be, you can force fnbl-get to download the latest version by setting the timestamp of the module archives back, by using the touch command:

touch -t 197001010101 ds-server/modules/bmclickatell.s4j 
touch -t 197001010101 ds-server/modules/groupdav-2.1.s4j

Retrieved from "http://wiki.bionicmessage.net/index.php?title=Groupware_sync_guide"

Groupware sync guide