r12 - 24 May 2010 - 13:13:10 - BeckyHYou are here: Wiki >

AppLogic29 Web > CatApplicationServersTomcat

AppLogic 2.9 Documentation The latest production release is AppLogic 3.0.30

TOMCAT, TOMCAT64: Application Servers

	At a Glance
	Catalog	System
	Category	Application Servers
	User volumes	yes
	Min. memory	128 MB
	OS	Linux
	Constraints	no
	Questions/Comments	Ask Forum

Functional Overview

TOMCAT is web server appliance based on the Sun Java machine and Apache Tomcat, a Java Servlet and Java Server Pages container developed under the Apache License. The main documentation for Tomcat is at tomcat.apache.org. Tomcat provides standards-compliant support for Servlets and JSPs. Tomcat can work as standalone web server or as application server.

TOMCAT serves static web content, automatically deploys web applications, executes servlets and Java Server Pages from a user-configurable content volume. The paths to the documents are configurable, so that the same volume can be shared between multiple web servers and/or other appliances serving different content.

TOMCAT serves HTTP/1.1 and HTTP/1.0 protocol for web clients and AJP 1.3 for requests from front end servers (ex. Apache with mod_proxy_ajp).

Like WEBx servers, TOMCAT has three generic output terminals intended for accessing external services from scripts on the content volume. The db terminal is used for accessing a various databases; the fs terminal is used for accessing shared file storage (using NFS); and the aux terminal is created for sending e-mail messages to an SMTP server.

The log terminal should be used to connect TOMCAT to a shared file system where TOMCAT can store log files.

Configuration of the server is defined using various properties. These properties are designed to cover the most usage variants in an easy-to-configure way and in most cases only a few need to be set to a non-default values.

Name	Latest version	OS	Java machine version	Apache Tomcat version
`TOMCAT`	1.0.10-1	CentOS 5	JDK 1.6.0.18	5.5.28
`TOMCAT64`	1.0.11-1	CentOS 5 (64 bit)	JDK 1.6.0.18	5.5.28

Boundary

Resources for TOMCAT

Resource	Minimum	Maximum	Default
CPU	0.1	16	0.3
Memory	128 MB	4G	512 MB
Bandwidth	1 Mbps	2 Gbps	250 Mbps

Resources for TOMCAT64

Resource	Minimum	Maximum	Default
CPU	0.1	16	0.3
Memory	128 MB	64G	512 MB
Bandwidth	1 Mbps	2 Gbps	250 Mbps

The amount of memory should be configured based on the quantity of applications deployed on TOMCAT and their memory requirements.

TOMCAT64 is a 64-bit appliance and does not have the 4Gb memory limit like the 32-bit TOMCAT appliance.

TOMCAT has restrictions inherited from the 32-bit java machine. This java machine can't work with more than approximately 2.6Gb of memory and allocating more than 2.8Gb of memory for TOMCAT is inefficient.

Memory requirements for storing Java application sessions

In addition for memory for Java applications, some amount of memory must be available to store application sessions. Each empty session (with no aditional data stored) uses close to 2kbytes of memory. That memory is used during the session lifetime (the default session lifetime is 30 min). Session lifetime can be configured by modifying or adding an additional section to the web.xml configuration file of an application. For example including this code below configures the session lifetime to be 1 minute:

 
  <session-config>
    <session-timeout>1</session-timeout>
  </session-config>

If 10k unique visitors are expected in 30 min, an additional 20Mb of free memory is required. In general: "Required amount of memory" = "Maximum number of simultaneous active sessions" * "average size of a session".

If not enough memory is available, tomcat may malfunction. This depends upon the user applications that are running in tomcat and is not a limitation of the appliance itself.

Terminals

Name	Dir	Protocol	Description
`in`	in	http	Serves HTTP requests coming from web clients. Supports the `HTTP/1.1`, `HTTP/1.0` and `AJP` protocols.
`db`	out	any	Access to a database server. Usage is defined by whatever scripts reside on the content volume (if any). This terminal may be left unconnected if not used.
`fs`	out	nfs	Access to a network file system for shared file storage, providing read-write file access over `NFS`. Usage is defined by whatever scripts reside on the content volume (if any). Software on the content volume 'sees' the mounted remote file system as `/mnt/fs` in the appliance's filesystem space. This terminal may be left unconnected if not used. The connected server must have a read-write share named `/mnt/data` exported over NFS.
`log`	out	cifs	Access to a CIFS-based network file system for storing access and error logs. This terminal may be left unconnected if not used. The connected server must allow anonymous logins and have a read-write exported share named `share`.
`aux`	out	any	Access to a SMTP server for sending outgoing e-mail. This terminal may be left unconnected if not used.
`net`	out	any	Gateway output for subnet access. This terminal may be left unconnected if not used.
`mon`	out	cce	Sends performance and resource usage statistics to `MON` appliance. This terminal may be left unconnected if not used.

