1. Introduction
In this example we will talk about Apache Tomcat Servlet/JSP container also referred to as Tomcat server and the file that provides different options to configure Tomcat. Apache Tomcat is developed as an open source software and is available under Apache License version 2.
Apache Tomcat is a light server that is aimed at performance rather than extensive functionality coverage, and therefore it is used by many large-scale web applications that require speed and ease of configuration and deployment. Tomcat server is not only popular because of its performance, but also because of its ease of set-up and configuration. Tomcat supports server and web application level configuration. Such flexibility allows fine tuning of the server performance, and security. The main purpose of using Tomcat is as a platform for developing and deploying web applications and web services.
2. Background
There are many versions of the Tomcat server. In this example we will talk about Apache Tomcat Servlet/JSP container version 8.0.20 that implements the Servlet 3.1 and JavaServer Pages 2.3 specifications. In this example 64-bit Windows 7 Professional SP1 was used. JDK 7 for Windows 7 64-bit was installed and configured.
Note that in this article we use Windows specific directory path separator “\”, which is different from the one used on Linux like systems. Below are critical directories for the Tomcat:
- (known as , where catalina is the project name of the Tomcat server) is the directory where you have placed Apache Tomcat folder, e.g. in our example. In addition, Tomcat server can be configured for multiple instances by defining for each instance of the Tomcat server. By default both folders refer to the single Tomcat server installation.
- is the directory, where server startup, shutdown, and other scripts are located.
- is the directory that contains configuration files and related to those files DTDs (Document Type Definition). The files in this folder are used for the server level performance tuning, security, load balancing, etc. We will talk about configuration file located in this folder.
- is the directory, where the log files are stored by default.
- is the directory, where the webapps you place in the server are stored.
All Tomcat server related configurations from above folders are read at the server’s start-up. Thus, if you change any of the Tomcat server’s configuration files, you need to restart the server. Also note that the configurations discussed in this article are mainly applicable to Tomcat 8, but may not be applicable to earlier or later versions. Please refer to the official documentation here for the version you want to install.
deployment descriptor configuration file, which is one of the main configuration files for the Tomcat server. It is located in the folder. This configuration file is used for basic web application’s configuration shared by all web applications that will be deployed on the Tomcat server instance. Each of the web application may optionally override shared configurations by defining their own file located in folder. Note that web application specific configurations should NEVER be placed in the shared . Describing options for the per web application configuration file is outside of the scope of this article, but you can read more about it
From now on, whenever we say here.
, we refer to the Tomcat server’s located in the and shared by all web applications deployed on that server. Note that the ordering of the configuration elements in the server’s must be followed as specified by the Java Servlet 3.1. Read more about Java Servlet 3.1 3. Tomcat Server Installation
In this example we will install Tomcat 8 on the Windows 7 Professional 64-bit system, which has JDK 7 installed. If you need a refresher on how to set up JDK 7 on Windows 7 please refer here.
Once you checked that you have JDK 7 setup, get Tomcat server distribution package from the Apache Tomcat’s official website. As of writing of this article the latest version of Tomcat server is Tomcat 8 and it is available from here. The Tomcat distribution used in this example is a zip of the binary core for 64-bit Windows.
We will not discuss in details installation steps for Tomcat, but you can refer to the Apache Tomcat server’s official installation howto here on how to setup the Tomcat 8.
Assuming you have installed Tomcat, let’s look at how to verify if it is working.
To run Tomcat server on Windows you need to configure it as a Windows service. This needs to be done each time you restart your computer. To manually start Tomcat you need to open Windows’s command line prompt by searching for cmd in the start-up menu. Then, in the command line prompt navigate to
folder and run “service.bat”script with “install” option. Below is the screen shot of running service.bat install.
Note: you must have administrative privileges to run Tomcat server from the command line prompt. To verify that the Tomcat 8 is running on the Windows type tomcat8 command into the open command line prompt. It will open a new command line window with Tomcat startup information as shown in the picture below.
4. Using Tomcat Server Management App
We can verify that the Tomcat server was installed and configured correctly in several ways. One of the ways is by using manager web application provided by default with Tomcat. To access the manager web app several steps need to be performed. First, verify that the Tomcat was registered with Windows as a service as explained in previous section. Then, add a user and a role elements in the
configuration file as shown below:
1
2
3
4
| < tomcat-users xmlns = http ://tomcat.apache.org/xml xmlns:xsi = http ://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation = http ://tomcat.apache.org/xml tomcat-users.xsd version = "1.0" > < role rolename = "manager-gui" /> < user username = "tomcat" password = "tomcat" roles = "manager-gui" /> </ tomcat-users > |
The above entry in the
allows access to the manager web app provided by default with each Tomcat instance. The user name and the password in the example could be any legal value. Once you have added above entry in the configuration file, restart the Tomcat server by closing the status command line prompt, and starting it again with tomcat8 command as explained earlier.
Read more on how to configure and run manager web application here.
Once you setup the user name and password and started Tomcat service you can open the following URL in the web-browser of your choice
. The screenshot of the web page is below:
The screenshot above was taken from the web page opened in Google Chrome browser version 41.0.X. The above URL contains basic information on Tomcat’s version, OS it runs on, and JVM properties. Note in the screenshot that the initial maximum heap-memory size is relatively small. It is generally recommended to increase that limit to a higher value depending on your system capabilities and expected requirements of the web applications that will be hosted. Read more on Tomcat’s heap-memory settings here.
5. Tomcat server’s web.xml configuration file
Up to this point, we have registered Tomcat as a Windows service, and now we are ready to look at
configuration file located in folder. Below is the with no options:
1
2
3
4
5
6
7
8
| <? xml version = "1.0" encoding = "ISO-8859-1" ?> xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee version = "3.1" > … </ web-app > |
The above simplified
contains element which will contain options for operating all web applications deployed in this Tomcat instance. The element represents the configuration options for a web application. It is required that all deployment descriptors must confirm to XML schema for the Servlet 3.1. is the root element for the deployment descriptor, file.5.1. Configuring Shared DataSource configuration using JNDI DataSource
In this section, configuration of the shared data source across all web applications is described. Note that per web application data source configuration is also possible and is a common choice for small projects. In this section, we will look at adding MySQL data source. Note that you are expected to be familiar with Context, context configured per web application running within a Tomcat server, and Host, host configured per Tomcat instance in the file, configurations.
Get the
and add it to the library of the shared resource located in the folder. In our case we copy (the official JDBC Driver) jar into the folder.
Perform MySQL server configuration as described in here section “1. MySQL configuration”.
Next perform Context configurations as described in here section “2. Context configuration”.
Next configure
as shown below:
1
2
3
4
5
6
| < resource-ref > < description >MySQL Datasource example</ description > < res-ref-name >jdbc/TestDB</ res-ref-name > < res-type >javax.sql.DataSource</ res-type > < res-auth >Container</ res-auth > </ resource-ref > |
Note that it is expected that resource with name “
” was configured in the Context. element represents the resource manager connection factory reference, such as JDBC DataSource. The sub elements of the represent the following:- is a description of this resource reference
- is a JNDI name and must be unique within deployment environment, e.g. web application.
- here is the type of the data source . This type is expected to be implemented by the data source. For the example data source read more
- specifies if the deployment component code signs on programmatically to the resource manager, or if the container will sign on to the resource manager for the deployment component. In the latter, the container needs information to sign on from the web application.
For more extended list for different database configurations refer here.
5.2. Configuring Jasper 2 Java Server Pages (JSP) Engine
Tomcat 8.0 implements JavaServer Pages 2.3 specification with Jasper 2 JSP engine. This version of the JSP engine was redesigned for better performance compared to the previous version. An extended list of parameters and their purpose could be found here.
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
| < servlet > < servlet-name >jsp</ servlet-name > < servlet-class >org.apache.jasper.servlet.JspServlet</ servlet-class > < init-param > < param-name >fork</ param-name > < param-value >false</ param-value > </ init-param > < init-param > < param-name >xpoweredBy</ param-name > < param-value >false</ param-value > </ init-param > < load-on-startup >3</ load-on-startup > </ servlet > … < servlet-mapping > < servlet-name >jsp</ servlet-name > < url-pattern >*.jsp</ url-pattern > < url-pattern >*.jspx</ url-pattern > </ servlet-mapping > |
The above
element is a small Java program that runs with a Tomcat server. A servlet receives and responds requests from the Web clients. The JSP compiler servlet is the mechanism used by Tomcat server to support JSP pages. Below is explanation for sub elements:- must be unique within web application
- here read more on org.apache.jasper.servlet.JspServlet
- option tells Ant not to fork compiles of JSP pages, but to compile them on the JVM that Tomcat is running on (default is true)
- option disables adding X-Powered-By response header by generated servlet (default is false)
- with value 3 means this servlet will be loaded after servlets with a lower value
- is the pattern for which any matched URL request will be serviced by this servlet
JSP servlet’s options may be used for optimization of Tomcat server request processing. One of such optimizations could be settings development option to false, which will disable on access checks for JSP page’s compilation. To see the full list of options go here.
5.3. Configuring SSI (Server Side Includes)
SSI are directives that are placed within HTML tags and evaluated on the server during page processing. SSI allows you adding dynamically generated content to the HTML pages without the need to serve the whole HTML page. SSI support on Tomcat is available as both a servlet and a filter. Only one of two SSI types should be used.
By default SSI support is disabled on Tomcat. You can read more about this here. Note that SSI directives could be used to execute external to Tomcat JVM programs, which may result in the security vulnerability to your Tomcat instance.
option
To use SSI look for SSI filter or SSI servlet in the default
in . Read comments and uncomment appropriate sections of the configuration file to enable SSI.5.4. Configuring CGI (Common Gateway Interface)
CGI defines a way for a web server to interact with external content-generating programs that conform to the CGI spec requirements.
By default SSI support is disabled on Tomcat. You can read more about this here. Note that CGI scripts could be used to execute external to Tomcat JVM programs, which may result in the security vulnerability to your Tomcat instance.
option
To use CGI look for CGI servlet and servlet-mapping elements in the default
in . Read comments and uncomment appropriate sections of the configuration file to enable CGI servlet.5.5. Configuring Default Servlet
Default servlet serves static resources and directory listing (if directory listing is enabled). It is declared in
and it is defined on all Tomcat instances. Below is an entry for the Default Servlet:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
| < servlet > < servlet-name >default</ servlet-name > < servlet-class > org.apache.catalina.servlets.DefaultServlet </ servlet-class > < init-param > < param-name >debug</ param-name > < param-value >0</ param-value > </ init-param > < init-param > < param-name >listings</ param-name > < param-value >false</ param-value > </ init-param > < load-on-startup >1</ load-on-startup > </ servlet > ... < servlet-mapping > < servlet-name >default</ servlet-name > < url-pattern >/</ url-pattern > </ servlet-mapping > |
A description of each of the sub elements in the build in default
element is below:- is the canonical name of this servlet. The name must be unique within the web application.
- is the fully qualified class name of this servlet
- is the optional parameter for this servlet that contains a name value pair that is used when the servlet is initialized. This element contains two sub elements <param-name> and <param-value>, which represent parameter’s name and value
- is the indicator of the load order for this servlet. If the value is a lowest positive integer, the servlet loaded first. To load the servlet at any time the value should be set to a negative integer or should be leaved undefined
In the second part of the
, we define element which is a servlet mapping for the build in default servlet. Note that each servlet defined in the must be mapped as in the default servlet example either in the server’s or web application’s . A description of each of the sub elements in the element is below:- a canonical name of the servlet. Note the sub element’s value in the must match the value specified in the element’s similar sub element.
- the url pattern which will be used to map all requests with matching patterns to the servlet
As you can see from configuration of the default servlet the default servlet is loaded at Tomcat server startup, directory listing is disabled, and debugging is disabled. To see extended list of options that you can modify go here. There you can find the available parameters descriptions and settings.
Most of the Tomcat server related security configurations are set in the Default Servlet element in the
. There are three main attributes of this element that need to be mentioned:- configuration should be set to true to prevent clients from deleting or modifying static resources on the server, and prevent clients from uploading new resources to the server.
- configuration should be set to false to prevent directory listing which if misused could use significant CPU and lead to DOS (Denial of Service) attacks.
- should be set to false (true by default). If directory listing is enabled Tomcat version number will be included in the info which is undesired.
For additional security it is recommended to have here.
for each individual web application with appropriate directory listing settings. On security settings read more 5.6. Default Session Configuration
You can set session timeout for all web application in the
. By default the session timeout is 30 minutes as shown below:
1
2
3
| < session-config > < session-timeout >30</ session-timeout > </ session-config > |
To change the value for when the session should be deleted change the
value.5.7. Default MIME Type Mappings
You can configure mapping for the data types that could be processed by the web applications in this Tomcat instance. There are many MIME types set by default in the
for all web applications. Tomcat will generate a header entry for the content type automatically based on the static resource’s file name extension using the MIMTE types specified here. Below some of the MIME types from the long list:
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
| < mime-mapping > < extension >gif</ extension > < mime-type >image/gif</ mime-type > </ mime-mapping > < mime-mapping > < extension >java</ extension > < mime-type >text/x-java-source</ mime-type > </ mime-mapping > < mime-mapping > < extension >wav</ extension > < mime-type >audio/x-wav</ mime-type > </ mime-mapping > < mime-mapping > < extension >xhtml</ extension > < mime-type >application/xhtml+xml</ mime-type > </ mime-mapping > |
Each <mime-mapping> element represents mapping between resource type and its “
” header value. sub element stands for the resource’s extension, and stands for the mime type that the file extension will map to.5.8. Default Welcome File List
When a request is made to a directory the Default Servlet tries to find the “
” in that directory. This listing is recommended to be overwritten in the per web application deployment configuration file ( ). If no “ ” found Tomcat returns 404.
1
2
3
4
5
| < welcome-file-list > < welcome-file >index.html</ welcome-file > < welcome-file >index.htm</ welcome-file > < welcome-file >index.jsp</ welcome-file > </ welcome-file-list > |
5.9. Configuring Clustering/Session Replication
For enabling clustering several steps need to be performed, and one of them is to add
element in the .
In addition other than here. Note that the request session gets distributed in the cluster to each web application that has element in it. It is recommended that all Tomcat instances configured the same.
server configuration files need to be modified as explained in
Blogger Comment
Facebook Comment