![]() ![]() ![]() ![]() |
Chapter 5
Customizing TomcatIntroduction
This chapter provides information and instructions on customizing domains using Tomcat.
Topics include:
About Tomcat
Ensim Pro supports the latest version of Tomcat (v-4.0.6), developed by the Jakarta-Apache Project. Tomcat 4.0 implements the final released versions of the Java Servlet 2.3 and JaveServer Pages (JSP) 1.2 specifications. As required by the specifications, Tomcat 4.0 also supports Web applications built for Java Servlet 2.2 and JSP 1.1 specifications, with no changes. Additionally, the Tomcat 4.0 Servlet Container (Catalina) provides greater flexibility and performance.
The Tomcat 4 package includes a set of tools designed to host Java Web applications. The package is shipped with the following:
- Sun® Java 2 Standard Edition (J2SE) development environment version 1.4.2, which includes J2SDK 1.4.2 and JRE (installed in /usr/java/j2sdk1.4.2/
and /usr/java/j2sdk1.4.2/jre/ respectively)- mod_jk-2.0 (Apache 2.0)
- Tomcat 4.0.6, installed in /var/tomcat4
- Database driver for MySQL and postgres, installed in /var/tomcat4/common/lib:
- mysql-connector-java-3.0.8-stable-bin.jar for MySQL
- pg73jdbc3.jar for postgres
- Tyrex, installed in /var/tomcat4/common/lib/tyrex-0.9.7.0.jar
- JNDI, installed in /var/tomcat4/common/lib/jndi.jar
- Mail, installed in /var/tomcat4/common/lib/mail.jar
![]()
Ensure that you meet the following minimum requirements for Tomcat:
* RAM: The server must have at least 512 MB of RAM.
*Disk usage: The server must have at least 21 MB free disk space available.
About JSPs and servlets
Ensim Pro (with the mod_jk module) has JSP and servlet functionality enabled on the Apache Web server. The Tomcat engine executes JSP and servlets. Once you enable Tomcat for a site, Ensim Pro instructs the Web server to send certain requests to Tomcat for processing. Tomcat requires an execution environment known as context, to be set up before it can execute JSPs and servlets properly.
A context is basically a directory structure on the server from which Tomcat can execute servlets and JSPs. Ensim Pro automatically sets contexts for you. You can also add a new context by uploading Java Web archive files (with the extension .war) into Web content directories.
![]()
Java Web archive files can be uploaded only after they are uncompressed. To uncompress the Java Web archive files, you must use the Site Administrator user account. Since the Tomcat daemon runs as a Tomcat user, it does not have the requisite privileges to uncompress files owned by the Site Administrator.
Deploying JSPs and servlets on Ensim Pro
Deploying JSPs and servlets on Ensim Pro is as easy as uploading a Web site using any FTP client. When you enable Tomcat for a site, Ensim Pro creates a default Tomcat context, for the virtual site in the Web directory. The context path of each virtual site is /home/virtual/domainname/var/www/html/.
A new directory called WEB-INF is created in this directory. The WEB-INF directory contains some configuration information for Tomcat and a directory in which servlet class files are placed for deployment.
As long as the file extension of the JSP file is .jsp, the Site Administrator can simply load a JSP page in the directory /var/www/html/, and the Web server automatically passes it on to Tomcat for processing.
For example, if you have a file named test.jsp, the Site Administrator can use an FTP client to upload the file in the directory /var/www/html/. You can then access the dynamic JSP page through http://<site name>/test.jsp. The first time you access this page, Tomcat takes a few seconds to compile the page but subsequent accesses are much quicker. Compiling a servlet source Java file creates a servlet class file. Deploying a servlet on Ensim Pro includes uploading the servlet class file in /var/www/html/WEB-INF/classes/.
For example, if you have a file named test.class, you would use an FTP client to upload the file in /var/www/html/WEB-INF/classes/. The servlet is executed through http://<site name>/servlet/test.
Compiling a Java servlet source file
You can develop servlets manually through the command line and a text editor. Ensim Pro provides a Java software development kit and a Java run time environment for the Site Administrator when you enable the service Development Tools for the site. The service installs a script java.sh in /etc/profile.d/. When you log onto the server, your shell runs this script and some relevant Java-environment variables are set up for you. You can add additional $CLASSPATH, for any site, by editing the script /etc/profile.d/java.sh.
![]()
To compile a Java servlet source file into a Java class file for Tomcat
- Log on to Ensim Pro as the Site Administrator.
- Change to the directory in which the source servlet code file is located.
- Enter the following command.
javac <
myServlet.java>
(substitute your file name for the file myServlet.java).- If the compilation is successful and no errors are reported, the file myServlet.class can be located in the same directory.
- To use this servlet, copy the file myServlet.class in the directory WEB-INF/classes.
Customizing Tomcat
The standard, out-of-the-box configuration of Apache Tomcat may not fit your development needs. This is particularly true if your application requires elevated permissions, a custom JDBC driver or access to other Java classes stored on the server.
Reviewing site permissions
The default site permissions are set by the file /var/tomcat4/conf/sites.policies.d/site<n>.policy and the site context is set by the file /var/tomcat4/conf/sites.xml.d/site<n>.xml where site<n> is the site index.
You can review the site permissions anytime.
![]()
To review site permissions
- Log on to the server as root user.
- At the command prompt, type the following:
sitelookup -d <domain name>
The following output displays.
<
domain name>, admin<n>,site<
n>,/home/virtual/<
domain name>,<admin name>.
The output indicates that the site index of
<
domain name>
issite<
n>
. Use the site index to determine site permissions.For example, if a site named www.myco.com has the site index site<n>, then the
file /var/tomcat4/conf/sites.policies.d/site<n>.policy will consist of default site permissions for site<n>. This file appends to the file catalina.policy.Reviewing site context
The default site context is set by the file /var/tomcat4/conf/sites.xml.d/site<n>.xml.
The contents of the file site<n>.xml are:
<Host name=”myco.com” appbase=”/home/virtual/site<n>/fst/var/www/html”>
<Alias>www.myco.com</Alias>
<!-- Global logger unless overridden at lower levels -->
<Logger className=”org.apache.catalina.logger.FileLogger”
directory=”/home/virtual/site<
n>/fst/var/log”
prefix=”tomcat4_log.”
timestamp=”true”/>
<Realm className=”org.apache.catalina.realm.MemoryRealm” />
<Context path=””
docBase=”/home/virtual/site<
n>/fst/var/www/html”
crossContext=”false”
reloadable=”true” />
sinclude(`/var/tomcat4/conf/sites.xml.d/site<
n>.xml.custom')
</Host>
The default context for myco.com is /var/www/html in the domain file system of myco.com. This file appends to the file server.xml.
Adding security permissions
All Tomcat contexts, added by the Ensim Pro, receive a default set of security permissions. The default security permissions are as follows:
grant codeBase “file:/home/virtual/site<
N>/fst/var/www/html/
-” {permission java.net.SocketPermission “*”, "connect”;};
![]()
To add security permissions for a site:
- Log on to Ensim Pro as root user.
- Change directory to /var/tomcat4/conf/ sites.policies.d/.
- In this directory, create the file site<n>.policy.custom.
- Add the required security permissions to the file site<n>.policy.custom.
- Regenerate the file /var/tomcat4/conf/catalina.policy using the following command.
#m4 /var/tomcat4/conf/catalina.policy.template > /var/tomcat4/conf/catalina.policy
- To clear the cache and to enable new changes in /var/tomcat4/work/domainname, type the following commands.
cd /var/tomcat4/work/
rm -rf *
- To restart Tomcat, type the following command.
/etc/rc.d/init.d/tomcat4 restart
When adding security permissions for a site:
- Do not make any direct changes to the files /var/tomcat4/conf/catalina.policy or site<n>.policy, as these changes will be overwritten by the configuration scripts in Ensim Pro.
- Edit the file site<N>.policy.custom. This will be appended to the file catalina.policy.
- Be aware that allowing all security permissions may open up the site to hackers.
- Be aware that syntax errors may result in Tomcat failing to start.
- Edit /var/tomcat4/conf/catalina.policy.template to set global settings - applicable to all sites.
- Back up conf files before editing them.
Adding an additional context path
All Tomcat enabled sites receive default context path as /var/www/html/. As the Appliance Administrator, you can add an additional context path.
![]()
To add an additional context path:
- Log on to Ensim Pro as root user.
- Change directory to /var/tomcat4/conf/sites.xml.d/.
- In this directory, create a file site<n>.xml.custom.
- Add the additional context to this file.
- Regenerate the file /var/tomcat4/conf/server.xml using the following command.
#m4 /var/tomcat4/conf/server.xml.template > /var/tomcat4/conf/server.xml
- To clear the cache in order to enable new changes in /var/tomcat4/work/domain name, type the following commands.
cd /var/tomcat4/work/
rm -rf *
- To restart Tomcat, type the following command.
/etc/rc.d/init.d/tomcat4 restart
When adding an additional context path:
- Do not make any direct changes to the files /var/tomcat4/conf/server.xml or site<n>.xml, as these changes will be overwritten by the configuration scripts in Ensim Pro.
- Edit the file site<n>.xml.custom. This will be appended to the file server.xml.
- Be aware that syntax errors may result in Tomcat failing to start.
- Edit /var/tomcat4/conf/server.xml.template to set global settings - applicable to all sites.
- Back up conf files before editing them.
Adding additional class paths
Ensim Pro provides database drivers for MySQL and postgres. You may come across a situation where the default class path for Tomcat does not suffice and you need to indicate the path for your own classes that exist elsewhere on the file system.
If you want to add additional classes (for example, a new JDBC driver) to Tomcat's default CLASSPATH, you must add CLASSPATH=$CLASSPATH:/path/to/my/new/class in the file /etc/tomcat4/conf/tomcat4.conf.
For the changes to take effect, restart the Tomcat engine. Only root users can set new CLASSPATH for any Web site. If you want to add new database driver or component, which should be available to all sites, add it to:
- /var/tomcat4/common/classes – if it is a class file
- /var/tomcat4/common/lib – if it is a jar file
Enabling the Tomcat development environment
You can create a Web site with the domain name myco.com with Tomcat development environment enabled and set the Site Administrator name as adminmyco.
Assumptions:
- The Web site is developed on Sun J2SE 1.4
- The site number is 1
![]()
To enable the Tomcat development environment:
![]()
To compile .java files, use javac *.java.
Adding permissions
![]()
To add permissions to connect to the SMTP server:
- Log on to Ensim Pro as root user.
- Change directory to /var/tomcat4/conf/sites.policy.d.
- Create a new file site1.policy.custom.
- In the file site1.policy.custom, include the following lines to add permissions to connect to the SMTP server.
Permission java.net.SocketPermission "127.0.0.1:25", connect, resolve";
Permission java.net.SocketPermission "localhost:25", connect, resolve";- Save the file site1.policy.custom.
- Regenerate the file /var/tomcat4/conf/catalina.policy using the following command.
#m4 /var/tomcat4/conf/catalina.policy.template > /var/tomcat4/conf/catalina.policy
- To restart Tomcat, type the following command.
/etc/rc.d/init.d/tomcat4 restart
Adding additional context
![]()
To add additional context:
- Log on to Ensim Pro as root user.
- Change directory to /var/tomcat4/conf/sites.xml.d.
- Create a new file site1.xml.custom.
- Add new context to this file.
- Save the file.
- Regenerate the file /var/tomcat4/conf/server.xml using the following command.
#m4 /var/tomcat4/conf/server.xml.template > /var/tomcat4/conf/server.xml
- To restart Tomcat, type the following command.
/etc/rc.d/init.d/tomcat4 restart
Starting Tomcat
By default, Ensim Pro always displays the Tomcat status as ON (enabled). You can start Tomcat either manually or automatically.
Manually
![]()
To manually start Tomcat:
Automatically
![]()
To automatically start Tomcat:
Disabling Tomcat
You can disable Tomcat permanently if you no longer want to use Tomcat. You can turn off the Java virtual machines that handles the requests and prevent Tomcat from launching in the future.
![]()
To disable Tomcat:
- Log on to Ensim Pro as Appliance Administrator.
- Type su -. The system prompts you for a password.
- Enter the root password.
You now have root privileges, which means that you can change anything on the server appliance operating system.
- Type the following commands in the order specified.
/sbin/chkconfig --del tomcat4
/etc/rc.d/init.d/tomcat4 stop
Additional resources
For more information on Tomcat, refer to the following links.
Ensim
Corporation www.ensim.com Contact Ensim www.ensim.com/about/contact.html |
![]() ![]() ![]() ![]() |