The default interface is enabled. It is intended for diagnostics and troubleshooting (over ssh). Future versions of this appliance may disable ssh access.

User Volumes

Volume	Description
`content`	Volume for the storage of tomcat applications, applications data, temporary and work files. This volume is only used if the `content_on_fs` property set to `off`.

Properties

Property name	Type	Description
`content_on_fs`	String	Specifies whether the content is relative to the file system at the `fs` terminal or is on the content volume. Default: `off` (on the content volume)
`hostname`	String	Host name of the web site. Default: `localhost`
`tomcat_port`	Integer	Port where Tomcat listens for incoming HTTP requests. Default: `8080`
`session_timeout`	Integer	Timeout for the user session, in minutes, during which `TOMCAT` will keep all data, associated with the user session, in memory. Default: `30`.
`max_connections`	Integer	Maximum number of allowed concurrent connections. When this number is reached, new connections are still accepted, but their processing is delayed until another connection is closed. Default: `100`
`heap_size`	Integer	Memory allocated for Java heap (the -Xmx Java option), in megabytes. If 0, this value is automatically calculated. Default: `0`
`perm_size`	Integer	Memory allocated for Java permanent objects (the -XX:PermSize Java option), in megabytes. If 0, this value is automatically calculated. Default: `0`
`app_base`	String	Root directory for the documents, work and temp files. A typical structure of `Tomcat` 's ${catalina.base} directory will be created in this folder: "shared" for libraries that are common to all java-applications; "temp" and "work" for temporary and work files; and subdirectory defined in `work_dir` property - analogue of ${catalina.base}/webapps. Default: `empty`
`work_dir`	String	Directory where the documents to be served are located. Also used for auto-deployment purpose. More information is available at Tomcat's website - Automatic Application Deployment . Default: `webapps`
`timezone`	String	Specifies the time zone used in the appliance. If this property is empty, the timezone is not modified and left as-is. A list of supported time zones is available here. Default: `empty`

Logging Properties

Property name	Type	Description
`logs_enabled`	String	Completely enables or disables logging. Default: `no`
`logs_base_dir`	String	Directory where log files are stored. Default: `empty`, logs will be placed in root of mounted NAS volume
`error_log_filename`	String	Filename prefix for the error log. Default: `catalina`
`log_level`	String	Logging level. The values are, increasing verbosity level, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. More detailed description of log levels is available here. Default: `INFO`
`enable_access_log`	String	Enables or disables access log. Default: `no`
`access_log_filename`	String	Filename prefix for the access log. Default: `access.log`

Custom Counters

The TOMCAT appliance reports the following custom counters through the mon terminal. These counters belong to the TOMCAT counter group (TOMCAT64 in the case of TOMCAT64):

Counter Name	Description
`Classes loaded`	Number of classes loaded
`Classes loaded bytes`	Number of Kbytes loaded
`Classes unloaded`	Number of classes unloaded
`Classes unloaded bytes`	Number of Kbytes unloaded
`Classe load/unload execution time`	Time spent performing class load and unload operations
`Compiler compiled`	Number of compilation tasks performed
`Compiler failed`	Number of compilation tasks that failed
`Compiler invalid`	Number of compilation tasks that were invalidated
`Compiler execution time`	Time spent performing compilation tasks
`Heap s0 space capacity`	Current survivor space 0 capacity
`Heap s1 space capacity`	Current survivor space 1 capacity
`Heap s0 space utilization`	Survivor space 0 utilization
`Heap s1 space utilization`	Survivor space 1 utilization
`Heap eden space capacity`	Current eden space capacity
`Heap eden space utilization`	Eden space utilization
`Heap old space capacity`	Current old space capacity
`Heap old space utilization`	Old space utilization
`Heap permanent space capacity`	Current permanent space capacity
`Heap permanent space utilization`	Permanent space utilization
`Heap young generation GC events`	Number of young generation GC Events (GC - Garbage Collection)
`Heap young generation GC time`	Young generation garbage collection time
`Heap number of GC events`	Number of full GC events
`Heap full GC time`	Full garbage collection time
`Heap total GC time`	Total garbage collection time
`Pool current new generation`	Current new generation capacity
`Pool min new generation`	Minimum new generation capacity
`Pool max new generation`	Maximum new generation capacity
`Pool current old generation`	Current old generation capacity
`Pool min old generation`	Minimum old generation capacity
`Pool max old generation`	Maximum old generation capacity
`Pool current permanent generation`	Current permanent generation capacity
`Pool min permanent generation`	Minimum permanent generation capacity
`Pool max permanent generation`	Maximum permanent generation capacity
`New generation tenuring theshold`	Tenuring threshold
`New generation max tenuring theshold`	Maximum tenuring threshold
`Desired survivor size`	Desired survivor size
`Compiler tasks`	Number of compilation tasks performed

