Tomcat the definitive guide (Jason Brittain Ian F Darwin) (Z-Library)

Tomcat The Definitive Guide SECOND EDITION 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 corporate@oreilly.com. Editor: Simon St.Laurent Production Editor: Loranah Dimant Copyeditor: Nancy Reinhardt Proofreader: Loranah Dimant Indexer: Tolman Creek Design Cover Designer: Karen Montgomery Interior Designer: David Futato 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]

v 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

vi | Table of Contents 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

Table of Contents | vii 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

ix Preface1 Tomcat has eased the lives of thousands of Java™ developers, supplying them with a free environment for testing and deploying web applications. Tomcat has proved its 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 and web 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 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 (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 good choice for use as a web server for many applications, including using it as a high performance production web server. 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 and in 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 and tutorials about how to write web applications, be sure to read Java Servlet Programming by Jason Hunter with William Crawford (O’Reilly).

x | Preface 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 Tom- cat 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, Getting Started with Tomcat, we explain that. You will then be better able to make informed decisions on choices you might need to make when installing Tomcat, so we spend the 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 should use Tomcat as a standalone web server and servlet container and when it’s best to use Tomcat with the Apache httpd web server. Then, we show you how to configure realms, roles, users, servlet sessions, and JNDI resources, includ- ing 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 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 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, 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 and improve your Tomcat’s performance. We go over adjusting the num- ber of processor Threads, JVM and OS 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, 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. If you already run Apache’s httpd web server and don’t want to change everything all at once, Chapter 5, Integration with the Apache Web Server, covers the use of Tomcat with Apache httpd and talks about the several ways of making Tomcat thrive “in front of” or “behind” an Apache httpd installation.

Preface | xi Whether you’re providing e-commerce, putting up a mailing list, or running a per- sonal site, when you’re connected to the Internet, your site is exposed to 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. Each can be modified to control how Tomcat works. When something goes wrong with your Tomcat or a web application, Chapter 8, Debugging and Troubleshooting, shows you some ways to diagnose the problem. We show you what to look for in the logfiles, how the web browser interacts with Tom- cat’s web server during a request, how to get verbose information about a particular request, and what to do if Tomcat just won’t shut down when you tell it to. Not everyone wants to run a prebuilt binary release of Tomcat, so in Chapter 9, Building Tomcat from Source, we show you how to compile your own Tomcat. We show you step-by-step how to install the Apache Ant build tool, download all neces- sary support libraries, and build your Tomcat. If you’ve got more request traffic than a single Tomcat can handle, or if you want your site to keep serving requests even if one of your servers crashes, your site may need to run on more than one Tomcat server, or more than one Apache, or a combi- nation of the two. Sometimes the only solution is more hardware. In Chapter 10, Tomcat Clustering, we show you some options for running two or more Tomcat serv- let containers in parallel for both fault tolerance and higher scalability, and we dis- cuss the pros and cons of various clustering approaches. In Chapter 11, Final Words, we give an overview of the Tomcat open source project’s community resources, including docs, mailing lists, other web sites, and more. These are valuable resources for solving any problems you may have with future versions of Tomcat, and they can also help you get more involved in the development of Tom- cat if that is one of your goals. 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, Installing Java, we show you step-by-step how to install a Java runtime, and explain some Java issues to watch out for.

xii | Preface Who This Book Is For The book is written for anyone who wants to learn about the Tomcat servlet con- tainer. You do not have to be a programmer to use Tomcat or this book; all of the Java programming is, as mentioned above, tucked away inside servlets or other com- ponents. 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 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 get up to speed quickly on using Tomcat as a web application server during development and in production. Maybe you’re running one of the many Java EE servers that include Tomcat as their web container. For any of these reasons and for any other readers, this book pro- vides an excellent introduction to Tomcat. Conventions Used in This Book The following typographic devices are used: Italic Used for filenames, URLs, Java classes, and for new terms when they are defined. Constant width Used for code examples, XML elements, and commands. constant width bold Indicates user input or lines of particular note in code examples. 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.5. For example, SRV.6.5 refers to Section 6, subsection 5 of the Servlet Specification. Similarly, JSP with a dot- ted 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.

Preface | xiii Using Code Examples This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Tomcat: The Definitive Guide, Second Edi- tion, by Jason Brittain with Ian F. Darwin. Copyright 2008 O’Reilly Media, Inc., 978-0- 596-10106-0.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com. We’d Like to Hear from You Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 800-998-9938 (in the United States or Canada) 707-829-0515 (international or local) 707-829-0104 (fax) We have a web page for this book, where we list errata, examples, and any addi- tional information. You can access this page at: http://www.oreilly.com/catalog/9780596101060 To comment or ask technical questions about this book, send email to: bookquestions@oreilly.com For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our web site at: http://www.oreilly.com There are also web sites for this book by its authors: http://tomcatbook.darwinsys.com http://tomcatbook.brittainweb.org

xiv | Preface Safari® Books Online When you see a Safari® Books Online icon on the cover of your favorite technology book, that means the book is available online through the O’Reilly Network Safari Bookshelf. Safari offers a solution that’s better than e-books. It’s a virtual library that lets you easily search thousands of top tech books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current informa- tion. Try it for free at http://safari.oreilly.com. 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 evolu- tion of Tomcat since its donation to the Apache Software Foundation. A colossal thanks goes to Simon St.Laurent, editor of this Second Edition after Brett McLaughlin, for being patient with me beyond my expectations while I spent the necessary time digging deep to uncover and clearly document the answers through- out the book, and for showing continued confidence. Another big thanks goes to Brett McLaughlin, who edited the First Edition and was the editor of this Second Edition in the early months of the project. Brett made innu- merable minor suggestions to improve the book and several times talked us into reor- ganizing scattered material into the (hopefully) comprehensible form you see before you. Thanks Brett! Paula Ferguson saw the First Edition of the book through the early stages, and then passed the torch to Brett McLaughlin. Thanks Paula! Open source projects are just not the same without a vibrant community surround- ing 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 care- ful reading of the drafts of the First Edition, and suggested many, many improve- ments. Special thanks to you, Jason.

Preface | xv Jason Brittain’s Acknowledgments A big thanks to my wife Carmina, for taking care of the little ones while I wrote, over the course of more than two years. Thanks, Cutie, for all the help you gave me while I wrote this edition of the book, and for being inspirational to me, and now to our children. I love you very much, and I always will! Thanks to James Duncan Davidson and Jason Hunter who together had a strong vision of excellence for the First Edition of this book and worked hard to make that vision a reality. I’d like to personally thank Simon St.Laurent for the help and support for this book. The level of detail and clarity demonstrates how much Simon worked to make sure I had the time to write it that way. Thanks Simon! Thanks also go to Ian Darwin for coauthoring the first edition of the book. He wrote a large amount of helpful and virtually timeless Tomcat content that remains in this Second Edition. The person who directly contributed the most content for the Second Edition of this book (besides Simon St.Laurent, the editor through most of the project), was Akbar Ansari. He provided many screen shots that would have taken me countless addi- tional hours to create, he graphed benchmark data numerous times, proofread some of my text and gave me feedback, and most importantly gave me words of encour- agement as I wrote. Thanks, Akbar, for being so helpful and genuinely interested! Thanks also to Jamie Madden for being the tech reviewer for the Second Edition. Bart Busschots and Jamie Madden both wrote the Mac OS X specific sections of this book—excellent pioneering work guys! Thanks! Also Sebastien Diotte implemented the initial 5.5+ port of BadInputValve, Sean McCauliff gave feedback about textual strangeness in some chapters, and Mike Miller showed me an important FreeBSD ipfilter port remapping rule. Thanks to Mark Petrovic for conversing with me about the SecurityManager and for writing the security policy autodiscovery article; Nicholas Schuetz for creating and maintaining the #tomcat IRC channel on the irc.freenode.net server (it has helped countless Tom- cat users); Philip Morton, Robert Brindamour, and Tom Duggin for fixing a scalabil- ity bug in BadInputValve; William Osmond (I forgot to write in my notes what you helped with, but I know you helped! Thanks!); Fabrice Bellard and others for writ- ing QEMU so that I could run so many different operating systems to write about them; and Jason Gabler for showing me sventon. Thanks to my former co-workers and friends at NASA’s Ames research center, and the NASA Kepler Space Telescope mission (http://kepler.nasa.gov) for allowing me to participate. Eventually, our software will find many new habitable worlds, never before detected by mankind.

xvi | Preface I want to also 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 availabil- ity, load balancing, and fault tolerance back in 1996. Also, to David Jemmett, for- merly 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! I also wish to acknowledge and thank Theron Tison, who is the most thoughtful, unselfish, caring person I had the pleasure of being around while growing up. He was the pillar of stability and confidence that allowed me to reach virtually all of my goals. Thank you, Theron, for helping me through so many tough years. 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 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. I have, over the years, 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. My special warm thanks to Jason for taking over and doing all of the revisions for this Second Edition, when I found I had other fish to fry. An extra big “+1” to you, Jason, for sticking with it to completion despite the needs of your growing family!

1 Chapter 1 CHAPTER 1 Getting Started with Tomcat1 Because Tomcat is written in Java, some people assume that you have to be a Java guru to use it. That is not so! Although you need to know Java to modify the inter- nals of Tomcat or to write your own servlet programs, you do not need to know any Java to use Tomcat or to write or maintain many JavaServer Pages (JSPs). You can have JSPs that use “JavaBeans” or “JSP Custom Tags”; in both cases, you are simply using Java components that a developer has set up for you. In this chapter, we explain how to install Tomcat, get it running, and test it to make sure that it’s functioning properly. As of this writing, there are several production-ready versions of Tom- cat available, but we strongly suggest you use the latest stable version of the 6.0 branch or whichever is the latest stable version of Tomcat by the time you read this. See the Apache Tomcat home page (http://tomcat. apache.org) to find the latest stable version. For Tomcat versions 5.5 and 6.0, this book provides an abundance of answers and explanations about the general concepts of how Tomcat works, in addition to show- ing rich detail about how to use these popular versions of Tomcat. Installing Tomcat There are several paths to getting Tomcat up and running. The quickest one is to download and run the compiled binary. Tomcat is written in Java, which means you need to have a modern and complete Java runtime installed before you can build or test it. Read Appendix A to make sure you have Java installed properly. Do not skip this step; it is more important than it sounds! One of the benefits of open source projects is that programmers find and fix bugs and make improvements to the software. If you’re not a programmer, there is little or nothing to be gained from recompiling Tomcat from its source code, as you are not interested in this level of interaction. Also, if you’re not an experienced Tomcat

2 | Chapter 1: Getting Started with Tomcat developer, attempting to build and use your own Tomcat binaries may actually cause problems because it is relatively easy to build Tomcat in ways that quietly disable important features. To get started quickly, you should download an official release binary package for your system. If you want some hints on compiling from source, see Chapter 9. There are two levels of packaging. The Apache Software Foundation publishes bina- ries in the form of releases and nightly builds. Other organizations rebundle these into RPM packages and other kinds of installers for Linux, “packages” for BSD, and so forth. The best way to install Tomcat depends on your system. We explain the process on several systems: Linux, Solaris, Windows, Mac OS X, and FreeBSD. Tomcat 6 requires any Java runtime version 1.5 or higher (which Sun’s marketing group calls “Java 5”). We suggest that you run Tomcat 6 on Java 1.6 or higher, how- ever, due to the additional features, fixes, and performance improvements that Java 1.6 (or higher) JVMs offer. Installing Tomcat on Linux Tomcat is available in at least two different binary release forms for Linux users to choose from: Multiplatform binary releases You can download, install, and run any of the binary releases of Tomcat from Apache’s web site regardless of the Linux distribution you run. This format comes in the form of gzipped tar archives (tar.gz files) and zip archive files. This allows you to install Tomcat into any directory you choose, and you can install it as any user ID in the system. However, this kind of installation is not tracked by any package manager and will be more difficult to upgrade or uninstall later. Also, it does not come with an init script for integration into the system’s star- tup and shutdown. Distribution native package If you run Fedora or Red Hat Linux (or another Linux that uses the Red Hat package manager, such as SUSE or Mandriva), you can download a binary RPM package of Tomcat. This allows for easy uninstalls and upgrades via the Red Hat Package Manager, plus it installs a Tomcat init script for stopping, starting, and restarting Tomcat from the command line and on reboots. The downside to this method of installation is that you must install the Tomcat RPM package as the root user. As of this writing there are at least two RPM package implementa- tions for you to choose from, each with different features.

Installing Tomcat | 3 Keep in mind, though, that Linux is just the operating system kernel, and the com- plete operating system is a “distribution.” Today, there are many different Linux dis- tributions. Some examples include Fedora, Red Hat, Ubuntu, Mandriva, Gentoo, and Debian. Although any two Linux distributions tend to be similar, there are also usually enough differences that make it difficult for developers to write one script that runs successfully on two. Also, each Linux distribution may primarily use a dif- ferent native package manager, so each version of a distribution can change any number of things in the operating system, including Java* and Tomcat. It is not uncommon for Linux distributions to bundle software written in Java that does not work only because the distribution’s own package of it is broken in a subtle way. Distributions also tend to include old versions of Tomcat that are either unstable or less than ideal to run your web site compared to the latest stable version available. For these reasons, it’s almost always best to install your own recent stable version of Tomcat. Because there are so many Linux distributions, and because they are significantly dif- ferent from each other, giving specific instructions on how best to install Tomcat on each version of each Linux distribution is beyond the scope of this book. Luckily, there is enough similarity between the popular Linux distributions for you to follow more generic Linux installation instructions for installing Tomcat from an Apache binary release archive. If you run a Fedora or Red Hat Linux distribution, more than one implementation of Tomcat RPM packages exists for you to choose from: The Tomcat RPM package that comes with this book This is a fully relocateable RPM package that can be easily rebuilt via a custom ant build file. It does not build Tomcat itself but instead bundles the official mul- tiplatform Apache release class binaries of the Tomcat 6 version of your choice. This RPM package depends on no other RPM packages, so it can be installed as a single package, but needs to be configured to use an installed Java runtime (JDK or JRE). See Appendix E for the full source listing of the RPM package’s scripts. The Tomcat RPM package that is available from JPackage.org This is a nonrelocateable RPM package that installs Tomcat into the /var direc- tory. It rebuilds Tomcat from source code and then packages up the resulting multiplatform class binaries. This RPM package depends on many other RPM packages (each potentially requiring yet more packages) from JPackage.org and must be installed as a graph of RPM packages. As of this writing, JPackage.org does not have a Tomcat 6.0 RPM, only a Tomcat 5.5 RPM. * See Appendix A for more information about how to work around a distribution’s incompatible Java implementation.

4 | Chapter 1: Getting Started with Tomcat Each of these RPM packages includes detailed scripts for installing, uninstalling, and upgrading Tomcat, as well as scripts for runtime integration with the operating sys- tem. We suggest you try ours first. If you run Gentoo Linux, there is an ebuild of Tomcat 6 that you can install and use. See the guide for it by William L. Thomson Jr. at http://www.gentoo.org/proj/en/java/ tomcat6-guide.xml. Also, see the Tomcat Gentoo ebuild page on the Gentoo Wiki at http://gentoo-wiki.com/Tomcat_Gentoo_ebuild. In addition to the ebuild, the RPM package from this book is written to install and run on Gentoo; just install the rpm command first. Installing Tomcat from an Apache multiplatform binary release For security reasons, you should probably create a tomcat user with low privileges and run Tomcat as that user. We suggest setting that user’s login shell to /sbin/ nologin and locking the user’s password so that it can’t be guessed. Also, it’s proba- bly a good idea to make the tomcat user’s primary group the nobody group or another group with similarly low permissions. You will need to do this as the root user: # useradd -g 46 -s /sbin/nologin -d /opt/tomcat/temp tomcat If you do not have root access, you could run Tomcat as your login user, but beware that any security vulnerabilities (which are extremely rare) in Tomcat could be exploited remotely as your user account. Now download a release archive from the Apache binary release page at http:// tomcat.apache.org/download-60.cgi. You should download the latest stable version as listed on the Tomcat home page at http://tomcat.apache.org. Even if you intend to install only a subset of the archive files of the Tomcat version you chose, you should download all of the archive files for that version in case you need them later. The Apache Soft- ware Foundation does archive releases of Tomcat, but you should store your own copies as well. If you are a heavy user of Tomcat, you should probably also download archives of the source code for your release and store your own copies of them as well so that you may investigate any potential bugs you may encounter in the version you’ve chosen. Uncompress the main Tomcat binary release archive. If you downloaded the apache- tomcat-6.0.14.tar.gz archive, for example, uncompress it wherever you want Tom- cat’s files to reside: $ cd $HOME $ tar zxvf apache-tomcat-6.0.14.tar.gz

Installing Tomcat | 5 Before you go any further, you should briefly look at the RELEASE-NOTES text file that resides in the root of your new Tomcat installation. It contains important informa- tion for everyone installing Tomcat and can give you details specific to the version you downloaded. Something else that is very important for you to do before proceeding with the installation is to read the online Tomcat changelog for your branch of Tom- cat. For example, Tomcat 6.0’s online changelog is at http://tomcat.apache.org/ tomcat-6.0-doc/changelog.html. Regardless of the version of Tomcat you install and use, you should look at the bugs listed in the changelog because bugs that exist in your version are fixed in newer versions of Tomcat and will show up in the changelog listed under newer versions. Although Java 1.5.x runtimes work fine with Tomcat 6, it is suggested that you use Java 1.6.x. If you’ll be running Tomcat as user tomcat (or any user other than the one you log in as), you must install the files so that this user may read and write those files. After you have unpacked the archives, you must set the file permissions on the Tomcat files so that the tomcat user has read/write permissions. To do that for a different user account, you’ll need root (superuser) access again. Here’s one way to do that from the shell: # chown -R tomcat apache-tomcat-6.0.14 Tomcat should now be ready to run, although it will not restart on reboots. To learn how to make it run when your server computer boots up, see “Automatic Startup,” later in this chapter. Installing Tomcat from this book’s Linux RPM packages This book contains a production quality example of a Tomcat RPM package for Linux (see Appendix E for the source). It serves as both an elegant way to get Tom- cat installed and running on Linux and as an example of how you may build your own custom Tomcat RPM package. Before you begin, you must install Apache Ant (http://ant.apache.org) version 1.6.2 or higher (but not version 1.6.4—that release was broken), preferably 1.7.x or higher. It must be usable from the shell, like this: # ant -version Apache Ant version 1.7.0 compiled on December 13 2006 You must also have the rpmbuild binary available in your shell. In Fedora and Red Hat distributions, this is part of the RPM package named rpm-build. You must use version 4.2.1 or higher (the 4.2.0 version that is included with Red Hat 9 has a bug that prevents rpmbuild from working properly—but that is becoming antiquated!). Just make sure it’s installed and you can run the rpmbuild command successfully: # rpmbuild --version RPM version 4.3.2

6 | Chapter 1: Getting Started with Tomcat Download this book’s examples archive from http://catalog.oreilly.com/examples/ 9780596101060. Unpack it like this: $ unzip tomcatbook-examples-2.0.zip Change directory into the tomcat-package directory: $ cd tomcatbook-examples/tomcat-package Now, download the binary release archives from the Apache binary releases page at http://tomcat.apache.org/download-60.cgi. You should download the latest stable ver- sion as listed on the Tomcat home page at http://tomcat.apache.org. Download all the tar.gz archive files for the version of Tomcat that you’ve chosen. Move all the Tomcat binary release archive files into the tomcatbook-examples/ tomcat-package/ directory so they can be included in the RPM package set you’re about to build: # cp apache-tomcat-6.0.14*.tar.gz tomcatbook-examples/tomcat-package/ Edit the conf/tomcat-env.sh file to match the setup of the machines where you’ll deploy your Tomcat RPM packages. At the minimum, you should make sure that JAVA_HOME is an absolute filesystem path to a Java 1.5 or 1.6 compliant virtual machine (either a JDK or a JRE). Then, invoke ant to build your Tomcat 6 RPM package set: $ ant This should build the Tomcat RPM packages, and when the build is complete, you will find them in the dist/ directory: # ls dist/ tomcat-6.0.14-0.noarch.rpm tomcat-6.0.14-0-src.tar.gz tomcat-6.0.14-0.src.rpm tomcat-6.0.14-0.tar.gz The Tomcat RPM package builder also builds a Tomcat source RPM package,* plus a tar.gz archive of the RPM package as a convenience. Copy the RPM package to the machine(s) you wish to install it on. When you’re ready to install it, you have two choices: • Install it into its default path of /opt/tomcat. • Install it, relocating it to a path of your choice. Here’s how to install it to the default path: * Think of this source RPM package as the content necessary to build the binary RPM package, not necessarily the Java source code to Tomcat itself. This book’s Tomcat RPM package was built using the officially com- piled Tomcat class files, so the Java source isn’t included in the source RPM package, nor is it necessary to build the multiplatform “binary” RPM package.

Installing Tomcat | 7 # rpm -ivh tomcat-6.0.14-0.noarch.rpm Preparing... ########################################### [100%] 1:tomcat ########################################### [100%] The following error: error: Failed dependencies: /bin/sh is needed by tomcat-6.0.14-0.noarch usually occurs on operating systems that do not primarily use the RPM package manager, and you are installing this Tomcat RPM package when the RPM package manager’s database is empty (no package in the database provides the /bin/sh inter- preter). This may happen, for example, if you are installing the Tomcat RPM pack- age on a Debian Linux OS after installing the rpm command. Try to install it again like this: # rpm -ivh --nodeps tomcat-6.0.14-0.noarch.rpm If you get warnings such as these about users and groups: warning: user tomcat does not exist - using root warning: group nobody does not exist - using root you need to add a tomcat user and nobody group by hand using adduser and addgroup. Just make sure that the tomcat user’s primary group is nobody. Also, make sure that you set user tomcat’s home directory to “/opt/tomcat/temp,” and set tomcat’s login shell to something that doesn’t actually work, such as /sbin/nologin if you have that: # groupadd nobody # useradd -s /sbin/nologin -d /opt/tomcat/temp -c 'Tomcat User' \ -g nobody tomcat Once you are done with this, try again to install the tomcat package: # rpm -e tomcat # rpm -ivh --nodeps tomcat-6.0.14-0.noarch.rpm Once it’s installed, just verify that the JAVA_HOME path set in /opt/tomcat/conf/ tomcat-env.sh points to the 1.5 or 1.6 JVM that you want it to. That’s it! Tomcat should be ready to run. With these same RPM packages, you can install Tomcat and relocate it to a different filesystem path, like this: # rpm -ivh --prefix /usr/local tomcat-6.0.14-0.noarch.rpm This would install Tomcat, relocating it so that CATALINA_HOME becomes /usr/ local/tomcat. You may install the admin and compat packages this way as well. As of this writing, JPackage.org does not offer a Tomcat 6 RPM pack- age, but instead offers a Tomcat 5.5 RPM package.