Contents

Acknowledgments Introduction vii xxi

Tomcat Other Jakarta Subprojects

TE

RI

Humble Beginnings: The Apache Project The Apache Software Foundation The Jakarta Project

AL

Chapter 1: Apache and Jakarta Tomcat

1
2 3 3
4 4

Chapter 2: JSP and Servlets

First Came CGI Then Servlets Were Born
Servlet Containers Accessing Servlets

PY

Tomcat and Web Servers Summary

RI

GH

Java APIs The J2EE APIs J2EE Application Servers Agree on Standards, Compete on Implementation Tomcat and Application Servers

TE

The Big Picture: J2EE

GPL LGPL Other Licenses

MA

Distributing Tomcat Comparison with Other Licenses

5 6
6 7 7

7
7 8 9 10 10

11 12

13
14 14
15 16

And on to JSPs . . . JSP Tag Libraries Web Application Architecture Java Site Architecture Summary

CO

18 21 24 25 27

Contents
Chapter 3: Tomcat Installation
Installing the Java Virtual Machine
Installing the Sun JVM on Windows

29
29
29

Installing Tomcat
Tomcat Windows Installer Finishing the Installation Setting Environment Variables Testing the Installation Installing Tomcat on Windows Using the ZIP File Installing Tomcat on Linux

33
33 34 34 34 39 40

The Tomcat Installation Directory

The The The The The The The The bin Directory shared Directory common Directory conf Directory logs Directory server Directory webapps Directory work Directory

41
41 42 42 42 42 42 42 43

Troubleshooting and Tips

The Port Number Is in Use Running Multiple Instances A Proxy Is Blocking Access

43
43 44 44

Summary

44

Chapter 4: Tomcat Architecture

An Overview of Tomcat Architecture
The Server The Service The Remaining Classes in the Tomcat Architecture

45
45
47 47 50

Summary

50

Chapter 5: Basic Tomcat Configuration

Tomcat 5 Configuration Essentials Tomcat 5 Web-Based Configurator
Enabling Access to Configurator

51
52 53
54

Files in $CATALINA_HOME/conf Basic Server Configuration

Server Configuration via the Default server.xml Operating Tomcat in Application Server Configuration

58 60
60 66

Contents
Web Application Context Definitions Authentication and the tomcat-users.xml File The Default Deployment Descriptor web.xml How server.xml, Context Descriptors, and web.xml Work Together Fine-Grained Access Control: catalina.policy catalina.properties: Finer-Grained Control over Access Checks Configurator Bootstrapping and the Future of Tomcat Configuration A Final Word on Differentiating Between Configuration and Management 76 77 77 81 84 87 87 88

Summary

88

Chapter 6: Web Application Configuration

The Contents of a Web Application
Public Resources The WEB-INF Directory The META-INF Directory

91
91
92 94 95

The Deployment Descriptor (web.xml)

Servlet 2.3-Style Deployment Descriptor Servlet 2.4-Style Deployment Descriptor

96
97 110

Summary

125

Chapter 7: Web Application Administration

Sample Web Application Tomcat Manager Application
Enabling Access to the Manager Application Manager Application Configuration

127
128 129
130 132

Tomcat Manager: Using HTTP Requests

List Deployed Applications Installing/Deploying Applications in Tomcat 4.x Deploying a New Application Installing a New Application Installing/Deploying Applications in Tomcat 5.x Deploying a New Application Remotely Reloading an Existing Application Listing Available JNDI Resources Listing Available Security Roles Listing OS and JVM Properties Stopping an Existing Application Starting a Stopped Application Removing an Installed Application (Tomcat 4.x Only) Undeploying a Web Application

134
135 136 136 137 139 139 142 143 144 144 145 146 146 147

xi

Contents
Displaying Session Statistics Querying Tomcat Internals Using the JMX Proxy Servlet Setting Tomcat Internals Using the JMX Proxy Servlet 148 149 150

Tomcat Manager: Web Interface

Displaying Tomcat Server Status Managing Web Applications Deploying a Web Application

150
151 151 153

Tomcat Manager: Managing Applications with Ant Possible Errors Security Considerations Tomcat Deployer Summary

154 157 158 160 160

Chapter 8: Advanced Tomcat Features

Valves Interception Tomcat-Style Standard Valves Access Log Implementation
Scope of Log Files Testing the Access Log Valve

161
162 162 163
163 165

Single Sign-On Implementation

Multiple Sign-On Without the Single Sign-On Valve Configuring a Single Sign-On Valve

166
166 169

Restricting Access via a Request Filter

Remote Address Filter Remote Host Filter Configuring Request Filter Valves Request Dumper Valve

170
170 170 171 172

Persistent Sessions
The Need for Persistent Sessions Configuring a Persistent Session Manager

172
172 173

JNDI Resource Configuration

What Is JNDI? Tomcat and JNDI Typical Tomcat JNDI Resources Configuring Resources via JNDI Configuring a JDBC DataSource Configuring Mail Sessions

176
176 177 178 179 182 184

xii

