Tomcat: The Definitive Guide

Preface

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).

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 do 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 do 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 6 possible on any Unix-like platform.

Appendix D is the source code for BadInputFilterValve, a Java request filter that is detailed in Chapter 6. This program will help protect your Tomcat installations from malicious attacks through improper request data.

Who This Book Is For

The book is written for anyone who wants to learn about the Tomcat servlet container. You do 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.

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.

Tip

Indicates a tip, suggestion, or general note

Warning

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 5 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.

How to Contact Us

We have tested and verified the information in this book to the best of our ability, but you may find that features have changed (or even that we have made mistakes!). Please let us know about any errors you find, as well as your suggestions for future editions, by writing to:

O’Reilly & Associates

1005 Gravenstein Highway North

Sebastopol, CA 95472

[phone] (in the U.S.A. or Canada)

[phone] (international or local)

[phone] (FAX)

You can also send us messages electronically. To be put on the mailing list or request a catalog, send email to:

[e-mail]

To ask technical questions or comment on the book, send email to:

[e-mail]

There is a web site for the book, where we’ll list examples, errata, and any plans for future editions. You can access this page at:

http://www.oreilly.com/catalog/tomcat

For more information about this book and the complete line of O’Reilly books, conferences, news sites, and so forth, see the O’Reilly web site:

http://www.oreilly.com

There are also web sites for this book that are maintained by its authors:

http://tomcatbook.darwinsys.com

http://tomcatbook.brittainweb.org

Acknowledgments

Thanks to James Duncan Davidson and Sun Microsystems for giving us Tomcat in the first place. James worked above and beyond the call of duty to write it and to work out the details of how it could become open source software. Sun Microsystems supported his pioneering work and has strongly supported the evolution of Tomcat since its donation to the Apache Software Foundation.

Thanks to (in no particular order) Craig McClanahan, Remy Maucherat, Pier Fumagalli, Costin Manolache, Henri Gomez, Ignacio J. Ortega, Jean-Frederic Clere, Glenn Neilsen, Bill Barker, Amy Roh, Hans Bergsten, Patrick Luby, Mladen Turk, Jeanfrancois Arcand, Jon Stevens, Filip Hanik, and others on the Tomcat mailing lists. Craig and Remy were the prime movers of the Tomcat 4 (Catalina) server. Many of us wonder how and when they sleep. Thank you, Craig, for Tomcat 4, for answers, and for your revolutionary code. Thank you, Remy, for the hard work; you’ve helped us so much through many great releases.

Open source projects are just not the same without a vibrant community surrounding them, and we believe that Tomcat could not have gone so far so fast without the stewardship of the Apache Software Foundation and its members. Thanks, ASF, for your hard work, servers, and bandwidth.

Jason Hunter, author of O’Reilly’s Java Servlet Programming, provided a very careful reading of the drafts and suggested many, many improvements. Special thanks to you, Jason.

Paula Ferguson saw the book through the early stages, then passed the torch to Brett McLaughlin. Brett made innumerable minor suggestions to improve the book, and also several times talked us into reorganizing scattered material into the (hopefully) comprehensible form you see before you. Thanks, Brett!

Ian Darwin’s Acknowledgments

Mike Loukides encouraged me to find an O’Reilly book to write, when a competing publisher tried to lure me away after the success of the Java Cookbook.

Kevin Bedell read the manuscript carefully cover to cover and suggested many improvements (as well as spotting several errors and omissions). Thanks, Kevin.

Over the years, I have learned a lot about JavaServer Pages from Chad Darby, author of Learning Tree’s (http://www.learningtree.com) course on servlets and JavaServer Pages. Chad also did a helpful review of the manuscript.

And, of course, to Betty, the woman of my life, and our children Benjamin, Andy, and Margaret. Thanks for your support and for the time away.

Jason Brittain’s Acknowledgments

I couldn’t have written my portion of this book without my wife, Carmina. She’s always shown confidence in me over the years, and with her I’m happier than I’ve ever been. Cutie, from the bottom of my heart, I thank you for all of your help with this book!

Thanks to James Duncan Davidson and Jason Hunter, who together had a strong vision of excellence for this book and worked hard to make that vision a reality.

Thanks to my current employer, CollabNet Inc., who integrates Tomcat, contributes to the Tomcat project, and kept me employed while I wrote my portion of this book.

Thanks to everyone at the (now defunct) Olliance Inc., who were patient while I carefully studied Tomcat and contributed to the project. The time I spent on Tomcat there will hopefully now be a great help to anyone who uses Tomcat.

Thanks to everyone I worked with at Leverage Information Systems, especially Ben Lai, David Smith, Thede Loder, Piyush Shah, Christine Etheredge, Alex Lisowski, Iain Lamb, and Chip Clofine, who got me into participating in open source servlet container projects in the first place. Each of you has been inspirational to me.

Thanks also goes to my good friends Lane Davis and Michaël Mattox, who have each helped me in numerous ways over the years, including helping me with this book.

I also want to thank Rodney Joffe, formerly of Genuity, for having lots of confidence in me early on in my career and for introducing me to the subjects of high availability, load balancing, and fault tolerance back in 1996. Also, to David Jemmett, formerly of GoodNet, for not only giving me my first big break as a software engineer and system administrator, but also for giving me a starting point into dynamic web content development in mid-1995. I’m grateful to each of you!