From ArchWiki
Revision as of 10:14, 10 May 2011 by Wikimig (talk | contribs) (Updated for tomcat7 package)
Jump to navigation Jump to search

Tomcat is an open source Java Servlet container developed by the Apache Software Foundation.

Note on Tomcat versions

Tomcat currently exists under three stable branches: 5.5, 6 and 7. None of these deprecates the previous. Instead, each branch is the implementation of a couple of the "Servlet" and "JSP" Java standards. The version officially supported in Arch Linux is Tomcat 7 implementing Servlet 3.0 and JSP 2.2. If you happen to need to run a Java application with older versions of Servlet and/or JSP, you should try unsupported packages tomcat5.5 (coming soon) or tomcat6 from AUR.


pacman -S tomcat7

If using out of a development environment (eg production), consider installing tomcat-native:

pacman -S tomcat-native

This adds native 32b/64b code to enhance performance. This will remove the following warning in catalina.err:

INFO: The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path [...]

Filesystem hierarchy

  • /usr/share/tomcat7

Main Tomcat folder containing scripts and links to other directories

  • /usr/share/java/tomcat7

Tomcat Java librairies (jars)

  • /etc/tomcat7

Configuration files. Among some: tomcat-users.xml (defines users allowed to use administration tools and their roles), server.xml (Main Tomcat configuration file), catalina.policy (security policies configuration file)

  • /etc/rc.d/tomcat7

Start/stop daemon script

  • /etc/conf.d/tomcat7

Default running option file. Use this file rather than the rc.d script to set the JVM you want Tomcat to be run with, options to pass to Tomcat through the environment variable CATALINA_OPTS, ...

  • /var/log/tomcat7

Log files (catalina.err: startup log, catalina.out: output from stdout, others are access logs and business logs defined in /etc/tomcat7/server.xml as "Valve")

  • /var/lib/tomcat7/webapps

Where Tomcat deploys your web applications

  • /var/tmp/tomcat7

Where Tomcat store your webapps' data

Initial configuration

In order to be able to use the manager webapp and the admin webapp you need to edit this the following file:


Uncomment the "role and user" XML declaration and modify it to enable roles tomcat, admin-{gui,script} and/or manager-{gui,script,jmx,status} depending on your needs. To keep it short, tomcat is the mandatory role used to run, admin-* are roles able to administer web applications and admin-* are full right administrator roles on the Tomcat server.

Here is a bare config file that declares some of these roles along with usernames and passwords (Be sure to change the following [CHANGE_ME] passwords to something secure):

<?xml version='1.0' encoding='utf-8'?>
 <role rolename="tomcat"/>
 <role rolename="manager-gui"/>
 <role rolename="manager-script"/>
 <role rolename="manager-jmx"/>
 <role rolename="manager-status"/>
 <role rolename="admin-gui"/>
 <role rolename="admin-script"/>
 <user username="tomcat" password="[CHANGE_ME]" roles="tomcat"/>
 <user username="manager" password="[CHANGE_ME]" roles="manager-gui,manager-script,manager-jmx,manager-status"/>
 <user username="admin" password="[CHANGE_ME]" roles="admin-gui"/>

Keep in mind that Tomcat must be restarted each time a modification is made to this file.

This blog post gives a good description of these roles.

Start/stop Tomcat

Once Tomcat is started using one of the following method, you can visit this page to see the result: http://localhost:8080. If a nice Tomcat local home page is displayed this means your Servlet container is up and running and ready to host you web apps. If the startup script failed or you can only see a Java error displayed in you browser, have a look at startup logs in /var/log/tomcat7/catalina.err ("catalina" is the name of Tomcat's servlet container). Google is full of answers on recurrent issues found in Tomcat logs.

The standard secured way

Just use the usual Arch Linux script:

/etc/rc.d/tomcat {start|stop|restart|status}

As usual one can add tomcat to the DAEMONS array of the rc.conf to make it start at boot.

Quick note about security: Tomcat is packaged in Arch Linux to use the jsvc binary from Apache's common-daemons. Tomcat rc.d script runs this Apache binary with root privileges which itself starts Tomcat with an underprivileged user (tomcat:tomcat in Arch Linux). This prevents malicious code that could be executed in a bad web application from making too much damage. This also enables the use of ports under 1024 if needed. See man jsvc for options available and pass them throught the CATALINA_OPTS envrionment variable declared in /etc/conf.d/tomcat7.

Alternate "manual" way

Tomcat can also be controled directly using upstream scripts:


This can be usefull to debug applications or even debug Tomcat. In order to be able to use these scripts, some further configuration may be needed. Be aware that using these scripts prevents the jsvc security advantage described above.

Deploy and handle web applications

By default, two ways are available to deploy applications. The easiest is to use the manager webapp http://localhost:8080/manager/html. Use the username/password you defined as manager in tomcat-users.xml. Once logged in you can see five already deployed web applications. Add yours through the "Deploy" area and then stop/start/undeploy it with the "Applications" area. One can also just copy the WAR file of the application to directory /usr/share/tomcat7/webapps. For that later, be sure that the autoDeploy option is still set for the right host in /etc/tomcat7/server.xml:

<Host name="localhost"  appBase="webapps"
     unpackWARs="true" autoDeploy="true">

Further setup

Basic configuration can be made through the virtual host manager web application: http://localhost:8080/host-manager/html. Provide the username/password you set in tomcat-users.xml. Other options are tweaked in configuration files in /etc/tomcat7, the most important beeing server.xml. Using these files is out of the scope of this 101 wiki page. Please have a look at the official Tomcat 7 documentation for more details.

Migrating from previous versions of Tomcat

As said in the introduction, Tomcat 7 does not deprecates Tomcat 6 nor Tomcat 6 deprecates Tomcat 5.5. They are all three, implementations of Servlet/JSP standards. Hence you must first determine which version of Tomcat you need depending on the versions of Servlet/JSP your application uses. If you need to migrate, the official website gives instructions on how to handle such a process.

Security configuration

Comming Soon...