Difference between revisions of "Tomcat"

From ArchWiki
Jump to navigation Jump to search
m (link style)
 
(91 intermediate revisions by 32 users not shown)
Line 1: Line 1:
{{stub}}
+
[[Category:Web server]]
Tomcat is an open source java servlet container.
+
[[de:Apache Tomcat]]
 
+
[[ja:Tomcat]]
This document describes the steps needed to install Apache Tomcat and how to deploy 3rd party web applications in Tomcat.
+
[[zh-hans:Tomcat]]
 +
Tomcat is an open source Java [[wikipedia:Java_Servlet#Servlet_containers|Servlet container]] developed by the Apache Software Foundation. For more information about basic configuration, see:[[Tomcat and Apache]]
  
 +
{{Note|Tomcat currently exists under two stable branches: [http://tomcat.apache.org/download-70.cgi 7] and [https://tomcat.apache.org/download-80.cgi 8]. None of these version deprecates the preceding. 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]. All versions are officially supported in Arch Linux: {{Pkg|tomcat7}} and {{Pkg|tomcat8}}. Check the version you need depending on your web applications requirements. If you just want to try out tomcat or just do not want to spend more time figuring out, there are good chances you will want to try tomcat7. This wiki page refers to tomcat7 but most of its content can be applied to tomcat8.}}
  
 
== Installation ==
 
== Installation ==
 +
Install one of {{Pkg|tomcat7}}, {{Pkg|tomcat8}}, or tomcat9.
  
  # pacman -S tomcat
+
If deploying Tomcat onto a production environment, consider installing {{Pkg|tomcat-native}}. The native library for Tomcat configures the server to use the Apache Portable Runtime (APR) library's network connection (socket) and RNG implementations. It uses native 32- or 64-bit code to enhance performance and is sometimes used in production environments where speed is crucial. No configuration is necessary for default Tomcat installations. More information is availble in the [http://tomcat.apache.org/native-doc/ official Tomcat docs]. To install Tomcat in version 9 witch is needed for servlet specification 4.0 is at the moment missing and will come soon as possible. To install tomcat in version 9 follow the instructions in the [https://tomcat.apache.org/tomcat-9.0-doc/index.html official Tomcat 9 docs].
 
 
== Post Installation ==
 
 
 
=== Setting Java Home ===
 
  
There is two [https://wiki.archlinux.org/index.php/Java Java VM] in Arch: OpenJDK JVM and Sun JVM.
+
Using tomcat-native will remove the following warning in {{Ic|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 [...]
  
Edit file <tt>/etc/conf.d/tomcat</tt>,
+
=== Filesystem hierarchy ===
 +
Replace the {{ic|*}} with your installed version (7 or 8).
  
* If you use OpenJDK JVM, set <tt>TOMCAT_JAVA_HOME</tt> to <tt>/usr/lib/jvm/java-6-openjdk</tt>, in example:
+
{| class="wikitable"
 +
! Pathname !! Use
 +
|-
 +
|{{ic|/etc/tomcat*}}            || Configuration files. Among some: {{ic|tomcat-users.xml}} (defines users allowed to use administration tools and their roles), {{ic|server.xml}} (Main Tomcat configuration file), {{ic|catalina.policy}} (security policies configuration file)
 +
|-
 +
|{{ic|/usr/share/tomcat*}}      ||Main Tomcat folder containing scripts and links to other directories
 +
|-
 +
|{{ic|/usr/share/java/tomcat*}} ||Tomcat Java libraries (jars)
 +
|-
 +
||{{ic|/var/log/tomcat*}}      ||Log files '''not''' handled by {{Ic|systemd}} (see [[#Logging]])
 +
|-
 +
|{{ic|/var/lib/tomcat*/webapps}}||Where Tomcat deploys your web applications
 +
|-
 +
|{{ic|/var/tmp/tomcat*}}        ||Where Tomcat store your webapps' data
 +
|}
  
<code>
+
== Initial configuration ==
  TOMCAT_JAVA_HOME=/usr/lib/jvm/java-6-openjdk
+
In order to be able to use the manager webapp and the admin webapp you need to edit the following file:
</code>
+
{{ic|/etc/tomcat7/tomcat-users.xml}}
  
* If you use Sun JVM, set <tt>TOMCAT_JAVA_HOME</tt> to <tt>/opt/java</tt>, in example:
+
Uncomment the "role and user" XML declaration and modify it to enable roles {{ic|tomcat}}, {{ic|admin-gui}}, {{ic|admin-script}} and/or {{ic|manager-gui}}, {{ic|manager-script}}, {{ic|manager-jmx}}, {{ic|manager-status}} depending on your needs (see [http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html#Configuring_Manager_Application_Access Configuring Manager Application Access]).
 +
To keep it short, {{ic|tomcat}} is the mandatory role used to run, {{ic|manager-*}} are roles able to administer web applications and {{Ic|admin-*}} are full right administrator roles on the Tomcat server.
  
<code>
+
Here is a bare configuration file that declares some of these roles along with usernames and passwords (Be sure to change the following [CHANGE_ME] passwords to something secure):
  TOMCAT_JAVA_HOME=/opt/java
 
</code>
 
  
=== Creating an Admin user ===
+
{{hc|/etc/tomcat7/tomcat-users.xml|2=
 
+
<?xml version='1.0' encoding='utf-8'?>
Edit the Tomcat users file to include manager and admin roles with your favorite editor.
+
<tomcat-users>
 
 
# vim /opt/tomcat/conf/tomcat-users.xml
 
 
 
example of tomcat-users.xml file.
 
<Code>
 
<?xml version='1.0' encoding='utf-8'?>
 
  <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>
 +
}}
  
 +
Keep in mind that Tomcat must be restarted each time a modification is made to this file.
  
== Starting Tomcat ==
+
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.
  
As root or with sudo.
+
To have read permissions on the configuration files and work well with some IDEs, you must add your user to the `tomcat7` (respectively `tomcat8`) group:
 +
  gpasswd -a <user> tomcat<number>
  
# /etc/rc.d/tomcat start
+
== Start/stop Tomcat ==
  
Successful outcome:
+
[[Start]] the {{ic|tomcat7}} service.
<Code>
 
/etc/rc.d/tomcat start
 
:: Starting Tomcat                  [DONE]  
 
</Code>
 
  
 +
Once Tomcat is started, 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 using systemd's [[journalctl]]. Google is full of answers on recurrent issues found in Tomcat logs.
  
 +
{{Note|To improve security, Arch Linux's Tomcat packages use the [http://commons.apache.org/daemon/jsvc.html jsvc] binary from Apache's [http://commons.apache.org/daemon/ common-daemons]. Tomcat's {{Ic|systemd}} service runs this Apache binary with root privileges which itself starts Tomcat with an underprivileged user ({{Ic|tomcat7:tomcat7}} in Arch Linux). This prevents malicious code that could be executed in a bad web application from causing too much damage. This also enables the use of ports under 1024 if needed. See {{Ic|man jsvc}} for options available and pass them through the {{Ic|CATALINA_OPTS}} environment variable declared in {{ic|/etc/conf.d/tomcat7}}.}}
  
Using your favorite browser go to http://localhost:8080/ for your default Tomcat home page.
+
=== Alternate "manual" way ===
  note: If this is not working. There is a problem with Tomcat.
+
        Check logs from /opt/tomcat/logs/catalina.log
+
Tomcat can also be controlled directly using upstream scripts:
 +
/usr/share/tomcat/bin/{startup.sh,shutdown.sh,..}
 +
This can be useful to debug applications or even debug Tomcat, but do not use it to start Tomcat for the first time as doing so can set some permissions wrongly and stop web apps from working. 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 ==
  
== Web application deployment ==
+
Tomcat 7 is bundled with 5 already deployed web applications (change localhost with your server's FQDN if needed):
 +
* The default home page: [http://localhost:8080/ http://localhost:8080/]
 +
* Tomcat 7's local documentation: [http://localhost:8080/docs/ http://localhost:8080/docs/]
 +
* Examples of Servlets and JSP: [http://localhost:8080/examples/ http://localhost:8080/examples/]
 +
* The host-manager to handle virtual hosts: [http://localhost:8080/host-manager http://localhost:8080/host-manager/]
 +
* The manager to administer web applications: [http://localhost:8080/manager/html http://localhost:8080/manager/html/]
  
 +
=== The GUI way ===
 +
Probably the easiest way is to use the manager webapp [http://localhost:8080/manager/html http://localhost:8080/manager/html]. Use the username/password you defined as {{Ic|manager}} in {{ic|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.
  
Download the web application that you want to deploy ( a war file ) and save it to /opt/tomcat/webapps/ folder.
+
=== The CLI way ===
 +
One can also just copy the WAR file of the application to directory {{ic|/usr/share/tomcat8/webapps}}. For that later, be sure that the {{Ic|autoDeploy}} option is still set for the right host as shown here:
 +
{{hc|/etc/tomcat8/server.xml|2=
 +
...
 +
<Host name="localhost"  appBase="webapps"
 +
      unpackWARs="true" '''autoDeploy="true"'''>
 +
...
 +
}}
  
Restart Tomcat:
+
=== Hosting files outside the webapps folder ===
 +
If you want to keep your project outside the webapps folder this is possible by creating a {{ic|Context}}.
 +
Go to {{ic|/etc/tomcat<number>/Catalina/localhost/}} and create your context. A context is a simple xml file which specifies where tomcat should look for the project. The basic format of the file is
 +
{{hc|/etc/tomcat7/Catalina/localhost/whatShouldFollowLocalhost.xml|2=
 +
<Context path="/whatSholdFollwLocalhost" docBase="/where/your/project/is/" reloadable="true"/>
 +
}}
  
# /etc/rc.d/tomcat restart
+
A working example is as follows. This assumes that the project is hosted somewhere in the users /home-folder.
 +
{{hc|/etc/tomcat7/Catalina/localhost/myProject.xml|2=
 +
<Context path="/myProject" docBase="/home/archie/code/jsp/myProject" reloadable="true"/>
 +
}}
 +
The files can now be hosted in {{ic|/home/archie/code/jsp/myProject/}}. To see the project in your webbrowser, go to [http://localhost:8080/myProject http://localhost:8080/myProject].
 +
If tomcat is unable to load the files, it might be an issue with permissions. {{ic|chmod o+x /home/archie/code/jsp/myProject}} should fix the issue.
  
Go to http://localhost:8080/manager/html
+
== Logging ==
 +
Tomcat when used with official Arch Linux packages uses systemd's [[journalctl]] '''for startup log'''. This means that files {{ic|/var/log/tomcat7/catalina.err}} and {{ic|/var/log/tomcat7/catalina.out}} are '''not''' used. Other logs such as access logs and business logs defined in {{ic|/etc/tomcat7/server.xml}} as {{Ic|Valve}} will still by default end up in {{ic|/var/log/tomcat7/}}.
  
Tomcat will ask for your admin <username> and <password>.
+
To restore upstream style logging, copy systemd file {{ic|/lib/systemd/system/tomcat7.service}} to {{ic|/etc/systemd/system/tomcat7.service}} and change both {{ic|SYSLOG}} for the absolute paths of log files.
  
Login and check that your war file is listed in the Applications.
+
== 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 {{ic|tomcat-users.xml}}. Other options are tweaked in configuration files in {{ic|/etc/tomcat7}}, the most important being {{ic|server.xml}}. 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.
  
If it is listed, click on it to access it.
+
=== Migrating from previous versions of Tomcat ===
 +
As said in the introduction, '''Tomcat 8 does not deprecate Tomcat 7'''. 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].
  
Hint: Bookmark the webpage for later use.
+
=== Using Tomcat with a different JRE/JDK ===
 +
Apart from installing the desired JRE/JDK, the only requirement is to set the TOMCAT_JAVA_HOME variable in Tomcat's {{Ic|systemd}} service file.
  
 +
The variable can be overridden by a custom configuration, as described in [[Systemd#Editing provided units]]:
 +
# create the directory ''/etc/systemd/system/tomcat7.service.d''
 +
# in that directory, save a ''start.conf'' file with this content (for the Oracle JDK package {{AUR|jdk}}, use instead ''/usr/lib/jvm/java-8-jdk''):
 +
[Service]
 +
Environment=TOMCAT_JAVA_HOME=/usr/lib/jvm/java-8-openjdk
  
== Problems in deployment ==
+
Alternatively, copy the service file ''/usr/lib/systemd/system/tomcat7.service'', to ''/etc/systemd/system/'' and replace this line:
 +
Environment=TOMCAT_JAVA_HOME=/usr/lib/jvm/java-7-openjdk
 +
by (e.g. for Oracle JDK)
 +
Environment=TOMCAT_JAVA_HOME=/opt/java
  
Tomcat should automatically deploy your war file if it is in the /opt/tomcat/webapps/ folder.
+
=== Security configuration ===
 +
This page gives the bare minimum to get your first web application to run on Tomcat. It is not intended to be the definitive guide to administering Tomcat (it is a job of its own). The official Tomcat website will provide all necessary official matter. One could also refer to [http://oreilly.com/java/archive/tomcat-tips.html this O'Reilly page] and this [http://www.unidata.ucar.edu/projects/THREDDS/tech/reference/TomcatSecurity.html last one].  
 +
Still, here are some security tips to get you started:
  
If this is not happening you could try to deploy manually.
+
* Keep your Tomcat installation up to date to get the latest fixes to security issues
 +
* Remove unwanted default applications such as {{Ic|examples}}, {{Ic|docs}}, default home page {{Ic|ROOT}} ("_" in the {{Ic|manager}} webapp). This prevents potential security holes to be exploited. Use the {{Ic|manager}} for that.
  
In the manager page under Deploy click on the "Select WAR file to upload" and select the war file then click on "Deploy".
+
For more security you could even remove the host-manager and manager web applications. Keep in mind that the later is useful to deploy web applications.
  
 +
* Disable the WAR auto-deploy option. This would prevent someone who gained restricted access to the server to copy a WAR into the {{ic|/usr/share/java/webapps}} directory to get it running. Edit {{ic|server.xml}} and set the {{Ic|autoDeploy}} to {{Ic|false}}:
 +
{{hc|/etc/tomcat7/server.xml|2=
 +
...
 +
<Host name="localhost"  appBase="webapps"
 +
      unpackWARs="true" '''autoDeploy="false"'''>
 +
...
 +
}}
 +
* Anonymize Tomcat's default error page to prevent potential attackers to retrieve Tomcat's version. To see what Tomcat says by default, just visit an nonexistent page such as [http://localhost:8080/I_dont_exist http://localhost:8080/I_dont_exist]. You get a 404 error page with Tomcat's version at the bottom.
  
== How to stop Tomcat ==
+
To anonymize this, edit/open the following JAR (Editors like {{Ic|vim}} can edit zips directly)
 +
/usr/share/tomcat7/lib/catalina.jar
 +
And edit the following file
 +
{{hc|org/apache/catalina/util/ServerInfo.properties|2=
 +
...
 +
server.info=
 +
server.number=
 +
server.built=
 +
...
 +
}}
  
 +
* Disable unused {{Ic|connectors}} in {{ic|server.xml}}
 +
* Keep restricted access to {{ic|/etc/tomcat7/server.xml}}. Only {{Ic|tomcat}} user and/or {{Ic|root}} should be able to read and write this.
 +
* Keep {{Ic|jsvc}} usage. Do not use upstream startup scripts unless particular reason as explained in the security note above.
 +
* Use strong different passwords for each user in {{Ic|tomcat-users.xml}}, give roles to users who really need them and even disable usernames/roles you do not use/need.
  
As root or with sudo.
+
One can even crypt {{ic|tomcat-users.xml}} passwords using the following upstream script:
 +
/usr/share/tomcat7/bin/digest.sh -a SHA NEW_PASSWORD
 +
This will output something like:
 +
NEW_PASSWORD:b7bbb48a5b7749f1f908eb3c0c021200c72738ce
 +
Paste the hashed part in place of the clear password in {{ic|tomcat-users.xml}} and add the following to {{ic|server.xml}}:
 +
{{hc|/etc/tomcat7/server.xml|2=
 +
<Host
 +
  ...
 +
  <Realm
 +
    ...
 +
    '''className="org.apache.catalina.realm.MemoryRealm" digest="SHA"'''
 +
    ...
 +
  />
 +
  ...
 +
/>
 +
}}
  
# /etc/rc.d/tomcat stop
+
Note that this may not be relevant because only root and/or tomcat is supposed to have read/write access to that file. If an intruder manages to gain root access then he would not need such passwords to mess with your applications/data anyway. Be sure to keep restricted RW access to that file!
 +
* Always know what you are deploying
  
 +
== Troubleshooting ==
 +
=== Tomcat service is started, but page is not loaded ===
 +
First check {{ic|/etc/tomcat7/tomcat-users.xml}} for any syntax error. If everything is fine and {{ic|tomcat7}} is correctly running, type {{ic|journalctl -r}} to check the logs for any exception thrown (see [[#Logging|Logging]]). If you read anything like {{ic|java.lang.Exception: Socket bind failed: [98] Address already in use}}, this is due to some other service listening on the same port. For instance, it is possible that [[Apache]] and Tomcat are listening on the same port (if for example you have Apache running on port 8080 with [[Nginx]] serving it as a proxy on port 80). If this is the case, edit the {{ic|/etc/tomcat7/server.xml}} file and change the Connector port to something else under {{ic|1=<Service name="Catalina">}}:
  
== How to make Tomcat start automatically  ==
+
{{hc|/etc/tomcat7/server.xml|2=
 +
<?xml version='1.0' encoding='utf-8'?>
 +
...
 +
...
 +
<!-- Change port from 8080 to something else, like 8090 -->
 +
<Service name="Catalina">
 +
    <Connector executor="tomcatThreadPool"
 +
                port="8090" protocol="HTTP/1.1"
 +
                connectionTimeout="20000"
 +
                redirectPort="8443" />
 +
...
 +
...
 +
</Service>
 +
}}
  
add Tomcat in to your /etc/rc.conf DAEMONS line
+
Finally [[restart]] {{ic|tomcat7}} and {{ic|httpd}} services.
  
DAEMONS=(... '''@tomcat''')
+
If you have no solution and you are in a VM, it can help to delete /dev/random and create it again (cf. [https://www.nofluffjuststuff.com/blog/pratik_patel/2010/01/solution_futex_wait_hangs_java_on_linux__ubuntu_in_vmware_or_virtual_box Solution: FUTEX_WAIT hangs Java on Linux / Ubuntu in vmware or virtual box]):
 +
rm /dev/random
 +
mknod -m 644 /dev/random c 1 9
 +
Or another solution to keep it even after a reboot, modify {{ic|/usr/lib/jvm/java-8-openjdk/jre/lib/security/java.security}} (for example) to point to /dev/urandom

Latest revision as of 20:17, 23 January 2019

Tomcat is an open source Java Servlet container developed by the Apache Software Foundation. For more information about basic configuration, see:Tomcat and Apache

Note: Tomcat currently exists under two stable branches: 7 and 8. None of these version deprecates the preceding. Instead, each branch is the implementation of a couple of the "Servlet" and "JSP" Java standards. All versions are officially supported in Arch Linux: tomcat7 and tomcat8. Check the version you need depending on your web applications requirements. If you just want to try out tomcat or just do not want to spend more time figuring out, there are good chances you will want to try tomcat7. This wiki page refers to tomcat7 but most of its content can be applied to tomcat8.

Installation

Install one of tomcat7, tomcat8, or tomcat9.

If deploying Tomcat onto a production environment, consider installing tomcat-native. The native library for Tomcat configures the server to use the Apache Portable Runtime (APR) library's network connection (socket) and RNG implementations. It uses native 32- or 64-bit code to enhance performance and is sometimes used in production environments where speed is crucial. No configuration is necessary for default Tomcat installations. More information is availble in the official Tomcat docs. To install Tomcat in version 9 witch is needed for servlet specification 4.0 is at the moment missing and will come soon as possible. To install tomcat in version 9 follow the instructions in the official Tomcat 9 docs.

Using tomcat-native 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

Replace the * with your installed version (7 or 8).

Pathname Use
/etc/tomcat* 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)
/usr/share/tomcat* Main Tomcat folder containing scripts and links to other directories
/usr/share/java/tomcat* Tomcat Java libraries (jars)
/var/log/tomcat* Log files not handled by systemd (see #Logging)
/var/lib/tomcat*/webapps Where Tomcat deploys your web applications
/var/tmp/tomcat* 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 the following file: /etc/tomcat7/tomcat-users.xml

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

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

/etc/tomcat7/tomcat-users.xml
<?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.

To have read permissions on the configuration files and work well with some IDEs, you must add your user to the `tomcat7` (respectively `tomcat8`) group:

 gpasswd -a <user> tomcat<number>

Start/stop Tomcat

Start the tomcat7 service.

Once Tomcat is started, 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 using systemd's journalctl. Google is full of answers on recurrent issues found in Tomcat logs.

Note: To improve security, Arch Linux's Tomcat packages use the jsvc binary from Apache's common-daemons. Tomcat's systemd service runs this Apache binary with root privileges which itself starts Tomcat with an underprivileged user (tomcat7:tomcat7 in Arch Linux). This prevents malicious code that could be executed in a bad web application from causing too much damage. This also enables the use of ports under 1024 if needed. See man jsvc for options available and pass them through the CATALINA_OPTS environment variable declared in /etc/conf.d/tomcat7.

Alternate "manual" way

Tomcat can also be controlled directly using upstream scripts:

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

This can be useful to debug applications or even debug Tomcat, but do not use it to start Tomcat for the first time as doing so can set some permissions wrongly and stop web apps from working. 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

Tomcat 7 is bundled with 5 already deployed web applications (change localhost with your server's FQDN if needed):

The GUI way

Probably the easiest way 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.

The CLI way

One can also just copy the WAR file of the application to directory /usr/share/tomcat8/webapps. For that later, be sure that the autoDeploy option is still set for the right host as shown here:

/etc/tomcat8/server.xml
...
<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="true">
...

Hosting files outside the webapps folder

If you want to keep your project outside the webapps folder this is possible by creating a Context. Go to /etc/tomcat<number>/Catalina/localhost/ and create your context. A context is a simple xml file which specifies where tomcat should look for the project. The basic format of the file is

/etc/tomcat7/Catalina/localhost/whatShouldFollowLocalhost.xml
<Context path="/whatSholdFollwLocalhost" docBase="/where/your/project/is/" reloadable="true"/>

A working example is as follows. This assumes that the project is hosted somewhere in the users /home-folder.

/etc/tomcat7/Catalina/localhost/myProject.xml
<Context path="/myProject" docBase="/home/archie/code/jsp/myProject" reloadable="true"/>

The files can now be hosted in /home/archie/code/jsp/myProject/. To see the project in your webbrowser, go to http://localhost:8080/myProject. If tomcat is unable to load the files, it might be an issue with permissions. chmod o+x /home/archie/code/jsp/myProject should fix the issue.

Logging

Tomcat when used with official Arch Linux packages uses systemd's journalctl for startup log. This means that files /var/log/tomcat7/catalina.err and /var/log/tomcat7/catalina.out are not used. Other logs such as access logs and business logs defined in /etc/tomcat7/server.xml as Valve will still by default end up in /var/log/tomcat7/.

To restore upstream style logging, copy systemd file /lib/systemd/system/tomcat7.service to /etc/systemd/system/tomcat7.service and change both SYSLOG for the absolute paths of log files.

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 being 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 8 does not deprecate Tomcat 7. 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.

Using Tomcat with a different JRE/JDK

Apart from installing the desired JRE/JDK, the only requirement is to set the TOMCAT_JAVA_HOME variable in Tomcat's systemd service file.

The variable can be overridden by a custom configuration, as described in Systemd#Editing provided units:

  1. create the directory /etc/systemd/system/tomcat7.service.d
  2. in that directory, save a start.conf file with this content (for the Oracle JDK package jdkAUR, use instead /usr/lib/jvm/java-8-jdk):
[Service]
Environment=TOMCAT_JAVA_HOME=/usr/lib/jvm/java-8-openjdk

Alternatively, copy the service file /usr/lib/systemd/system/tomcat7.service, to /etc/systemd/system/ and replace this line:

Environment=TOMCAT_JAVA_HOME=/usr/lib/jvm/java-7-openjdk

by (e.g. for Oracle JDK)

Environment=TOMCAT_JAVA_HOME=/opt/java

Security configuration

This page gives the bare minimum to get your first web application to run on Tomcat. It is not intended to be the definitive guide to administering Tomcat (it is a job of its own). The official Tomcat website will provide all necessary official matter. One could also refer to this O'Reilly page and this last one. Still, here are some security tips to get you started:

  • Keep your Tomcat installation up to date to get the latest fixes to security issues
  • Remove unwanted default applications such as examples, docs, default home page ROOT ("_" in the manager webapp). This prevents potential security holes to be exploited. Use the manager for that.

For more security you could even remove the host-manager and manager web applications. Keep in mind that the later is useful to deploy web applications.

  • Disable the WAR auto-deploy option. This would prevent someone who gained restricted access to the server to copy a WAR into the /usr/share/java/webapps directory to get it running. Edit server.xml and set the autoDeploy to false:
/etc/tomcat7/server.xml
...
<Host name="localhost"  appBase="webapps"
      unpackWARs="true" autoDeploy="false">
...
  • Anonymize Tomcat's default error page to prevent potential attackers to retrieve Tomcat's version. To see what Tomcat says by default, just visit an nonexistent page such as http://localhost:8080/I_dont_exist. You get a 404 error page with Tomcat's version at the bottom.

To anonymize this, edit/open the following JAR (Editors like vim can edit zips directly)

/usr/share/tomcat7/lib/catalina.jar

And edit the following file

org/apache/catalina/util/ServerInfo.properties
...
server.info=
server.number=
server.built=
...
  • Disable unused connectors in server.xml
  • Keep restricted access to /etc/tomcat7/server.xml. Only tomcat user and/or root should be able to read and write this.
  • Keep jsvc usage. Do not use upstream startup scripts unless particular reason as explained in the security note above.
  • Use strong different passwords for each user in tomcat-users.xml, give roles to users who really need them and even disable usernames/roles you do not use/need.

One can even crypt tomcat-users.xml passwords using the following upstream script:

/usr/share/tomcat7/bin/digest.sh -a SHA NEW_PASSWORD

This will output something like:

NEW_PASSWORD:b7bbb48a5b7749f1f908eb3c0c021200c72738ce

Paste the hashed part in place of the clear password in tomcat-users.xml and add the following to server.xml:

/etc/tomcat7/server.xml
<Host
  ...
  <Realm
    ...
    className="org.apache.catalina.realm.MemoryRealm" digest="SHA"
    ...
  />
  ...
/>

Note that this may not be relevant because only root and/or tomcat is supposed to have read/write access to that file. If an intruder manages to gain root access then he would not need such passwords to mess with your applications/data anyway. Be sure to keep restricted RW access to that file!

  • Always know what you are deploying

Troubleshooting

Tomcat service is started, but page is not loaded

First check /etc/tomcat7/tomcat-users.xml for any syntax error. If everything is fine and tomcat7 is correctly running, type journalctl -r to check the logs for any exception thrown (see Logging). If you read anything like java.lang.Exception: Socket bind failed: [98] Address already in use, this is due to some other service listening on the same port. For instance, it is possible that Apache and Tomcat are listening on the same port (if for example you have Apache running on port 8080 with Nginx serving it as a proxy on port 80). If this is the case, edit the /etc/tomcat7/server.xml file and change the Connector port to something else under <Service name="Catalina">:

/etc/tomcat7/server.xml
<?xml version='1.0' encoding='utf-8'?>
...
...
<Service name="Catalina">
    <Connector executor="tomcatThreadPool"
                 port="8090" protocol="HTTP/1.1"
                 connectionTimeout="20000"
                 redirectPort="8443" />
...
...
</Service>

Finally restart tomcat7 and httpd services.

If you have no solution and you are in a VM, it can help to delete /dev/random and create it again (cf. Solution: FUTEX_WAIT hangs Java on Linux / Ubuntu in vmware or virtual box):

rm /dev/random 
mknod -m 644 /dev/random c 1 9

Or another solution to keep it even after a reboot, modify /usr/lib/jvm/java-8-openjdk/jre/lib/security/java.security (for example) to point to /dev/urandom