Possible startup errors

In case of appliance startup failure, the following errors may be logged into the system log:

Error message	Description
`ERROR: Logs are enabled, but log terminal is not connected.`	`log` terminal isn't connected, but `logs_enabled` or `enable_access_log` is set to `yes`.
`ERROR: Property content_on_fs is 'off' but the local content volume is missing.`	The `content_on_fs` is set to `off`, specifying that the data volume must be mounted locally, but `TOMCAT` cannot mount content volume. Most probable cause is that the content volume is not formatted, or is not defined in `TOMCAT` properties.
`ERROR: Failed to mount nfs share.`	`TOMCAT` can't mount nfs share. The probable cause is that `fs` is not connected or `TOMCAT` was started before `NAS` (or whatever appliance is connected to the `fs` terminal)

Dashboard messages

Message	Description
`Data storage has less than 5% of free disk space`	The data volume accessed through the `fs` terminal has less than 5% of free disk space. It is advised to increase the size of the volume.
`Data storage has less than 1% of free disk space`	The data volume accessed through the `fs` terminal has less than 1% of free disk space. Immediate attention required; possible data loss may occur.
`Content volume has less than 5% of free disk space`	The content volume on the appliance has less than 5% of free disk space. It is advised to increase the size of the volume.
`Content volume has less than 1% of free disk space`	The content volume on the appliance has less than 1% of free disk space. Immediate attention required; possible data loss may occur.

Performance

