This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com • • • • • Table of Contents Index Reviews Reader Reviews Errata Tomcat: The Definitive Guide By Jason Brittain, Ian F Darwin Publisher: O'Reilly Pub Date: June 2003 ISBN: 0-59600-318-8 Pages: 336 Slots: Tomcat: The Definitive Guide offers something for everyone who uses Tomcat System and network administrators will find detailed instructions on installation, configuration, and maintenance For users, it supplies insightful information on how to deploy Tomcat And seasoned enterprise Java developers will have a complete reference to setting up, running, and using this powerful software The book covers all major platforms, including Windows, Solaris, Linux, and Mac OS X, contains details on Tomcat configuration files, and even has a quick-start guide to get developers up and running with Java servlets and JavaServer Pages This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com • • • • • Table of Contents Index Reviews Reader Reviews Errata Tomcat: The Definitive Guide By Jason Brittain, Ian F Darwin Publisher: O'Reilly Pub Date: June 2003 ISBN: 0-59600-318-8 Pages: 336 Slots: Copyright Preface What's This Book About? Why an Entire Book on Tomcat? Who This Book Is For Conventions Used in This Book How to Contact Us Acknowledgments Chapter Getting Started with Tomcat Section 1.1 Installing Tomcat Section 1.2 Starting, Stopping, and Restarting Tomcat Section 1.3 Automatic Startup Section 1.4 Testing Your Tomcat Installation Chapter Configuring Tomcat Section 2.1 Using the Apache Web Server Section 2.2 Managing Realms, Roles, and Users Section 2.3 Controlling Sessions Section 2.4 Accessing JNDI and JDBC Resources Section 2.5 Servlet Auto-Reloading Section 2.6 Relocating the Web Applications Directory Section 2.7 Customized User Directories Section 2.8 Tomcat Example Applications Section 2.9 Server-Side Includes Section 2.10 Common Gateway Interface (CGI) Section 2.11 The Tomcat Admin Application Chapter Deploying Servlet and JSP Web Applications in Tomcat Section 3.1 Layout of a Web Application Section 3.2 Manual Application Deployment Section 3.3 Automatic Deployment Section 3.4 The Manager Application This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Section 3.4 The Manager Application Section 3.5 Automation with Jakarta Ant Chapter Tomcat Performance Tuning Section 4.1 Measuring Web Server Performance Section 4.2 External Tuning Section 4.3 Internal Tuning Section 4.4 Capacity Planning Section 4.5 Additional Resources Chapter Integration with Apache Web Server Section 5.1 Introduction Section 5.2 The Pros and Cons of Integration Section 5.3 Installing Apache httpd Section 5.4 Apache Integration with Tomcat Section 5.5 Of Connectors and Configuration Files Section 5.6 Summary Chapter Tomcat Security Section 6.1 Introduction Section 6.2 Securing the System Section 6.3 Multiple Server Security Models Section 6.4 Using the -security Option Section 6.5 Setting Up a Tomcat chroot Jail Section 6.6 Filtering Bad User Input Section 6.7 Securing Tomcat with SSL Chapter Configuration Files and Their Elements Section 7.1 server.xml Section 7.2 web.xml Section 7.3 tomcat-users.xml Section 7.4 catalina.policy Chapter Debugging and Troubleshooting Section 8.1 Reading Log Files Section 8.2 URLs and the HTTP Conversation Section 8.3 Debugging with RequestDumperValve Section 8.4 When Tomcat Won't Shut Down Chapter Building Tomcat from Source Section 9.1 Installing Jakarta Ant Section 9.2 Obtaining the Source Section 9.3 Downloading Support Libraries Section 9.4 Building Tomcat Chapter 10 Tomcat Clustering Section 10.1 Clustering Terms Section 10.2 The Communication Sequence of an HTTP Request Section 10.3 Additional Resources Chapter 11 Final Words Section 11.1 Supplemental Resources Section 11.2 Community Appendix A Installing Java Section A.1 Choosing a Java SDK Appendix B JSPs and Servlets Section B.1 Why Both JSPs and Servlets? Section B.2 Simplifying JSPs with JavaBeans:Reusable Components Section B.3 Simplifying Your JSPs with Custom Tags Section B.4 Extending Tomcat Appendix C jbchroot.c This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Appendix D BadInputFilterValve.java Colophon Index This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Copyright © 2003 O'Reilly & Associates, Inc Printed in the United States of America Published by O'Reilly & Associates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472 O'Reilly & Associates books may be purchased for educational, business, or sales promotional use Online editions are also available for most titles (http://safari.oreilly.com) For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly & Associates, 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 & Associates, 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 & Associates, Inc was aware of a trademark claim, the designations have been printed in caps or initial caps The association between the image of a snow leopard and the topic of Tomcat is a trademark of O'Reilly & Associates, Inc 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 document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Preface What's This Book About? Why an Entire Book on Tomcat? Who This Book Is For Conventions Used in This Book How to Contact Us Acknowledgments This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com What's This Book About? Tomcat is a Java™ servlet container and web server from the Jakarta project of the Apache Software Foundation (http://jakarta.apache.org) A web server is, of course, the program that dishes out web pages in response to requests from a user sitting at a web browser But web servers aren't limited to serving up static HTML pages; they can also run programs in response to user requests and return the dynamic results to the user's browser This is an aspect of the web that Apache's Tomcat is very good at because Tomcat provides both Java servlet and JavaServer Pages (JSP) technologies (in addition to traditional static pages and external CGI programming) The result is that Tomcat is a good choice for use as a web server for many applications And it's a very good choice if you want a free, open source (http://opensource.org) servlet and JSP engine It can be used standalone, but it is often used "behind" traditional web servers such as Apache httpd, with the traditonal server serving static pages and Tomcat serving dynamic servlet and JSP requests This book is about how to use Tomcat itself If you're looking for detailed information and tutorials about how to write web applications, be sure to read Java Servlet Programming, by Jason Hunter with William Crawford (O'Reilly) This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com 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, and you'll need to, but there is a lot more to Tomcat than just getting it running You'll get more out of Tomcat if you understand how and why it was written So, in Chapter 1, we explain that To help you make informed decisions when installing Tomcat, we spend the rest of the chapter on the installation and startup processes In Chapter 2, we show you all about configuring Tomcat We talk about when you should use Tomcat as a standalone web server and servlet container, and when it's best to use Tomcat with the Apache httpd as its web server Then, we show you how to configure realms, roles, users, servlet sessions, and JNDI resources, including JDBC DataSources Next, we show how to turn on and off the auto-reloading of 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 and disable the example web applications, and how to enable server-side includes and common gateway interface scripting in Tomcat Finally, we close out the chapter by introducing you to the Tomcat administration web application, which will allow you to configure Tomcat through your web browser With Tomcat installed and configured just the way you like it, you're ready to learn more about servlet and JSP web applications and how to deploy them into your Tomcat In Chapter 3, 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 then show you how to automate the deployments of your web applications by way of copying, using the built-in manager web application, and by using the Jakarta Ant build tool Once you have Tomcat serving your web application, you may want to some performance tuning In Chapter 4, we show you how to measure and improve your Tomcat's performance We go over adjusting the number of processor Threads, JVM and operating system performance issues as they relate to Tomcat, turning off DNS lookups, and how to speed up JSPs We round out the chapter by discussing how capacity planning can affect performance Tomcat works as a complete standalone web server It supports static web pages, server-side includes, external CGI scripts, and many of the other paraphernalia associated with a web site However, Tomcat's forte, its raison d'etre, is to be the best servlet and JSP engine on the block These are the things it does best So, for many applications you may want or need to use Tomcat in conjunction with other servers Maybe you already run Apache's web server and don't want to change everything all at once So, Chapter 5, covers the use of Tomcat with an Apache frontend and talks about the several ways to make Tomcat thrive "behind" an Apache installation Whether you're providing e-commerce, putting up a mailing list, or running a personal site, when you're connected to the Internet, your site is exposed to a lot of people, including a few weirdos who think it's okay to exploit the vulnerabilities in your server software for fun and profit Because security is important, we devote Chapter 6, to the topic of how to keep the online thugs at bay In Chapter 7, we talk about the Tomcat configuration files, server.xml and web.xml, as well as tomcat-users.xml and catalina.policy Each can be modified to control how Tomcat works When something goes wrong with your Tomcat or a web application, Chapter 8, shows you some ways to diagnose the problem We show you what to look for in the log files, how the web browser interacts with Tomcat's web server during a request, how to get verbose information about a particular request, and what to when Tomcat just won't shut down when you tell it to Not everyone wants to run a prepackaged binary release of Tomcat, so in Chapter 9, we show you how to compile your own Tomcat We show you step-by-step how to install the Jakarta Ant build tool, download all necessary support libraries, and build and install your Tomcat If you have more request traffic than a single Tomcat can handle, or if you want your site to keep serving requests when one of your servers crashes, your site may need to run on more than one Tomcat server, more than one Apache, or a combination of the two Sometimes the only solution is more hardware In Chapter 10, we show you some options for running two or more Tomcat servlet containers in parallel for higher scalability, and we discuss the pros and cons of various clustering approaches In Chapter 11, we have tried to bring together a solid listing of Tomcat resources that you can use in your further explorations of Tomcat While this is hardly comprehensive, these are the resources we find ourselves most often pulling up in a browser or opening on our desks Depending on your operating system, installing Java may not be as straightforward as you think To ensure that Tomcat runs well on your server computer, in Appendix A, we show you step-by-step how to install the JDK, as well as some Java issues to watch out for In Appendix B, we describe what servlets and JSPs are and how to write and install some JSPs We also talk about some tools for building web pages and XML, tools for managing your entire site, tools for letting your JSP send email, and even how you can generate a PDF document from a JSP, as well as other useful free programs Appendix C is the source code for jbchroot.c, a useful program to make the chroot jail operation described in Chapter possible on any Unix-like platform Appendix D is the source code for BadInputFilterValve, a Java request filter that is detailed in Chapter This program will help protect your Tomcat installations from malicious attacks through improper request data This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Who This Book Is For The book is written for anyone who wants to learn about the Tomcat servlet container You not have to be a programmer to use Tomcat or this book; all of the Java programming is, as mentioned earlier, tucked away inside servlets or other components You may be a system or network administrator who wants to run a small simple web site You may be an experienced Apache Web Server webmaster who now needs to run one or more servlets or JSPs as part of a larger site, or a programmer who is developing Java web components and wants to quickly get up to speed on using Tomcat as a web application development framework Maybe you're running a J2EE server or Sun's Web Server Pack and want more documentation on the Tomcat part of that software For any of these and other readers, this book provides an excellent introduction to Tomcat This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Conventions Used in This Book The following font conventions are used in this book: Italic Indicates filenames, pathnames, program names, URLs, and new terms where they are defined Constant width Indicates command lines and options that should be typed verbatim, Java class names and attributes, and XML element names and tags Constant width bold In code examples, indicates user input or lines of particular note Constant width italic Indicates text that should be replaced with user-supplied values Indicates a tip, suggestion, or general note Indicates a warning or caution Additionally, the initials "SRV" with a dotted decimal number after them refers to the indicated section in the Servlet Specification, Version 2.3 For example, SRV.6.5 refers to section 6, subsection of the Servlet Specification Similarly, "JSP" with a dotted number refers to the given section in the JSP specification You can download the servlet and JSP specifications from http://java.sun.com/products/servlet and http://java.sun.com/products/jsp, respectively ... this The Tomcat RPM creates a user and group (both named tomcat4 ) and runs Tomcat with that user and group The default shell of the tomcat4 user is /bin/bash Don't try to change this, or Tomcat. .. Hanik, and others on the Tomcat mailing lists Craig and Remy were the prime movers of the Tomcat (Catalina) server Many of us wonder how and when they sleep Thank you, Craig, for Tomcat 4, for... up Tomcat with the standard output and error streams directed into the file $TOMCAT_ HOME/logs/catalina.out The run argument causes Tomcat to leave the standard output and error streams where they