Tomcat Administrator Cheatsheet

by Steven J. Owens (unless otherwise attributed)

Although -- of course -- it's better to truly understand what a server application is about, from the point of view of a sysadmin who mostly dealing with apps like Tomcat from the outside, there are a set of key details that tend to be buried in and spread out across various docs.

This cheat sheet is an attempt to summarize these key details and make it easier for you to use other documentation. It's not a replacement for the jarkarta Tomcat documentation, or even better, Jason Brittain's Tomcat: The Definitive Guide, 2nd Ediition from O'Reilly.

In a separate tutorial, I describe each specific area or topic, and give links to more in-depth resources:

http://darksleep.com/notablog/articles/Tomcat_Admin_Jumpstart

I have these ordered "from the outside in", i.e. first the downloads/installs you'll need, second the environment variables, then internal directories, ports used, etc.

Note: Someday I need to update this cheatsheet to describe the differences between standard tomcat and the debian/ubuntu tomcats. Until then, check out the jumpstart version, which has links to some useful pages about ubuntu and debian.

Cheat Sheet

• Major Steps
  • download and install the JDK
  • download and install Tomcat (6.0.24 or later, important!, see What Version)
  • download and install the appropriate JDBC driver for your database
  • adjust any port settings (if the default ports aren't available) in tomcat/server.xml
  • edit tomcat/conf/server.xml to close the shutdown port, 8005 (see Standard HTTP/HTTPS ports and Root Permissions, below)
  • configure init scripts to make sure tomcat gets restarted when the linux box is restarted
  • configure apache mod_proxy_ajp to connect apache to tomcat (if you want to limit your scalability)
  • create a manager user by editing tomcat/tomcat-users.xml
  • deploy a webapp into tomcat/webapps
  • create a user for your webapp in your chosen database server
  • configure your webapp's database access in tomcat/conf/Catalina/localhost/webappname.xml and tomcat/webapp/webappname/WEB-INF/web.xml
  • adjust java settings (e.g. memory allocation) if necessary by setting JAVA_OPTS in your init script or in tomcat/bin/catalina.sh
  • adjust the system ulimit setting (open file handles limit) if necessary
  • troubleshoot (check log files in tomcat/logs for errors, check netstat -nlp for port conflicts, etc)
• Components You Will Probably Have To Download, Install Or Configure
  • tomcat 6.0.24 or later (important!, see What Version)
  • the java JDK (JRE alone is usually insufficient)
  • apache mod_proxy_ajp (not recommended for performance)
  • init scripts for system restart (don't use the standard scripts, use Jason Brittain's init scripts
  • JDBC driver jar file specific to your database server
• Environment Variables
  • JAVA_HOME, JDK installation directory, you set this or your package installer sets this
  • CATALINA_HOME, tomcat installation directory, usually set by the init script or startup script (tomcat/bin/catalina.sh), which assumes it is contained by the appropriate directory.
  • CATALINA_BASE, almost always identical to CATALINA_HOME, usually set by the init script or startup script (tomcat/bin/catalina.sh), as above.
  • JAVA_OPTS, command-line options for starting the JVM, usually set by the init script or startup script (tomcat/bin/catalina.sh)
    • use -Xms to set initial memory allocation
    • use -Xmx to set max memory allocation
    • example, to set both to 512 megabytes: $ export JAVA_OPTS = "-Xmx512m -Xms512m"
  • also, check on your system's kernel setting for ulimit, max number of open file handles
• Tomcat Directories
  • tomcat/bin, various useful scripts, see Scripts In tomcat/bin, below.
  • tomcat/conf, tomcat server-wide config files, see Config Files In Tomcat, below.
  • tomcat/webapps, where the webapps live, including the webapp config file in tomcat/webapps/webappname/WEB-INF/web.xml (see "config files in tomcat you usually mess with", below).
  • tomcat/logs, where tomcat writes its log files to
  • tomcat/temp, what javax.servlet.context.tempdir points to, servlet-spec specific version of java.io.tmpdir, where tomcat writes temporary files created by webapps
  • tomcat/work, temporary files created by tomcat for its own use (most java source files created for JSPs by the JASPER compiler)
• Ports Tomcat Uses
  • 8080, HTTP
  • 8443, HTTPS
  • 8005, shutdown service (disable this, see Standard HTTP/HTTPS ports and Root Permissions, below)
  • 8009, AJP connector, tomcat's half of mod_proxy_ajp, (not recommended for performance)
  • use netstat -nlp to check for other processes using these ports
  • edit ports in tomcat/conf/server.xml Server/Service/Connector tags
    • except for shutdown port, in tomcat/conf/server.xml Server tag
    • disable shutdown port (set to "-1"), use kill -15 instead
  • to run tomcat on port 80 as not-root-user, use ip tables to forward port 80 to 8080
  • for more running tomcat on port 80, see Jason Brittain's blog
• Scripts In tomcat/bin
  • tomcat/bin/catalina.sh does the real work
  • tomcat/bin/startup.sh to start tomcat, invokes catalina.sh
  • tomcat/bin/shutdown.sh to stop tomcat, invokes catalina.sh
  • tomcat/bin/version.sh to list tomcat-specific environment variables and version numbers, invokes catalina.sh
• Logs In tomcat/logs
  • typically date-stamped, rolled over each time restarted
  • STDOUT (main tomcat server stuff) in tomcat/logs/catalina.out
  • rollover STDOUT logs in tomcat/logs/catalina.yyyy-mm-dd.log
  • individual webapps in tomcat/logs/webappname.yyyy-mm-dd.log
• Config Files In Tomcat (mostly in tomcat/conf) you usually do mess with
  • tomcat/conf/server.xml, controls tomcat server-level stuff, like ports
  • tomcat/conf/tomcat-users.xml, edit to insert users for tomcat manager app
  • tomcat/webapps/webappname/WEB-INF/web.xml, webapp-internal configs for a specific webapp
  • tomcat/conf/Catalina/localhost/webappname.xml, server-level configs for a specific webapp
  • auto-created when tomcat is started, using tomcat/webapps/webappname/META-INF/context.xml if present, else default context values in tomcat/conf/context.xml
• Config Files In tomcat/conf you usually don't mess with
  • tomcat/conf/context.xml, default values for server-level webapp configs, seldom changed, overridden by webapp-specific context xml file (see above)
  • tomcat/conf/web.xml, default values for webapp configs, seldom changed, overridden by webapp-specific web.xml file (see above)
  • tomcat/conf/logging.properties, controls tomcat logging details, seldom changed
  • tomcat/conf/catalina.properties, tomcat internal classloader configs, don't mess with it.
  • tomcat/conf/catalina.policy, tomcat internal security policy, don't mess with it.
• Tomcat's Preinstalled (default) Webapps In tomcat/webapps
  • tomcat/webapps/ROOT at http://localhost:8080/ is the default webapp, serves stuff at root URL
  • tomcat/webapps/examples at http://localhost:8080/examples is the example code
  • tomcat/webapps/manager at http://localhost:8080/manager is a web UI for deploying webapps into your tomcat installation
    • must add user tag to tomcat/conf/tomcat-users.xml before you can log into tomcat manager app
    • insert into end of tomcat-users.xml:

      
        <user name="yourmanageruser" password="yoursecretpassword" roles="standard,manager" />

  • tomcat/webapps/host-manager at http://localhost:8080/host-manager is a web UI for configuring virtual hosts
  • tomcat/webapps/docs at http://localhost:8080/docs/ is a local copy of the tomcat docs
• Webapp
  • a specification-defined hierarchy of directories and files
    • tomcat/webapps/webappname/ is where web-served assets (pages, images, etc) go
    • tomcat/webapps/webappname/WEB-INF/web.xml is the config file for the webapp
    • tomcat/webapps/webappname/WEB-INF/lib/ is where any webapp-specific jar files go
    • tomcat/webapps/webappname/WEB-INF/classes/ is where compiled java class files for webapp go (but general practice is to jar them up and put them in lib, instead)
  • a WAR file is a jarred webapp plus some config files
  • deploy with manager app web UI
  • or autodeploy by copying webapp or WAR file into tomcat/webapps and the rest happens automatically
    • autodeploy is enabled by tomcat/conf/server.xml, Server/Service/Engine/Host tag, attribute autoDeploy="true"
    • or by tomcat/conf/server.xml, Server/Service/Engine/Host tag, attribute deployOnStartup="true"

The End

For more in-depth info on the above, check out

http://darksleep.com/notablog/articles/Tomcat_Admin_Jumpstart

Feedback

Verification Image:
Subject:
Your Email Address:
Confirm Address:
Please Post:
Copyright: By checking the "Please Post" checkbox you agree to having your feedback posted on notablog if the administrator decides it is appropriate content, and grant compilation copyright rights to the administrator. Message Content: