Configuring Tomcat 8

This, the second in a series of blogs on Tomcat, including basic set-up and clustering, configuration and finally performance tuning and monitoring.

PART 1   |   PART 2   |   PART 3

Following on from Mike's first post in this series (How to Set Up a Cluster with Tomcat 8, Apache and Mod_JK), which looked at basic set-up and clustering, this post will examine some basic configuration settings and the key things most people want to configure. I'll use the same system set up as Mike, so if you wish to follow along, then set up your system as described there.

Tomcat is designed to work out of the box, with very little change required to the default values. However, when you do need to make changes to the way it's configured, where should you start?

Well, all the key config files can be found in the conf directory underneath the main Tomcat directory, and some of the most important ones are:

  • server.xml - This is the main config file for Tomcat and contains the settings for most of the key Tomcat components.
  • context.xml - This is a global config file used by all web apps running on Tomcat. If you wish to override the global settings you should create your own context.xml file and place it in the META-INF directory of your web app.
  • web.xml - This is the global deployment descriptor used by all web apps running on Tomcat. If you wish to override the global settings you should create your own web.xml file and place it in the WEB-INF directory of your web app.
  • tomcat-users.xml - This file contains details on users and their roles

If you look into these files, you'll see they are well documented, with details of what each setting does.

So, let's start configuring our servers!

It's highly recommended to make backup copies of any config files before making changes. It should also be noted that if you have your servers set up from the previous post, when making config changes you should make the changes to both servers or you may see some odd results!

Changing the default home page

Firstly, if you have things set up as described in the first post and you point a browser at your server, you will see the default Tomcat page - which also provides documentation for Tomcat.
In order to change this you need to remove the contents of <TOMCAT_DIR>/webapps/ROOT and create your own front page called index.html, index.htm or index.jsp in this directory.

Creating an admin user and accessing the management interface

Tomcat comes with a management web application available at http://localhost/manager. However, if you point your browser at it, you will find that by default it is locked down. So, let's fix that now.

To enable access you must either create a new username/password combination and associate one of the manager roles with it, or add a manager role to some existing username/password combination.

The following roles are available:

  • manager-gui — Gives the user access to the HTML interface
  • manager-status — Gives the user access to the Server Status page only
  • manager-script — Gives the user access to a plain text interface and the Server Status page
  • manager-jmx — Gives the user access to the JMX interface and to the Server Status page

Here we will add a user to access the HTML interface. We will do this by adding a user to the tomcat users file. This file contains an XML element <user> for each individual user.

Here we will add a new user with the manager-gui role as follows:

<role rolename="manager-gui" /> 
<user name="admin" password="admin" roles="manager-gui" />

This defines the username and password used by this individual to log on, and the role names he or she is associated with

Usernames and passwords can also be stored in a database or in a directory server accessed via LDAP.

If you now point your browser at localhost/manager you should be able to access the management interface with the username and password set in the users file.

The management console is very basic and only has a limited set of features but it will allow you to do the following:

  • Deploy new web apps
  • List the currently deployed apps
  • Start and stop your apps
  • Reload an app
  • Undeploy an app
  • List the OS and JVM properties
  • List JNDI resources
Locking admin access to the local machine

If you have another machine (or virtual machine) you can access the admin interface from it, as can others. So, next up we will lock access down so that access can only be gained from the machine running Tomcat.

Edit <TOMCAT_DIR>/webapps/manager/META-INF/context.xml.

Uncomment the following section:

  <Valve className="org.apache.catalina.valves.RemoteAddrValve"
         allow="127.d+.d+.d+|::1|0:0:0:0:0:0:0:1" />
Configuring a datasource

Next, we will configure a mySQL datasource, and so we need to install mySQL

Firstly we need to install mysql. As I'm using Ubuntu we can use the package manager to do so with the following:

sudo apt-get install mysql-server

You will be prompted for a root password. For test purposes I'm going to use admin.

Next up we need to download the JDBC driver for connecting to our database. This can be downloaded from here:

Extract the zip file to a folder of your choice. In that folder you will find the necessary jar file. In my case this was mysql-connector-java-5.1.30-bin.jar.

Copy this file to <TOMCAT_DIR>/lib.

Next, we will create a test database.

Open up a terminal and run the following command:

mysql -u root -p

You will be prompted for the root password (admin on my test server).

Now we will create a new database, create a test table and add some dummy data.

create database testdb;
use testdb;

create table test_table (id int not null auto_increment primary key, name varchar(20));

insert into test_table (name) values("Tom");
insert into test_table (name) values("Dick");
insert into test_table (name) values("Harry");

Configuring the datasource

Finally, we will configure our data source. If we configure our datasource in the main config.xml it will be available to all our apps. However, this should generally be avoided as it will create a pool for each context deployed, and you will have a very unhappy DBA if you have multiple apps deployed but only one actually needs to access the database!

Therefore we will configure our datasource in our applications config.xml.

Under your <TOMCAT_DIR>/webapps directory, create a new folder called dbtest.

Under this folder create a new META-INF directory.

Within that folder create a context.xml file with the following text:

<Resource name="jdbc/testdb" auth="Container" type="javax.sql.DataSource"
               maxActive="-1" maxIdle="100" maxWait="5000"
               username="root" password="admin" driverClassName="com.mysql.jdbc.Driver"

OK. So we have configured our datasource. Next up we will create a very basic app to test it. We will then expand this app in later steps to show further configuration.

Creating a test app

Now our datasource is configured and we have some dummy data in a database let's create a test app to see if it works. Under the dbtest folder create the following structure:

----> WEB-INF
----> WEB-INF/lib

In order to keep things simple we will use Apache's Standard Taglibs. They can be downloaded from here:

Download the 1.1 version, unzip it to a directory of your choosing and then from the lib directory within that directory copy jstl.jar and standard.jar to the following directory:


This will give your app access to the necessary libraries.

Next, we will create a basic jsp page that retrieves the dummy data we put in the database and displays it.

Create a file called test.jsp under <TOMCAT_DIR>/webapps/dbtest/ and enter the following:

<%@ taglib uri="" prefix="sql" %>
<%@ taglib uri="" prefix="c" %>

<sql:query var="rs" dataSource="jdbc/testdb">
select id, name from test_table

    <title>DB Test</title>


<c:forEach var="row" items="${rs.rows}">
    ID ${}<br/>
    Name ${}<br/>

This should be fairly simple to follow. All it does is uses the sql taglib to retrieve the data we want and then the core taglib to loop through that data displaying the results. The implementation isn't that important right now, we just want to test that we can access our data source.

If you now point your browser at http://localhost/dbtest/test.jsp you should see the following:


ID 1
Name Tom
ID 2
Name Dick
ID 3
Name Harry
Error Handling

Finally I'm going to take a look at error handling.

First of all, let's create a page that we know will throw an error and add it to our previous app.

Create a new file called error.jsp under <TOMCAT_DIR>/webapps/dbtest.

Add the following text:

   <title>Error Handling Example</title>
   // Throw an exception to invoke the error page
   int x = 1;
   if (x == 1)
      throw new RuntimeException("Something went wrong!");

Now point your browser at http:// localhost/dbtes/error.jsp

You will see the full stack trace and details on the error.

The default error pages that Tomcat uses often include information about your server that you don't want others to see (file paths, configuration information, stack traces etc.). These can be very useful in development, but not when your system goes live. Therefore we want to create our own error pages.

Now point your browser at http://localhost/dbtest/x.jsp

Here you will see the standard 404 - page not found error.

You can either set error pages in the main web.xml or in your app's web.xml depending if you want different error pages for different apps.

In my case I'm going to alter them for my individual app.

Create a new web.xml file in <TOMCAT_DIR>/webapps/dbtest/WEB-INF and enter the following:

<web-app xmlns=""



This tells Tomcat that all 500 errors (Internal Server Error) should be redirected to the page 500_error.html in the errors directory of your app and that all 404 errors (Page Not Found) should be redirected to the page 404_error, also in the errors directory of your app.

Note - you can also do the following if you wish to capture specific Java exceptions:


Now create 500_error.html and 404_error.html pages in: <TOMCAT_DIR>/webapps/dbtest/errors

Now if you go to: http://localhost/dbtest/error.jsp


http://localhost/dbtest/x.jsp should see your own personalised error pages rather than the default ones.


Well, that concludes this brief look into configuring Tomcat. Hopefully I've covered enough to give you some ideas about configuring your own servers and shown that the basics are pretty straightforward.
In the final part of this series, Dave Winters will look at performance tuning and monitoring.