Difference between revisions of "Diag/swa-problems"

Revision as of 17:41, 12 March 2008

Diagnosing Problems with Scalix Web Access

Introduction

SWA depends on several major subsystems for proper operation. These include the Apache web server, the Tomcat application server running several web applications, Scalix LDAP service and the primary mail store which is accessed via IMAP. When problems are experienced by SWA users that are systemic in nature (that is, not a specific error related to performing one specific operation or referencing one specific message) it can be hard to pin down the source of the trouble. The many interacting subsystems, each with its own set of logs and configuration, present significant problem diagnosis challenges. The purpose of this document is to provide guidance on how to proceed and to collect together all the techniques that have proven useful in collecting diagnostic information from production SWA deployments.

Architecture

Beginning at the SWA user's browser, the system is architected as follows: The browser fetches static content and javascript code from a web server. Once the browser-resident javascript code is running, it too sends requests to the web server. The web server is the standard Apache 2.0 or 2.2 running on the machine that hosts the SWA service (which we will call the front-end server). Apache's job is to handle client HTTP connections, to perform SSL processing and to send the client requests on to Tomcat. TCP connections made by users' browsers to Apache are on port 80 or 443 (for SSL). Tomcat is essentially a web server, but with the special capability to run Java programs in-process. Tomcat itself is written in Java. We use Apache, rather than Tomcat, to handle the end-user browser connections because Apache has better scaling and security than Tomcat, and because SSL is more efficiently handled by Apache. Communication between Apache and Tomcat is via the AJP protocol which is similar but not identical to HTTP. The use of AJP allows the number of connections made to Tomcat to be kept reasonably low. This is because AJP, unlike HTTP, supports connection re-use for requests from different clients. AJP connections between Apache and Tomcat use port 8009. Tomcat is a web server written in the Java language and supporting the servlet interface. A servlet is a bundle of Java code that accepts HTTP requests and processes them to produce responses. The servlet concept has been expanded over time to include various associated aspects of application deployment such as packaging and the specification of URL paths, leading to the definition of the 'web application'. Although there are many web applications running in Tomcat, two are of primary importance for SWA : the swa server (called 'webmail') and the scalix messaging services, or platform (called 'api'). The webmail servlet is responsible for serving all SWA static content : images, html pages, css files and javascript. It also handles all AJAX (XmlHttpRequest) calls made by the browser-resident javascript. To perform certain operations the webmail servlet will in turn make a request to the messaging services servlet. The use of messaging services is optional. The default configuration is to use messaging services. In smaller deployments the messaging services servlet running on the same machine as webmail will be used (hence running in the same Tomcat instance). However is larger deployments it is possible that multiple messaging services web applications have been deployed, on several machines. Both webmail and messaging services in turn connect to LDAP and IMAP servers to access user information and message store content. All the subsystems : Apache, Tomcat, webmail, messaging services, IMAP and LDAP must be available and working properly in order for SWA to function correctly.

Problem Diagnosis Methodology

The best approach when presented with a problem reported by SWA users is to begin at the client and work progressively 'inwards' towards the IMAP service, examining service health at each subsystem along the way. Techniques for the analysis of each subsystem are discussed below:

Javascript Client

SWA's browser-resident Javascript code has a diagnostic logging capability. This feature is disabled by default for security and performance reasons. Follow these instructions to enable it.

Apache

Tomcat

Webmail

Messaging Services

IMAP