Installing funambol on B3 (Debian installation guide)

[rxmd]

Here's a small guide on installing the Funambol data synchronization server on a B3. It's a fairly popular and powerful solution for syncing data between various mobile devices, such as address books between phones etc.

Funambol is a powerful piece of software, but rather resource-heavy as it is written in Java and relies on the Apache Tomcat application server and its own database server, both of which are packaged into the installation. It also comes with its own version of the Java Runtime Engine, which for us is of course useless as it is compiled for Intel machines, while the B3 is an ARM machine. Consequently much of this guide will be dedicated to makíng Funambol work with what the B3 already has installed, and to trim down on its considerable resource usage so that it will fit into the B3. There are several guides for installing Funambol on Debian Squeeze, but they are either not very beginner-friendly or don't cover the particularities of installing it on a non-Intel, non-Sun, compact, memory-limited platform.

Note that Funambol still does not play well with Debian's packaging system and does not get updated automatically. This includes its application server Tomcat. It's possible to run Funambol on a dedicated installation of Tomcat (using Debian's tomcat6 package), which has the advantage of being more secure with regards to updates, and also more compatible with any other Tomcat web applications you might want to use. However, configuring this is a bit tricky and is officially unsupported by Funambol, so it's outside the scope of this guide.

1. Preparing the system

First of all, we need to install Java. Instead of Funambol's useless packaged Intel version of Sun's JDK, we will install OpenJDK as the Java runtime environment. Also, as the B3 already has a MySQL database server, we will use this MySQL database for storing our data. Consequently, we also need the MySQL connector for Java:

Code: Select all

$ apt-get install openjdk-6-jdk libmysql-java

Set the environment variable JAVA_HOME so that Java applications can find the Java runtime environment, by adding it to /etc/bash.bashrc:

Code: Select all

$ nano /etc/bash.bashrc

Code: Select all

JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre"
export JAVA_HOME

You can add the same lines to /etc/profile for good measure, and the JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre" (without the export line) to /etc/environment. Note that this still may not be sufficient for Funambol to pick it up during system startup, so we will hard-code it into Funambol's scripts as well.

MySQL configuration. We will assign a rood password to the MySQL admin user so that we can log into MySQL to do some things:

Code: Select all

$ mysqladmin -h localhost -u root password STRONG_ROOT_PASSWORD
$ mysql -h localhost -u root -p

MySQL will now ask you for the password we just specified. At the MySQL prompt, enter the following SQL commands:

Code: Select all

: create user ‘funambol_usr’@'locahost’ identified by ‘STRONG_FUNAMBOL_PASSWORD’;
: grant all privileges on *.* to ‘funambol_usr’@'localhost’ with grant option;
: flush privileges; 
: create database funambol;
: grant all on funambol.* to funambol_usr@’localhost’ identified by ‘STRONG_FUNAMBOL_PASSWORD’;
: exit;

2. Preparing the Funambol installation

Download Funambol. Substitute "ovh" in the following example for the Sourceforge mirror of your choice and make sure you download the latest version. This is approximately a 200MB download.

Code: Select all

$ cd ~/downloads
$ wget http://ovh.dl.sourceforge.net/project/funambol/bundle/v10/funambol-10.0.2.bin
$ chmod a+x funambol-10.0.2.bin

Extract the Funambol package:

Code: Select all

$ sh ~/downloads/funambol-10.0.2.bin

Agree to the license, extract to /opt/ as suggested, but say "no" to starting the server - Funambol would otherwise try to start using its built-in packaged version of Java, which is compiled for i386 and will fail.

Final preparation. We create a group and user for Funambol, set /opt/Funambol as this user's home directory, and make them owners of everything in this directory. Useradd will ask you for a password. You can assign an arcane password for this user, but make sure that you write it down because we will use it at least once.

Code: Select all

$ groupadd funambol
$ useradd -g funambol -d /opt/Funambol funambol
$ chown -hR funambol:funambol /opt/Funambol
$ cd /opt/Funambol

It might be useful to assign a password to this user, if only because some of the following steps marginally more convenient:

Code: Select all

$ passwd funambol
$ su funambol

3. Customizing Funambol before installation


OK. Now we start customizing Funambol for our installation on Bubba. First thing, we get the useless x86 JDK out of the way, together with Funambol's built-in database server that we won't be using.

Code: Select all

$ rm -rf tools/hypersonic
$ rm -rf tools/jre-1.6.0

Second thing, we remove any useless Windows executables:

Code: Select all

$ rm bin/*.cmd
$ rm bin/*.exe
$ rm tools/tomcat/bin/*.bat
$ rm tools/tomcat/bin/*.exe

Configure Funambol's data synchronisation server component to use the MySQL database we just created:

Code: Select all

$ nano ds-server/install.properties

Find the line where it says "dbms=hypersonic" and change it to "dbms=mysql", and make sure that the JDBC configuration section later in the file looks like this:

Code: Select all

jdbc.classpath=/usr/share/java/mysql-connector-java.jar
jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost/funambol?characterEncoding=UTF-8
jdbc.user=funambol_usr
jdbc.password=STRONG_FUNAMBOL_PASSWORD (that you set at the MySQL prompt above)

Note that the example MySQL configuration in the install.properties file refers to a particular version of the MySQL Java connector. Debian provides a symlink that should remain constant even when the MySQL Java connector is updated, so we use the symlink instead.

Now we'll have to edit some Funambol files to make it work with the system Java installation, to save some memory, and to be able to run it during system startup. Let's start with the install script (note: we haven't actually run the install script yet!):

Code: Select all

$ nano bin/install

Tell the install script where to find the Java installation by adding something like this to the beginning of the file:

Code: Select all

JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre"
export JAVA_HOME

Now let's edit the Funambol startup script itself:

Code: Select all

$ nano bin/funambol

In the beginning of the Funambol startup script, there are a few statements where Funambol tries to find its own directory. These may not work when Funambol is invoked from an init script, so we hard code the directory instead. Find the lines where it says

Code: Select all

cd `dirname $0`
FUNAMBOL_HOME=`(cd .. ; pwd)`

and change them to:

Code: Select all

# cd `dirname $0`
# FUNAMBOL_HOME=`(cd .. ; pwd)`
FUNAMBOL_HOME="/opt/Funambol"

JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre"
export JAVA_HOME

Also later in the file, find the line where it says "COMED=true" and change it to "COMED=false" in order to prevent Funambol from starting up its own database server, which we don't need because we use MySQL.

The last change we have to make to these files concerns the memory usage. By default, Funambol is a bit of a memory hog, which we have to get under control a little bit because our server doesn't have a lot of memory. So edit the startup scripts for Funambol's individual servers:

Code: Select all

$ nano bin/funambol-server
$ nano bin/inbox-listener
$ nano bin/pim-listener
$ nano bin/ctp-server

In each of those, find the line where it says MEM_OPTS="-Xmx512M" (or some other value) and change it to 128M (for funambol-server, which is the base synchronisation server) and to 32M for inbox-listener, pim-listener and ctp-server.

4. Installing Funambol

Now we can start the actual installation. Run the install script so that Funambol can set up its database:

Code: Select all

$ bin/install

Tell Funambol to (re)create all the databases, unless you have an existing MySQL Funambol database structure. The install process should take a few minutes, during which Funambol will generate the database structure inside MySQL, propagate your configuration settings to the configuration XMLs for the various Listener modules (located in /opt/Funambol/config/com/funambol) and set up its built-in Tomcat installation.

Now its time to actually start the thing up. If you feel masochistic, fire up htop in another SSH console and watch Funambol gobble up memory and CPU time while it spends 20 seconds starting up:

Code: Select all

$ bin/funambol start

Once startup is completed, fire up a web browser and connect to Funambol's Web demo client to see if it's working (http://b3:8080/webdemo, username/password guest/guest).

If the web demo works, try to connect to the Funambol server itself to see if that is working, too: http://b3:8080/funambol.

If you get a 404 error at this point, saying that "The requested resource (/funambol/) is not available", we have to help Tomcat a little bit with the installation of the web application and expand it manually:

Code: Select all

$ cd tools/tomcat/webapps/funambol
$ jar xfv ../funambol.war

Connecting to http://b3:8080/funambol, we should now see the Funambol DS Server's startup page.

5. Loading Funambol automatically at system startup

Now we don't want to start Funambol manually all the time, but we want it to be started together with all the other system services. In order to do this, do the following (as root!):

Code: Select all

$ cp /opt/Funambol/bin/funambol /etc/init.d
$ nano /etc/init.d/funambol

Edit the beginning of this file, where it says

Code: Select all

#!/bin/sh

cd `dirname $0`
FUNAMBOL_HOME=`(cd .. ; pwd)`

and make the following changes to make sure that the Funambol home directory is hard-coded, that the Java installation is found and that the new init script plays nice with the Debian install script system. Note that we've added Apache to the list of recommended bootup scripts because we will use Apache later on as a transparent proxy. The $all keyword ensures that Funambol gets loaded as late as possible during the bootup sequence:

Code: Select all

#!/bin/sh
### BEGIN INIT INFO
# Provides:          funambol
# Required-Start:    $remote_fs $syslog $network $all mysql 
# Required-Stop:     $remote_fs $syslog $network mysql
# Should-Start:      $named $time apache2
# Should-Stop:       $named $time apache2
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start and stop the funambol data synchronisation server
# Description:       Controls the Funambol data synchronisation server, its built-in
#                    Tomcat application server and its various listeners
### END INIT INFO
 
# cd `dirname $0`
FUNAMBOL_HOME=`(cd /opt/Funambol ; pwd)`

JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre"
export JAVA_HOME

Also, we don't want to run the Funambol server as root, so we have to modify the file to start up all the various subprocesses under our newly-created Funambol user. For this, take all the instances where the script contains something like

Code: Select all

sh $FUNAMBOL_HOME/bin/ctp-server start > /dev/null

(there should be 10 of them) and wrap them inside a su command like this:

Code: Select all

su funambol -c "sh $FUNAMBOL_HOME/bin/ctp-server start > /dev/null"

Now tell Debian to start up Funambol at bootup:

Code: Select all

$ update-rc.d funambol defaults

Reboot your B3 to see whether startup is working correctly. Fire up htop to watch Funambol eat CPU cycles and memory

6. Changing logfile locations

By default, Funambol writes extensive amounts of logfiles into its own /opt/Funambol directory tree. We'd prefer to have those in the standard location under /var/log. Redirecting Funambol's logging is a two-step process; first we have to redirect the logging of Funambol's packaged Tomcat application server, secondly we have to change the logging location of Funambol's own server packages. (I am following the examples in the Ubuntu guide by rao on http://ubuntuforums.org/showthread.php?t=1488582 and in https://core.forge.funambol.org/wiki/ChangeLogsPath)

As root, do the following to create a new logfile directory and secure it a little bit:

Code: Select all

$ mkdir /var/log/funambol
$ chown funambol:adm /var/log/funambol
$ chmod 750 /var/log/funambol

First, set up logging for the built-in Tomcat application server:

Code: Select all

$ mkdir /var/log/funambol/tomcat
$ chown funambol:adm /var/log/funambol/tomcat
$ chmod 750 /var/log/funambol/tomcat
$ nano /opt/Funambol/tools/tomcat/conf/logging.properties

Inside the file, take all the lines where it says "${catalina.base}/../../logs/http" (there should be five of them) and replace the latter by "/var/log/funambol/tomcat".

Secondly, we have to modify the Tomcat startup script. For this we use sed, to automatically replace the old with the new logfile locations:

Code: Select all

$ cd /opt/Funambol/tools/tomcat/bin/
$ cp -p catalina.sh catalina.sh.old
$ sed 's* "$CATALINA_BASE"/logs/* /var/log/funambol/tomcat/*g' catalina.sh.old > catalina.sh

Thirdly, we can delete the old Tomcat logfiles:

Code: Select all

$ rm -rf /opt/Funambol/tools/tomcat/logs

If you want, replace that by a link to their new location. Preferably do that when logged in as the "funambol" user we just created:

Code: Select all

$ su funambol
$ ln -s /var/log/funambol/tomcat /opt/Funambol/tools/tomcat/logs

Now set up logfile rotation for this new Tomcat logging location:

Code: Select all

touch /etc/logrotate,d/funambol-tomcat
chmod 644 /etc/logrotate,d/funambol-tomcat
nano /etc/logrotate,d/funambol-tomcat

Make sure the logfile rotation configuration file looks something like this:

Code: Select all

/var/log/funambol/tomcat/*.log {
       weekly
       missingok
       rotate 52
       compress
       delaycompress
       notifempty
       create 640 root adm
}

Note that this will not rotate the log file for the application server itself (catalina.out). If you want to rotate that too, you'll have to dig deeper into the Tomcat configuration, see http://wiki.apache.org/tomcat/FAQ/Logging#Q6.

To change the log file location for the Funambol servers themselves, you could change the configuration files by hand. However, it is much easier to use Funambol's server administration tool.
To do this, first create a couple of logfile subdirectories on your server:

Code: Select all

$ cd /var/log/funambol
$ mkdir content-provider
$ mkdir ds-server
$ chown -R funambol:adm *
$ chmod 750 *

Then download either the Windows or the Linux version of the administration tool from https://www.forge.funambol.org/download/#server, login to your server, go to (server) | Server Settings | Logging | Appenders, and change all entries where it says "/opt/Funambol/logs", replacing this by "/var/log/funambol". You can also shrink the logfiles from 100 to 10 or 20 MB and change the maximum rotation count from 5 to 2.

7. That's it!

You now have a working Funambol installation. To use this server for syncing, set up your mobile devices to use a sync URL like http://b3/funambol/ds, and enjoy

[Menace]

Thanks for the great Installation-Guide!
In my case (I've installed not on a B3 but on normal amd64-Hardware) I had to extract the funambol.war manually, too. So I think this is a Funambol-bug...