The TOMCAT performance may be affected when logging is turned on (either error logging enabled by logs_enabled = yes or access logging - enable_access_log equals yes. The table below contains benchmark results (specified in rps units - requests per second) performed when logs are disabled with Apache Benchmark utility that ships with Apache web server version 2.0 and 2.2. More info for ab is available on apache web site. Following settings were used for benchmarking: "bw=500M mem=2G cpu=2".

concurrency	rps
1 client concurrency	2800-3200 rps
10 client concurrency	7500-7900 rps
100 clients concurrency	7700-8100 rps

Typical Usage

Simple java-enabled web site

The following diagram shows a typical usage of the TOMCAT appliance. TOMCAT will serve applications from content volume.

Appliances in use:

IN - input gateway
TOMCAT - java-enabled web server

Property name	Value	Notes
`hostname`	www.mysite.org	Hostname of site.
`app_base`	MyApp
`content_on_fs`	`off`	`TOMCAT` uses user volume `content` for all content.
`timezone`	EST	EST timezone.
`tomcat_port`	80	Standart port for the HTTP protocol.

Client requests arrive on the IN gateway. The gateway forwards the requests to the TOMCAT server, which serves the request.

2-tier application with database, log and monitoring

The following diagram shows a typical usage of the TOMCAT appliance with database, log, monitoring and content on a network storage.

Appliances in use:

IN - input gateway
TOMCAT - java-enabled web server
MYSQL5 - MySQL database appliance
NAS - network storage for content and logs
mon - monitoring appliance

Example property configuration:

Property name	Value	Notes
`hostname`	www.mysite.org	Hostname of site
`app_base`	MyApp
`content_on_fs`	`on`	`TOMCAT` uses remote storage through the `fs` terminal for all content
`timezone`	EST	EST timezone
`tomcat_port`	80	Standart port for HTTP protocol
`max_connections`	200	Max of 200 concurrent users
`logs_enabled`	`yes`	Enables error logs
`logs_base_dir`	MyApp_Log_Dir
`log_level`	`INFO`
`error_log_filename`	error_log	Error log name
`enable_access_log`	`yes`	Enables access log
`access_log_filename`	myapp_access	Access log name

Client request arrive on the IN gateway. The gateway forwards the requests to the TOMCAT server, which serves the request. Content and logs are on storage appliance. Counters are reported to mon appliance.

Java applications can use many types of databases. It depends only of presence of appropriate JDBC driver in application. TOMCAT allow to connect any database appliance to its db terminal.

WEB5 as a front end for TOMCAT

The following diagram shows a usage of the TOMCAT appliance as application server and WEB5 as frontend. WEB5 serves static content and redirects all requests that require server-side processing to the TOMCAT using AJP protocol.

It is necessary to enable AJP support (enable mod_proxy and mod_proxy_ajp) in WEB5 for this mode.

Appliances in use:

IN - input gateway
TOMCAT - java-enabled web server
WEB5 - front-end web server, for serving non java-generated content

Example property configuration:

Property name	Value	Notes
`content_on_fs`	`off`	`TOMCAT` uses the user volume `content` for all content
`timezone`	EST	EST timezone

Others settings have their default values.

WEB5 must be properly configured to work as frontend and communicate with TOMCAT via AJP protocol.

mod_proxy and mod_proxy_ajp must be enabled by including next lines in apache config

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

some path of url space must be specified to serve by TOMCAT , for example

ProxyPass /path-that-served-by-tomcat ajp://aux:8009/some-servlet
ProxyPassReverse /path-that-served-by-tomcat ajp://aux:8009/some-servlet

For example:

path	content	served by
/index.html	static html document	served by `WEB5`
/images/*	static graphical files	served by `WEB5`
/scripts/*.php	dynamic content generated by php scripts	served by `WEB5`
/path-that-served-by-tomcat	dynamic content generated by jsp	served by `TOMCAT`

Client request arrive on the IN gateway. The gateway forwards the requests to the forntend web server, which servers requests for static html pages, graphical files and php scripts. Requests for jsp pages or servlet pages are forwarded to AppServer and served by it.

Scalable java-enabled web site

The following diagram shows a typical usage of the TOMCAT appliance with load-balancing.

Appliances in use:

IN - input gateway
HALB - web load-balancer for user requests
AppServer1, AppServer2 - java-enabled web servers

Example property configuration for both AppServer1 and AppServer2 :

Property name	Value	Notes
`content_on_fs`	`off`	`TOMCAT` uses the user volume `content` for all content
`timezone`	EST	EST timezone

Others settings have their's default values.

Client request arrive on the IN gateway. The gateway forwards the requests to the lb load balancer, which directs the request to one of the servers AppServer1 and AppServer2.

Notes and Links

References:
- http://tomcat.apache.org/ -- Tomcats's web site
- http://tomcat.apache.org/tomcat-5.5-doc/index.html -- Tomcat 5.5 documentation

Open source and 3rd party software used inside of the appliance

TOMCAT and TOMCAT64 use the following 3rd party open source packages in addition to the 3rd party open source packages used by their base class LUX5 and LUX64 respectively.

TOMCAT

Software	Version	Modified	License	Notes
Apache Tomcat	5.5.28	Yes	Apache License v2.0	homepage
JDK	1.6.0.18	No	Sun-BCL	available on Sun website
samba-client	3.0.28-0.el5.8	No	GPLv2	N/A
samba-common	3.0.28-0.el5.8	No	GPLv2	N/A

TOMCAT64

Software	Version	Modified	License	Notes
Apache Tomcat	5.5.28	Yes	Apache License v2.0	homepage
JDK	1.6.0.18	No	Sun-BCL	available on Sun website
samba-client	3.0.28-1.el5_2.1	No	GPLv2	N/A
samba-common	3.0.28-1.el5_2.1	No	GPLv2	N/A

To see the full list of open source packages used in this appliance, please see its implementation design.

Questions and Comments

To post a question or comment on this appliance, visit our forum.

-- AndriyMayevskyy - 20 Nov 2008

AppLogic29

Documentation
- Home

References
- Dashboard
- Configurator
- Editor
- Monitor
- Volume Browser
- Shell
- Web Service API
- Catalog
- Applications
- Glossary

Guides
- App Provisioning?
- App Deployment
- Appliance Creation

Helpdesk| Bugzilla| Wiki

TOMCAT, TOMCAT64: Application Servers

Functional Overview

Boundary

Resources for TOMCAT

Resources for TOMCAT64

Memory requirements for storing Java application sessions

Terminals

User Volumes

Properties

Logging Properties

Custom Counters

Possible startup errors

Dashboard messages

Performance

Typical Usage

Simple java-enabled web site

2-tier application with database, log and monitoring

WEB5 as a front end for TOMCAT

Scalable java-enabled web site

Notes and Links

Open source and 3rd party software used inside of the appliance

TOMCAT

TOMCAT64

Related Documents

Questions and Comments