Installing funambol on B3 (Debian installation guide)
Posted: 26 Jun 2011, 05:27
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:
Set the environment variable JAVA_HOME so that Java applications can find the Java runtime environment, by adding it to /etc/bash.bashrc:
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:
MySQL will now ask you for the password we just specified. At the MySQL prompt, enter the following SQL commands:
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.
Extract the Funambol package:
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.
It might be useful to assign a password to this user, if only because some of the following steps marginally more convenient:
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.
Second thing, we remove any useless Windows executables:
Configure Funambol's data synchronisation server component to use the MySQL database we just created:
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:
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!):
Tell the install script where to find the Java installation by adding something like this to the beginning of the file:
Now let's edit the Funambol startup script itself:
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
and change them to:
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:
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:
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:
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:
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!):
Edit the beginning of this file, where it says
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:
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
(there should be 10 of them) and wrap them inside a su command like this:
Now tell Debian to start up Funambol at bootup:
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:
First, set up logging for the built-in Tomcat application server:
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:
Thirdly, we can delete the old Tomcat logfiles:
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:
Now set up logfile rotation for this new Tomcat logging location:
Make sure the logfile rotation configuration file looks something like this:
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:
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
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
Code: Select all
$ nano /etc/bash.bashrc
Code: Select all
JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre"
export JAVA_HOME
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
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;
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
Code: Select all
$ sh ~/downloads/funambol-10.0.2.bin
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
Code: Select all
$ passwd funambol
$ su funambol
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
Code: Select all
$ rm bin/*.cmd
$ rm bin/*.exe
$ rm tools/tomcat/bin/*.bat
$ rm tools/tomcat/bin/*.exe
Code: Select all
$ nano ds-server/install.properties
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)
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
Code: Select all
JAVA_HOME="/usr/lib/jvm/java-6-openjdk/jre"
export JAVA_HOME
Code: Select all
$ nano bin/funambol
Code: Select all
cd `dirname $0`
FUNAMBOL_HOME=`(cd .. ; pwd)`
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
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
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
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
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
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
Code: Select all
#!/bin/sh
cd `dirname $0`
FUNAMBOL_HOME=`(cd .. ; pwd)`
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
Code: Select all
sh $FUNAMBOL_HOME/bin/ctp-server start > /dev/null
Code: Select all
su funambol -c "sh $FUNAMBOL_HOME/bin/ctp-server start > /dev/null"
Code: Select all
$ update-rc.d funambol defaults
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
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
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
Code: Select all
$ rm -rf /opt/Funambol/tools/tomcat/logs
Code: Select all
$ su funambol
$ ln -s /var/log/funambol/tomcat /opt/Funambol/tools/tomcat/logs
Code: Select all
touch /etc/logrotate,d/funambol-tomcat
chmod 644 /etc/logrotate,d/funambol-tomcat
nano /etc/logrotate,d/funambol-tomcat
Code: Select all
/var/log/funambol/tomcat/*.log {
weekly
missingok
rotate 52
compress
delaycompress
notifempty
create 640 root adm
}
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 *
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