Contents
Configuring Lifecycle Listeners
Lifecycle Events Sent by Tomcat Components The <Listener> Element Tomcat 5 Lifecycle Listeners Configuration

187
187 187 188

Summary

191

Chapter 9: Class Loaders

Class Loader Overview
Standard J2SE Class Loaders More on Class Loader Behavior Creating a Custom Class Loader

193
194
194 199 199

Security and Class Loaders

Class Loader Delegation Core Class Restriction Separate Class Loader Namespaces Security Manager

200
201 201 201 202

Tomcat and Class Loaders

System Class Loader Common Class Loader Catalina Class Loader Shared Class Loader Web Application Class Loader

202
203 203 204 204 205

Dynamic Class Reloading Common Class Loader Pitfalls

Packages Split Among Different Class Loaders Singletons XML Parsers

206 206
207 207 208

Summary

209

Chapter 10: HTTP Connectors

HTTP Connectors
Tomcat 4.0: HTTP/1.1 Connector Tomcat 4.1: Coyote HTTP/1.1 Connector Tomcat 5.x: Coyote HTTP/1.1 Connector

211
212
212 212 216

Configuring Tomcat for CGI Support Configuring Tomcat for SSI Support Running Tomcat Behind a Proxy Server Performance Tuning Summary

220 222 223 224 226

xiii

Contents
Chapter 11: Web Server Connectors
Reasons for Using a Web Server Connector Architecture
Communication Paths Connector Protocols

229
229 230
230 231

Choosing a Connector
JServ JK webapp JK2

233
233 234 234 234

Summary

235

Chapter 12: Tomcat and Apache Server

Introducing the JK2 Connector
The mod_ jk2 Apache module The Apache JServ Protocol (AJP) Coyote JK2 Connector

237
238
238 238 239

Understanding Tomcat Workers

Plug-In versus In-Process Multiple Tomcat Workers Types of Workers

239
239 240 240

Connecting Tomcat with Apache

Installing the Apache mod_ jk2 Module Configuring the AJP 1.3 Connector in server.xml Configuring Tomcat Workers Adding Directives to Load the jk2 Module (httpd.conf) Configuring the jk2.properties File Testing the Final Setup

241
241 243 243 247 247 248

Configuring SSL
Configuring SSL in Tomcat Configuring SSL in Apache Testing the SSL-Enabled Apache-Tomcat Setup

250
250 251 254

Tomcat Load Balancing with Apache

Changing CATALINA_HOME in the Tomcat Startup Files Setting Different AJP Connector Ports Setting Different Server Ports Disabling the Coyote HTTP/1.1 Connector Setting the jvmRoute in the Standalone Engine Commenting Out the Catalina Engine Tomcat Worker Configuration in jk2.properties

255
256 256 257 257 257 258 258

xiv

Contents
Tomcat Worker Configuration in workers2.properties Sample workers2.properties File 259 263

Testing the Load Balancer

Testing Sticky Sessions Testing Round-Robin Behavior Testing with Different Load Factors

265
266 267 269

Summary

270

Chapter 13: Tomcat and IIS

Role of the ISAPI Filter Connecting Tomcat with IIS
Testing Tomcat and IIS Installations Configuring the Connector in Tomcats server.xml file Installing the ISAPI Filter Updating the Windows Registry for the ISAPI Filter Configuring Tomcat Workers (workers2.properties) Configuring the jk2.properties File Creating a Virtual Directory Under IIS Adding the ISAPI Filter to IIS Testing the Final Setup

271
272 272
273 274 274 275 277 280 280 283 285

Troubleshooting Tips Performance Tuning

Web Site Hits per Day Keep Alive and TCP Connection Timeout Tuning the AJP Connector Load-Balanced AJP Workers

287 289
289 290 291 291

Using SSL Summary

291 292

Chapter 14: JDBC Connectivity

JDBC Basics
Establishing and Terminating Connections to RDBMSs Evolving JDBC Versions JDBC Driver Types Database Connection Pooling Tomcat and the JDBC Evolution

293
294
295 295 296 297 298

JNDI Emulation and Pooling in Tomcat 5 Preferred Configuration: JNDI Resources

Resource and ResourceParams tags Hands-On JNDI Resource Configuration Testing the JNDI Resource Configuration

299 300
301 304 310

xv

Contents
Alternative JDBC Configuration Alternative Connection Pool Managers
About PoolMan Deploying PoolMan PoolMans XML Configuration File Obtaining JDBC Connections Without JNDI Lookup Testing PoolMan with a Legacy Hard-coded Driver Obtaining a Connection with JNDI Mapping Testing PoolMan with JNDI-Compatible Lookup Deploying Third-Party Pools

311 312
312 313 313 315 316 317 319 319

Summary

320

Chapter 15: Tomcat Security

Securing the Tomcat Installation
ROOT and tomcat-docs Admin and Manager Further Security jsp-examples and servlets-examples Changing the SHUTDOWN Command

321
321
322 322 323 323 323

Running Tomcat with a Special Account

Creating a Tomcat User Running Tomcat with the Tomcat User

324
324 324

Securing the File System

Windows File System Linux File System

326
326 328

Securing the Java Virtual Machine

Overview of the Security Manager Using the Security Manager with Tomcat Recommended Security Manager Practices

328
328 332 335

Securing Web Applications Authentication and Realms

Authentication Mechanisms Configuring Authentication Security Realms

337 337
337 340 341

Encryption with SSL

JSSE Protecting Resources with SSL

362
363 366

Host Restriction Summary

368 368

xvi

Contents
Chapter 16: Shared Tomcat Hosting
Virtual Hosting
IP-Based Virtual Hosting Name-Based Virtual Hosting

369
370
370 372

Virtual Hosting with Tomcat

Example Configuration

375
375

Introduction to Virtual Hosting with Tomcat

Tomcat Components Tomcat 5 as a Standalone Server Tomcat 5 with Apache

377
377 378 381

Fine-Tuning Shared Hosting

Creating Separate JVMs for Each Virtual Host Setting Memory Limits on the Tomcat JVM

386
387 391

Summary

393

Chapter 17: Server Load Testing

The Importance of Load Testing Load Testing with JMeter
Installing and Running JMeter Making and Understanding Test Plans with JMeter JMeter Features Distributed Load Testing

395
395 396
396 397 401 413

Interpreting Test Results

Setting Goals and Testing Them Establishing Scalability Limitations Further Analysis

414
414 416 416

Optimization Techniques
Java Optimizations Tomcat Optimizations

416
417 418

Exploring Alternatives to JMeter Summary

419 419

Chapter 18: JMX Support

The Requirement to Be Manageable All About JMX
The JMX Architecture Instrumentation Level

421
421 423
424 426

xvii

Contents
Agent Level Distributed Services Level 427 430

JMX Remote API An Anthology of MBeans

Standard MBeans Dynamic MBeans Model MBeans Open MBeans

430 430
431 431 431 431

JMX Manageable Elements in Tomcat 5

Manageable Manageable Manageable Manageable Tomcat 5 Architectural Components Nested Components Run-Time Data Objects Resource Object

431
432 436 437 439

Accessing Tomcat 5s JMX Support via the Manager Proxy

Working with the JMX Proxy Modifying MBean Attributes Accessing Tomcat JMX Support Remotely via the RMI Connector Setting Up the JNDI Initial Context Remote Tomcat Probing with queryjmx

444
445 447 450 452 452

Security Concerns Summary

454 454

Chapter 19: Tomcat 5 Clustering

Clustering Benefits
Scalability and Clustering The Need for High Availability

457
458
458 459

Clustering Basics
Master-Backup Topological Pattern Fail-Over Behavioral Pattern

460
460 460

Tomcat 5 Clustering Model

Load Balancing Session Sharing

461
462 464

Working with Tomcat 5 Clustering

Session Management in Tomcat 5 The Role of Cookies and Modern Browsers Configuring a Tomcat 5 Cluster Common Front End: Load Balancing via Apache mod_ jk2 Back-End 1: In-Memory Replication Configuration Back-End 2: Persistent Session Manager with a File Store

468
468 469 469 473 475 483

xviii

Contents
Back-End 3: Persistent Session Manager with a JDBC Store Testing a Tomcat Cluster with JDBC Persistent Session Manager Back-End 487 490

An Application-Level Load Balancing Alternative (Balancer)

Load Balancing with the balancer Filter Working with the balancer Filter Testing the balancer Filter Redirection and the Cookie Problem Hardware-Assisted Request Distribution with Common NAT

490
491 492 495 496 496

The Complexity of Clustering

Clustering and Performance Clustering and Response Time Solving Performance Problems with Clustering

497
497 498 498

Summary

498

Chapter 20: Embedded Tomcat

Importance of Embedded Tomcat in Modern System Design
Typical Embedded Application Scenarios The Role of the Administrator with Embedded Tomcat

501
502
503 503

Overview of Embedded Mode in Tomcat

The MBean Server and Object Bus Internal Versus External Control Apache Ant as a Scripting Engine

505
505 506 506

The Apache Jakarta Commons Modeler

Custom JMX Ant Tasks in the Commons Modeler <jmx-service> Task <mbean> Subelement <attribute> Subelement <modelerRegistry > or <mbean-descriptor> Task <jmx-operation> Task

507
507 508 509 509 509 510

Ant Script Operational Flow

Using an Ant Script to Start Up a Minimal Embedded Server Downloading and Installing Embedded Tomcat The min.xml Minimal Embedded Startup Script Testing the Embedded Tomcat Server Starting Up a Minimal Server Accessing Embedded Tomcat 5 Shutting Down the Embedded Server Adding the manager Web Application Adding the Manager Role for Authentication

510
512 512 512 517 517 517 519 519 520

xix

Contents
Adding an <mbean> Element to the manager Context Using the manager Application on the Embedded Server 521 521

Summary Appendix A: Log4J Appendix B: Tomcat and IDEs Appendix C: Apache Ant Index

522 525 551 559 573

xx