HowTos/Tomcat

Scalix Wiki -> How-Tos -> Tomcat Integration

Modifying Web Application Settings Without Restarting Tomcat

A Scalix web application such as SWA (/webmail) or the platform API (/api) must be restarted before changes to configuration settings will take effect. One way to restart a web application is to simply restart the scalix-tomcat service. However, sometimes it is inconvenient or disruptive to restart Tomcat when settings are changed. Luckily, you can restart an individual web application without restarting the Tomcat service by touching the application's web.xml file or by installing and using the Tomcat manager application.

Scalix web applications read configuration settings from files in your scalix folder. For example, the configuration file for SWA on a scalix server installed in /var/opt/scalix/sm is found at /var/opt/scalix/sm/webmail/swa.properties.

Touching web.xml to Restart an Application

First, you may wish to tail the tomcat log file so that you can observe deployment progress:

[root@scalixvm WEB-INF]# tail -f /var/opt/scalix/sm/tomcat/logs/catalina.out &

Tomcat will automatically redeploy a web application any time its web.xml deployment descriptor is modified. Simply touch the file and Tomcat will redeploy the application, reloading swa.properties.

[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/webmail/WEB-INF/web.xml

After a moment, the tomcat log will show that SWA has been redeployed.

Config checkResources
INFO: Reloading context [/webmail]
shutting down Scalix Web Access
initializing Scalix Web Access
SWA:WARN - cannot locate log4j properties file at: /var/opt/scalix/sm/webmail/log4j.properties
SWA:reading configuration @ /var/opt/scalix/sm/webmail/swa.properties
done initializing Scalix Web Access

A similar procedure will redeploy the platform, sis, caa, mobile client, res, or sac.

[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/api/WEB-INF/web.xml
[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/sis/WEB-INF/web.xml
[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/caa/WEB-INF/web.xml
[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/m/WEB-INF/web.xml
[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/res/WEB-INF/web.xml
[root@scalixvm WEB-INF]# touch /var/opt/scalix/sm/tomcat/webapps/sac/WEB-INF/web.xml

Using the Tomcat Manager to Restart an Application

The Tomcat manager application is a convenient web interface for starting and reloading web applications. It is useful, but requires a bit of work to configure properly.

Download and Install the Manager Application

First, download the Tomcat core, which includes the manager application, to your Scalix server host. Open the download page and find the link for the "Core" under "Binary Distributions". Click the link for the .zip or the .tar.gz archive, depending on your file format preference.

Unpack the archive and copy the manager application to the tomcat folder.

[root@scalixvm ~]# tar xzvf apache-tomcat-5.5.23.tar.gz
[root@scalixvm ~]# cp -r apache-tomcat-5.5.23/server/webapps/manager /var/opt/scalix/sm/tomcat/webapps/

Edit the configuration file in apache-tomcat-5.5.23/conf/Catalina/localhost/manager.xml and point the docBase to your scalix installation.

<Context docBase="/var/opt/scalix/sm/tomcat/webapps/manager"
         privileged="true" antiResourceLocking="false" antiJARLocking="false">

  <!-- Link to the user database we will get roles from -->
  <ResourceLink name="users" global="UserDatabase"
                type="org.apache.catalina.UserDatabase"/>

</Context>

Copy the configuration file to the tomcat folder.

[root@scalixvm ~]# cp apache-tomcat-5.5.23/conf/Catalina/localhost/manager.xml /var/opt/scalix/sm/tomcat/conf/Catalina/localhost/

Grant Access to the Manager Application

Next, you will need to make the manager application available at some URL and create a user with permission to access the application. Follow the instructions in the documentation for Configuring Manager Application Access. For this example, I edited the file /var/opt/scalix/sm/tomcat/conf/tomcat-users.xml and created a user named "admin" with the password "password" by adding the line:

  <user username="admin" password="password" roles="manager"/>

Also, I added the following section to /var/opt/scalix/sm/tomcat/conf/server.xml to make the manager application available at the "/manager" path. Place this element in the Service name="Catalina" element of server.xml. The Valve shown here restricts access to the local host by IP address.

    <!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
    <Connector port="8080" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" redirectPort="8443" acceptCount="100"
               connectionTimeout="20000" disableUploadTimeout="true"
               URIEncoding="UTF-8">
               <Valve className="org.apache.catalina.valves.RemoteAddrValve"
                allow="127.0.0.1"/>
    </Connector>

Restart Tomcat to install the configuration changes made so far.

/etc/init.d/scalix-tomcat restart

Re-Deploying the /webmail Application

Open a web browser and enter the URL for the manager application configured in the previous step. In the example given, the address is http://localhost:8080/manager. Enter the username and password you added to tomcat-users.xml (admin/password in the example given). The manager application will open.

In the "Applications" table, find the row for the /webmail application. Click the "Reload" link to reload the application. SWA is restarted, and any changes made to swa.properties will now take effect.

For more information, refer to the manager app how-to.

Running Tomcat as a non-root user

For security reasons, it is preferrable to run Tomcat as a non-root user. In fact, most tomcat packages that come with OS distributions do it this way.

For Scalix this poses a few problems because the RES web application (which is part of the Scalix Admin Console system) needs to execute Scalix admin commands ("om-commands"), some of which must be executed with superuser/root privileges.

Scalix 10.0.0 and later therefore allow the use of sudo to limit root access to the commands in question.

Follow these steps:

1. On each machine running RES, install the sudo package that comes with your Linux distribution of choice.

2. Setup a /etc/sudoers file that has the following line (Note: This must be on a single line in the file):

<user> <hostname> = NOPASSWD : /opt/scalix/bin/*, /opt/scalix/diag/* , /bin/rpm, /usr/bin/dpkg, /bin/tail, /bin/df

where <user> is the name of the Unix user under which tomcat runs and <hostname> is your Scalix server hostname.

3. Add the following parameter to /etc/opt/scalix/res/config/res.properties:

res.sudo.commands.mode=true

Note: As of Scalix 10.0.1, the sample entry in the config file is wrong; this reads res.commands.sudo.mode=true and is incorrect. The correct entry is as per above.

4. Restart Tomcat

All access to Scalix commands will be logged by sudo through syslog.