Meet Tomcat Catalina
Apache Tomcat is a widely used implementation of the Java Servlet Specification, which has been developed as an open-source project by the Apache Software Foundation since 1999, when the project source was donated to the ASF by Sun Microsystems.
Tomcat is actually composed of a number of components, including a Tomcat JSP engine and a variety of different connectors, but its core component is called Catalina. Catalina provides Tomcat's actual implementation of the servlet specification; when you start up your Tomcat server, you're actually starting Catalina.
In this article, we'll get to know Tomcat's core component, from the origins of the name "Catalina", to an overview of how Catalina is configured. We'll also look at some Catalina-related tips and tricks, such as how to get the most out of Catalina's built-in logging functionality, and how to manage the Catalina class as an MBean using JMX.
Tired of wading through hundreds of lines of XML just to make a simple change to your Tomcat configuration? Tcat makes Tomcat configuration simple. Create optimized configuration profiles, save them, and apply them to groups of servers with a single click.
How Did Catalina Get Its Name?
There's nothing like an Apache product name to raise an eyebrow - the Apache volunteers have a knack for turning out oddly named technologies that's only rivaled by Ubuntu's "adjective-animal" naming format.
The name "Catalina," according to Craig McClanahan, who designed the original architecture of the servlet container, can be attributed to three things: his love for Catalina Island (despite never having visited it), his cat's habit of hanging around the computer while he was writing the code, and the consideration, at an early stage of development, of building Tomcat on a server framework called Avalon, which is the name of a town on Catalina island.
The Avalon framework was eventually abandoned, but the name stuck, and the rest is history.
Catalina's Configuration Files
Catalina's default behavior can be directly configured by editing the six configuration files located in Tomcat's "$CATALINA_BASE/conf" directory. Here's an overview of the files located in this directory and the kinds of options that can be configured within each.
This file contains the Tomcat security policy for the Catalina Java class, expressed in standard Security Policy syntax, as defined in the JEE specification. This is Tomcat's core security policy, and includes permissions definitions for system code, web applications, and Catalina itself.
This file is a standard Java properties file for the Catalina class. It contains information such as security package lists and class loader paths. This file can also contains some String cache settings, that you might edit when tuning your server for best Tomcat performance.
This file configures the way that Catalina's built-in logging functions, including things such as threshold and log location. Note that all the entries in this log refer to JULI, the modified commons-logging implementation that Tomcat automatically uses in place of your JDK's logging implementation.
This XML configuration file is used to define Tomcat Context information that will be loaded for every web application running on a given instance of Tomcat. In general, you should configure your Context information elsewhere, but there are a few entries in this file that can be uncommented to alter the way that Tomcat handles session persistence and Comet connections.
This is Tomcat's main configuration file, which uses the hierarchical syntax specified in the Java Servlet specification to configure Catalina's initial state, as well as define the order in which Tomcat boots and builds its various components. This file is quite complex, but comprehensive documentation is available on the Apache website.
This file contains information about the various users, passwords, and user roles on a given Tomcat server, as well as information about trusted Realms (JNDI, JDBC, etc.) where this data can be accessed.
This file configures options and values that will be applied to all applications loaded into a given instance of Tomcat, including servlet definitions such as buffer sizes, debugging levels, Jasper options like classpath, MIME types, and default welcome files for directories that do not have their own "index" files. Although you can technically configure options for specific web applications in this file, this will require you to restart your entire server to propagate these changes, so it is not recommended.
If you need more information about configuring Catalina, check out our Tomcat Configuration page!
A common question asked by Tomcat beginners is how to rotate the Catalina.out log file, without restarting Tomcat. (If you're not familiar with the file, Catalina.out is the standard destination log file for System.out and System.err, JVM loggers that print information about fatal errors in the JVM.)
There are two answers.
The first, which is more direct, is that you can rotate Catalina.out by adding a simple pipe to the log rotation tool of your choice in Catalina's startup shell script. This will look something like:
"$CATALINA_BASE"/logs/catalina.out WeaponOfChoice 2>&1 &
Simply replace "WeaponOfChoice" with your favorite log rotation tool.
The second answer is less direct, but ultimately better. The best way to handle the rotation of Catalina.out is to make sure it never needs to rotate. Simply set the "swallowOutput" property to true for all Contexts in "server.xml".
This will route System.err and System.out to whatever Logging implementation you have configured, or JULI, if you haven't configured it. All commons-logger implementations rotate logs by default, so rotating Catalina.out is no longer your problem.
For more information about JULI, Log4J, and Tomcat logging in general, check out our easy-to-follow guide to Tomcat Logging.
Managing Catalina as an MBean
Because Catalina is a Java class, if you enable Java Management Extensions (JMX) management, you can actually manage all of Catalina's exposed functions as a single MBean, and reference all its hierarchical elements by name. Apache maintains a list of all the MBean names as part of the Tomcat documentation.
In order to begin managing Catalina as an MBean, all you need to do is modify the CATALINA_OPTS system variable to allow JMX access.
For a comprehensive, step by step guide to enabling and using JMX with Catalina, check out our guide to Tomcat JMX!
Learn More About Catalina
If you want to learn more about the Catalina servlet container, there are a number of resources you can consult. Here are some of our favorite Tomcat Catalina resources:
Understanding Apache Tomcat - MuleSoft's comprehensive guide to Apache Tomcat, including FAQs, HOW-TO's, whitepapers, and more.
The Tomcat API - Apache's documentation of the Tomcat API, with detailed information about each package and its contained elements.
The Java Servlet Specification - Information on the Servlet specification that Catalina implements.
The Tomcat Mailing Lists - User and Developer Discussions about Tomcat-related topics hosted on the Apache Website.