SECOND EDITION Tomcat The Definitive Guide Jason Brittain with Ian F. Darwin Beijing • Cambridge • Farnham • Köln • Paris • Sebastopol • Taipei • Tokyo Tomcat: The Definitive Guide, Second Edition by Jason Brittain with Ian F. Darwin Copyright © 2008 O’Reilly Media, Inc. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or [email protected]. Editor: Simon St.Laurent Indexer: Tolman Creek Design Production Editor: Loranah Dimant Cover Designer: Karen Montgomery Copyeditor: Nancy Reinhardt Interior Designer: David Futato Proofreader: Loranah Dimant Illustrator: Jessamyn Read Printing History: June 2003: First Edition. October 2007: Second Edition. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Tomcat: The Definitive Guide, the image of a snow leopard, and related trade dress are trademarks of O’Reilly Media, Inc. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. O’Reilly Media, Inc. is independent of Sun Microsystems. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. This book uses RepKover™, a durable and flexible lay-flat binding. ISBN-10: 0-596-10106-6 ISBN-13: 978-0596-10106-0 [M] Table of Contents Preface . ix 1. Getting Started with Tomcat . 1 Installing Tomcat 1 Starting, Stopping, and Restarting Tomcat 17 Automatic Startup 29 Testing Your Tomcat Installation 34 Where Did Tomcat Come From? 35 2. Configuring Tomcat . 38 A Word About Using the Apache Web Server 38 Relocating the Web Applications Directory 39 Changing the Port Number from 8080 42 Java VM Configuration 51 Changing the JSP Compiler 54 Managing Realms, Roles, and Users 55 Controlling Sessions 70 Accessing JNDI and JDBC Resources 75 Servlet Auto-Reloading 78 Customized User Directories 78 Tomcat Example Applications 80 Common Gateway Interface (CGI) 80 The Tomcat Admin Webapp 82 v 3. Deploying Servlet and JSP Web Applications in Tomcat . 86 Layout of a Web Application 93 Deploying an Unpacked Webapp Directory 95 Deploying a WAR File 100 Hot Deployment 106 Working with WAR Files 107 The Manager Webapp 108 Automation with Apache Ant 111 Symbolic Links 124 4. Tomcat Performance Tuning . 126 Measuring Web Server Performance 127 External Tuning 153 Internal Tuning 156 Capacity Planning 164 Additional Resources 167 5. Integration with the Apache Web Server . 169 The Pros and Cons of Integration 170 Installing Apache httpd 174 Apache Integration with Tomcat 177 Tomcat Serving HTTP over the APR Connector 194 6. Tomcat Security . 201 Securing the System 202 Multiple Server Security Models 204 Using the SecurityManager 205 Granting File Permissions 208 Setting Up a Tomcat chroot Jail 213 Filtering Bad User Input 224 Securing Tomcat with SSL 241 7. Configuration . 259 server.xml 260 web.xml 316 tomcat-users.xml 333 catalina.policy 333 catalina.properties 334 context.xml 335 vi | Table of Contents 8. Debugging and Troubleshooting . 336 Reading Logfiles 336 Hunting for Errors 337 URLs and the HTTP Conversation 337 Debugging with RequestDumperValve 342 When Tomcat Won’t Shut Down 343 9. Building Tomcat from Source . 347 Installing Apache Ant 348 Obtaining the Source 349 Downloading Support Libraries 351 Building Tomcat 352 10. Tomcat Clustering . 354 Clustering Terms 355 The Communication Sequence of an HTTP Request 356 Distributed Java Servlet Containers 366 Tomcat 6 Clustering Implementation 370 JDBC Request Distribution and Failover 388 Additional Resources 389 11. Final Words . 391 Supplemental Resources 391 Community 395 A. Installing Java . 397 B. jbchroot.c . 410 C. BadInputValve.java . 416 D. BadInputFilter.java . 426 E. RPM Package Files . 439 Index . 463 Table of Contents | vii This book is lovingly dedicated to our son Alex and our daughter Angie. —Jason Brittain Preface1 Tomcat has eased the lives of thousands of Java™ developers, supplying them with a free environment for testing anddeployingweb applications. Tomcat has provedits mettle in all kinds of environments, providing the foundation you’ll need to apply your Java expertise to the Web. What’s This Book About? Tomcat is a Java servlet container andweb server from the Apache Software Founda- tion (http://tomcat.apache.org). A web server is, of course, a program that dishes out web pages in response to requests from, for example, a user sitting at a web browser. But web servers aren’t limitedto serving up static HTML pages; they can also run programs in response to user requests andreturn the dynamicresults to the user’s browser. This is an aspect of the Web that Apache’s Tomcat is very goodat because Tomcat provides both Java servlet and JavaServer Pages (JSPs) technologies (in addi- tion to serving traditional static pages and external CGI programs written in any pro- gramming language). The result is that Tomcat is a goodchoice for use as a web server for many applications, including using it as a high performance production web server. Andit’s a very goodchoice if you want a free, open source ( http:// opensource.org) servlet andJSP engine. It can be usedstandaloneandin conjunction with other web servers such as Apache httpd. This book is about how to use Tomcat itself. If you’re looking for detailed informa- tion andtutorials about how to write web applications, be sure to read Java Servlet Programming by Jason Hunter with William Crawford (O’Reilly). ix Why an Entire Book on Tomcat? Can’t you just download and run Tomcat from the Apache Software Foundation’s web site? Well, of course you can, andyou’ll needto, but there is a lot more to Tom- cat than just getting it running. You’ll get more out of Tomcat if you understand how andwhy it was written. So in Chapter 1, Getting Started with Tomcat, we explain that. You will then be better able to make informeddecisionson choices you might needto make when installing Tomcat, so we spendthe rest of the chapter on the installation and startup procedures. In Chapter 2, Configuring Tomcat, we show you all about configuring Tomcat. We talk about when you shoulduse Tomcat as a standaloneweb server andservlet container andwhen it’s best to use Tomcat with the Apache httpd web server. Then, we show you how to configure realms, roles, users, servlet sessions, andJNDI resources, includ- ing JDBC DataSources. Next, we show how to turn on andoff the auto-reloadingof servlets, how to relocate the webapps directory, and how to map user home directories for access through Tomcat. Then, we go over how to enable anddisablethe example web applications andhow to enable common gateway interface scripting in Tomcat. And finally, we close out the chapter by introducing you to the Tomcat administration web application, which allows you to configure Tomcat through your web browser. With Tomcat installedandconfiguredjust the way you like it, you’re readyto learn more about servlet andJSP web applications andhow to deploythem into your Tomcat. In Chapter 3, Deploying Servlet and JSP Web Applications in Tomcat,we show you the layout of a web application, how to deploy a web application, and how to deploy individual servlets and JSP pages. Next, we show you how to build web application archive files and how to deploy them. To make things less tedious, we review how to automate the deployments of your web applications by copying, using the built-in manager web application, and using the Jakarta Ant build tool. Once you have Tomcat serving your web application, you may want to do some per- formance tuning. In Chapter 4, Tomcat Performance Tuning, we show you how to measure andimprove your Tomcat’s performance. We go over adjustingthe num- ber of processor Threads, JVM andOS performance issues as they relate to Tomcat, turning off DNS lookups, andhow to speedup JSPs. We roundout the chapter by discussing how capacity planning can affect performance. Tomcat works as a complete standalone web server. It supports static web pages, external CGI scripts, andmany of the other paraphernalia associatedwith a web site. However, Tomcat’s forte, its raison d’etre, is to be the best servlet andJSP engine on the block. These are the things it does best. If you already run Apache’s httpd web server anddon’twant to change everything all at once, Chapter 5, Integration with the Apache Web Server, covers the use of Tomcat with Apache httpd andtalks about the several ways of making Tomcat thrive “in front of” or “behind” an Apache httpd installation. x | Preface Whether you’re providing e-commerce, putting up a mailing list, or running a per- sonal site, when you’re connectedto the Internet, your site is exposedto a lot of peo- ple, including a few weirdos who think it’s OK to exploit the vulnerabilities in your server software for fun and/or profit. Because security is important, we devote Chapter 6, Tomcat Security, to the topic of how to keep the online thugs at bay. In Chapter 7, Configuration, we talk about the Tomcat configuration files, server.xml and web.xml, as well as tomcat-users.xml, catalina.policy, catalina.properties, and con- text.xml files.