Difference between revisions of "Tomcat"

From ArchWiki
Jump to navigation Jump to search
(Updated for tomcat7 package)
Line 1: Line 1:
 
{{stub}}
 
{{stub}}
Tomcat is an open source java servlet container.
+
Tomcat is an open source Java [http://en.wikipedia.org/wiki/Java_Servlet#Servlet_containers Servlet container] developed by the Apache Software Foundation.
  
This document describes the steps needed to install Apache Tomcat and how to deploy 3rd party web applications in Tomcat.
+
'''Note on Tomcat versions'''
  
 +
Tomcat currently exists under three stable branches: [http://tomcat.apache.org/download-55.cgi 5.5], [http://tomcat.apache.org/download-60.cgi 6] and [http://tomcat.apache.org/download-70.cgi 7]. None of these deprecates the previous. Instead, [http://tomcat.apache.org/whichversion.html#Apache_Tomcat_Versions each branch is the implementation of a couple of the "Servlet" and "JSP" Java standards]. The version officially supported in Arch Linux is [http://www.archlinux.org/packages/extra/i686/tomcat7 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 [http://aur.archlinux.org/packages.php?ID=19452 tomcat6] from AUR.
  
 
== Installation ==
 
== Installation ==
 +
pacman -S tomcat7
  
  # pacman -S tomcat
+
If using  out of a development environment (eg production), consider installing [http://tomcat.apache.org/native-doc/ tomcat-native]:
 +
  pacman -S tomcat-native
  
== Post Installation ==
+
This adds native 32b/64b code to enhance performance. This will remove the following warning in <tt>catalina.err</tt>:
 +
INFO: The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path [...]
  
=== Setting Java Home ===
+
=== Filesystem hierarchy ===
 +
* <tt>/usr/share/tomcat7</tt>
 +
Main Tomcat folder containing scripts and links to other directories
 +
* <tt>/usr/share/java/tomcat7</tt>
 +
Tomcat Java librairies (jars)
 +
* <tt>/etc/tomcat7</tt>
 +
Configuration files. Among some: <tt>tomcat-users.xml</tt> (defines users allowed to use administration tools and their roles), <tt>server.xml</tt> (Main Tomcat configuration file), <tt>catalina.policy</tt> (security policies configuration file)
 +
* <tt>/etc/rc.d/tomcat7</tt>
 +
Start/stop daemon script
 +
* <tt>/etc/conf.d/tomcat7</tt>
 +
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 <tt>CATALINA_OPTS</tt>, ...
 +
* <tt>/var/log/tomcat7</tt>
 +
Log files (<tt>catalina.err</tt>: startup log, <tt>catalina.out</tt>: output from stdout, others are access logs and business logs defined in <tt>/etc/tomcat7/server.xml</tt> as "Valve")
 +
* <tt>/var/lib/tomcat7/webapps</tt>
 +
Where Tomcat deploys your web applications
 +
* <tt>/var/tmp/tomcat7</tt>
 +
Where Tomcat store your webapps' data
  
There is two [https://wiki.archlinux.org/index.php/Java Java VM] in Arch: OpenJDK JVM and Sun JVM.
+
== Initial configuration ==
 +
In order to be able to use the manager webapp and the admin webapp you need to edit this the following file:
 +
/etc/tomcat7/tomcat-users.xml
  
Edit file <tt>/etc/conf.d/tomcat</tt>,
+
Uncomment the "role and user" XML declaration and modify it to enable roles <tt>tomcat</tt>, <tt>admin-{gui,script}<tt> and/or <tt>manager-{gui,script,jmx,status}</tt> depending on your needs.
 
+
To keep it short, <tt>tomcat</tt> is the mandatory role used to run, <tt>admin-*</tt> are roles able to administer web applications and <tt>admin-*</tt> are full right administrator roles on the Tomcat server.
* If you use OpenJDK JVM, set <tt>TOMCAT_JAVA_HOME</tt> to <tt>/usr/lib/jvm/java-6-openjdk</tt>, in example:
 
  
 +
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):
 
<code>
 
<code>
  TOMCAT_JAVA_HOME=/usr/lib/jvm/java-6-openjdk
 
</code>
 
 
* If you use Sun JVM, set <tt>TOMCAT_JAVA_HOME</tt> to <tt>/opt/java</tt>, in example:
 
 
<code>
 
  TOMCAT_JAVA_HOME=/opt/java
 
</code>
 
 
=== Creating an Admin user ===
 
 
Edit the Tomcat users file to include manager and admin roles with your favorite editor.
 
 
# vim /opt/tomcat/conf/tomcat-users.xml 
 
 
example of tomcat-users.xml file.
 
<Code>
 
 
  <?xml version='1.0' encoding='utf-8'?>
 
  <?xml version='1.0' encoding='utf-8'?>
  <tomcat-users>
+
<tomcat-users>
  <role rolename="manager"/>
 
 
   <role rolename="tomcat"/>
 
   <role rolename="tomcat"/>
   <role rolename="admin"/>
+
   <role rolename="manager-gui"/>
   <role rolename="role1"/>
+
  <role rolename="manager-script"/>
   <user username="both" password="tomcat" roles="tomcat,role1"/>
+
   <role rolename="manager-jmx"/>
   <user username="tomcat" password="tomcat" roles="tomcat"/>
+
   <role rolename="manager-status"/>
   <user username="admin" password="<your_password_here>" roles="admin,tomcat,manager"/>
+
  <role rolename="admin-gui"/>
   <user username="role1" password="tomcat" roles="role1"/>
+
  <role rolename="admin-script"/>
  </tomcat-users> \
+
   <user username="tomcat" password="[CHANGE_ME]" roles="tomcat"/>
</Code>
+
   <user username="manager" password="[CHANGE_ME]" roles="manager-gui,manager-script,manager-jmx,manager-status"/>
 +
   <user username="admin" password="[CHANGE_ME]" roles="admin-gui"/>
 +
</tomcat-users>
 +
</code>
  
 +
Keep in mind that Tomcat must be restarted each time a modification is made to this file.
  
 +
This [http://blog.techstacks.com/2010/07/new-manager-roles-in-tomcat-7-are-wonderful.html blog post] gives a good description of these roles.
  
== Starting Tomcat ==
+
== Start/stop Tomcat ==
  
As root or with sudo.
+
Once Tomcat is started using one of the following method, you can visit this page to see the result: [http://localhost:8080 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 <tt>/var/log/tomcat7/catalina.err</tt> ("catalina" is the name of Tomcat's servlet container). Google is full of answers on recurrent issues found in Tomcat logs.
  
  # /etc/rc.d/tomcat start
+
=== The standard secured way ===
 +
Just use the usual Arch Linux script:
 +
  /etc/rc.d/tomcat {start|stop|restart|status}
  
Successful outcome:
+
As usual one can add <tt>tomcat</tt> to the <tt>DAEMONS</tt> array of the <tt>rc.conf</tt> to make it start at boot.
<Code>
 
/etc/rc.d/tomcat start
 
:: Starting Tomcat                  [DONE]
 
</Code>
 
  
 +
'''Quick note about security''': Tomcat is packaged in Arch Linux to use the [http://commons.apache.org/daemon/jsvc.html jsvc] binary from Apache's [http://commons.apache.org/daemon/ common-daemons]. Tomcat <tt>rc.d</tt> script runs this Apache binary with root privileges which itself starts Tomcat with an underprivileged user (<tt>tomcat:tomcat</tt> 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 <tt>man jsvc</tt> for options available and pass them throught the <tt>CATALINA_OPTS</tt> envrionment variable declared in <tt>/etc/conf.d/tomcat7</tt>.
  
 +
=== Alternate "manual" way ===
 +
 +
Tomcat can also be controled directly using upstream scripts:
 +
/usr/share/tomcat/bin/{startup.sh,shutdown.sh,..}
 +
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.
  
Using your favorite browser go to http://localhost:8080/ for your default Tomcat home page.
+
== Deploy and handle web applications ==
  note: If this is not working. There is a problem with Tomcat.
+
By default, two ways are available to deploy applications.
        Check logs from /opt/tomcat/logs/catalina.log
+
The easiest is to use the manager webapp [http://localhost:8080/manager/html http://localhost:8080/manager/html]. Use the username/password you defined as <tt>manager</tt> in <tt>tomcat-users.xml</tt>. 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 <tt>/usr/share/tomcat7/webapps</tt>. For that later, be sure that the <tt>autoDeploy</tt> option is still set for the right host in <tt>/etc/tomcat7/server.xml</tt>:
 
+
<code>
== Web application deployment ==
+
<Host name="localhost" appBase="webapps"
 
+
      unpackWARs="true" autoDeploy="true">
 
+
</code>
Download the web application that you want to deploy ( a war file ) and save it to /opt/tomcat/webapps/ folder.
 
 
 
Restart Tomcat:
 
 
 
# /etc/rc.d/tomcat restart
 
 
 
Go to http://localhost:8080/manager/html
 
 
 
Tomcat will ask for your admin <username> and <password>.
 
 
 
Login and check that your war file is listed in the Applications.
 
 
 
If it is listed, click on it to access it.
 
 
 
Hint: Bookmark the webpage for later use.
 
 
 
 
 
== Problems in deployment ==
 
 
 
Tomcat should automatically deploy your war file if it is in the /opt/tomcat/webapps/ folder.
 
 
 
If this is not happening you could try to deploy manually.
 
 
 
In the manager page under Deploy click on the "Select WAR file to upload" and select the war file then click on "Deploy".
 
 
 
 
 
== How to stop Tomcat ==
 
 
 
 
 
As root or with sudo.
 
 
 
# /etc/rc.d/tomcat stop
 
 
 
  
== How to make Tomcat start automatically  ==
+
== 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 <tt>tomcat-users.xml</tt>. Other options are tweaked in configuration files in <tt>/etc/tomcat7</tt>, the most important beeing <tt>server.xml</tt>. Using these files is out of the scope of this 101 wiki page. Please have a look at the [http://tomcat.apache.org/tomcat-7.0-doc/index.html official Tomcat 7 documentation] for more details.
  
add Tomcat in to your /etc/rc.conf DAEMONS line
+
=== 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 [http://tomcat.apache.org/whichversion.html#Apache_Tomcat_Versions 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 [http://tomcat.apache.org/migration.html instructions on how to handle such a process].
  
DAEMONS=(... '''@tomcat''')
+
=== Security configuration ===
 +
Comming Soon...

Revision as of 10:14, 10 May 2011

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.

Installation

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:

/etc/tomcat7/tomcat-users.xml

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'?>
<tomcat-users>
 <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"/>
</tomcat-users>

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:

/usr/share/tomcat/bin/{startup.sh,shutdown.sh,..}

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...