Ozibug - web based bug tracking


  1. Introduction
  2. Overview
  3. Files and Paths
  4. Tomcat Configuration
  5. IIS Configuration
  6. Appendix A - TOMCAT_HOME\conf\workers.properties
  7. Appendix B - TOMCAT_HOME\conf\uriworkermap.properties
  8. Appendix C - TOMCAT_HOME\conf\iis_redirect.reg
  9. Appendix D - TOMCAT_HOME\conf\server.xml
 
Back to index
 
This document describes how to integrate the Ozibug application running in the Jakarta Tomcat Web Container (Tomcat) with the Microsoft Internet Information Service (IIS) application. Further documentation on this can be found in the TOMCAT_HOME/doc directory. The examples use the ajp12 connector and Jakarta Tomcat release 3.2.1.
IIS can be used to wrap the requests and responses to and from the Tomcat Web Container. It can pass through the requests for the Ozibug servlets but handle the static files and images itself freeing Tomcat of additional work.
This is useful for several reasons.
  1. Logging

    IIS can be configured to produce standard and custom logging reports. These can then be used to analyze and perhaps optimize the traffic to and from your web applications.

  2. Speed

    Web applications typically consist of static files containing images, scripts, and documents and some dynamically generated content. These static files can then be served by a faster Web Server (such as IIS) which is specifically designed for this purpose rather than the Web Container, which is tuned for serving the dynamically generated content.

  3. Security

    With the Web Server receiving the HTTP requests from the internet, this becomes the first line of defence against attacks. As such there are usually many security features that the Web Server provides which will stop rogue attacks against the underlying infrastructure (Web Container.)

  4. Integration

    By using a Web Server as a common front end it is easy to integrate multiple applications and web sites and redirectors behind it. This usually allows great flexibility in adding, changing and removing the content and services behind it.

Back to top
 
This section gives a quick overview of the operations you must carry out.
  1. Tomcat
    • Configure the workers.properties and uriworkermap.properties file.
    • Create the registry file iis_redirect.reg and insert the contents into the Windows registry.
    • Reconfigure Tomcat by editing the server.xml file.
  2. IIS
    • Download the isapi_redirect.dll file.
    • Create the OzibugServlet directory, copy the isapi_redirect.dll file into it and add to IIS as a virtual directory.
    • Add the OZIBUG_HOME directory to IIS as a virtual directory.
    • Restrict permissions for the OZIBUG_HOME\WEB-INF sub-directory.
    • Add the filename index.html to the default file list.
    • Add the isapi_redirect.dll as an ISS ISAPI filter.
  3. Start/Stop
    • You will need to stop and restart both Tomcat and IIS.
  4. Test
    • Test your installation thoroughly, if all is OK then continue with the following steps.
    • Raise the loglevel of the Tomcat plugin by updating the value in the file iis_redirect.reg and re-applying this to the registry. This will reduce the amount of unwanted logging.
    • Remove (or comment out) the Tomcat Connector on port 8080 from the server.xml file. This will enhance the security of the installation.
 
Back to top
 
The following paths and files are defined here for convenience and are used and referenced throughout this document.
  1. TOMCAT_HOME

    This is the location of Tomcat. The configuration, logging, work and webapps directories are all underneath this directory. This location is dependent on where you installed Tomcat.

    C:\jakarta-tomcat
                              
  2. JAVA_HOME

    This should be set to where you installed your Java VM which could either be a JDK or a JRE.

    C:\jdk1.3.1_04
                              
  3. OZIBUG_HOME

    This is the location of the Ozibug servlet. This directory is created when Ozibug is installed into Tomcat. This is dependant on where you installed Tomcat and how you have installed Ozibug into Tomcat.

    C:\jakarta-tomcat\webapps\ozibug
                              
Back to top
 
The following configuration files should be edited.
  1. TOMCAT_HOME\conf\workers.properties

    A working example of this file is contained in Appendix A. The following definitions should be set.

    workers.tomcat_home This should be set to TOMCAT_HOME as outlined in Section 3.1.
    workers.java_home This should be set to JAVA_HOME as outlined in Section 3.2.
    worker.list This should be set to the value ajp12.
    workers.tomcat_home=C:\jakarta-tomcat
    workers.java_home=C:\jdk1.3.1_04
    worker.list=ajp12
                              
  2. TOMCAT_HOME\conf\uriworkermap.properties

    A working example of this file is contained in Appendix B This file should only contain the following definitions.

    /ozibug/Controller=ajp12
    /ozibug/Stylesheet=ajp12
                              
  3. TOMCAT_HOME\conf\iis_redirect.reg

    This file must be created, a working example of this file is contained in Appendix C. This file contains entries that the redirector plugin will use to find the Tomcat installation.

    These entries are inserted into the registry. You can do this by highlighting the finished file in your Windows Explorer and double clicking on it. This will invoke the regedit program which will insert the entries.

    extension_uri This key is a link to the tomcat redirector plugin.
    log_file This key defines the logfile that the plugin will use. The logfile should be defined in the TOMCAT_HOME\logs directory.
    log_level This key defines the log level that the plugin will use. The level can be one of the following values "debug", "info", "error" or "emerg". Initially this should be set to debug, after the installation has been tested it should be set to error.
    worker_file
    This key should contain the filename of the workers.properties file defined in Section 4.1.
    worker_mount_file
    This key should contain the filename of the uriworkermap.properties file defined in Section 4.2.
    NOTE: that the entries in this file are wrapped in double quotes and the filenames contain double backslashes as the file separator character (except the extension_uri value.)

  4. TOMCAT_HOME\conf\server.xml

    A working example of this file is contained in Appendix D. This file contains the Tomcat configuration data in XML format. This must be edited to change the port numbers that Tomcat uses (as by default these will conflict with the Web Server ports.)

    The connector entry that defines the HTTP entry for port 80 should be changed to port 8080. This entry will look like this after editing.

    <Connector className="org.apache.tomcat.service.PoolTcpConnector">
      <Parameter name="port"
        value="8080">
      </Parameter>
      <Parameter name="handler"
        value="org.apache.tomcat.service.http.HttpConnectionHandler">
      </Parameter>
    </Connector>
                              

    After the installation and configuration have been tested this entry can be removed.

Back to top
 
The following steps need to be carried out to configure the IIS application.
  1. Tomcat Redirector Directory

    Create the directory C:\OzibugServlet and copy in the file isapi_redirect.dll. This file can be downloaded from the jakarta-tomcat website. It is included in the win32/i386 directory underneath the binaries directory.

    The C:\OzibugServlet directory is simply used to hold the redirector plugin and also give meaning to the name that the IIS Web Server logs whenever the Ozibug application is accessed.

    Using the IIS management console you must add the C:\OzibugServlet directory as a virtual directory of the web site you have chosen. Once added make sure that only the execute permission is given to this directory.

    NOTE: By default the MS Explorer file manager hides files that have the ".dll" extension. This setting can be changed on Windows NT by selecting the "view" and "options" from the top menu bar and unselecting the checkbox. On Windows 2K it can be changed by selecting "tools" and "folder options" from the top menu.

  2. OZIBUG_HOME Directory

    The OZIBUG_HOME directory which is defined in section 3.3, must be added as a virtual directory to IIS using the IIS management console.

    Once added you must make sure that the WEB-INF directory dous not have read, write or execute permissions. This directory is located directly underneath the main Ozibug directory.

    You can remove permissions by selecting the directory, clicking the right mouse button to retrieve the context menu and selecting properties. A dialog box is displayed where you can remove permissions. Do this and then select the Apply button.

  3. Default filename

    Using the IIS management console you must add the filename index.html to the default document list. This list of filenames is tried by the Web Server when a request is received which does not have a filename associated with it.

    This can be done by selecting the configured web site, clicking with the right mouse button to retrieve the context menu and then selecting the properties menu item. The document list is a tabbed pane on the dialog which is displayed.

  4. Mime types

    By default IIS doesn't configure all the mime types that are usually contained in an extensive web application. These must be added to IIS so that the correct content type is sent to the browser.

    Using the IIS Management Console select the web site that you have been using. Then using the right mouse button select the context menu and select the properties menu option. This displays the configuration dialog box for the web site. Select the HTTP Headers tab and at the bottom of the dialog box is the MIME Map. Push the File Types button which will display the File Types editor.

    By selecting the New Type button you can add a new mime type. Enter the filename extension into the associated extension field and the correct mime type into the Content Type field. Selecting OK will then add this type to IIS.

    The following mime types should be added.

    Associated extension Content Type (Mime)
    css text/css
    js text/javascript
    xml text/xml

     

  5. Tomcat Redirector Filter

    Using the IIS management console you must now add the file C:\OzibugServlet\isapi_redirect.dll as an ISAPI filter. The name should reflect its use so use Ozibug.

    Restart the IIS service - this should be done from the services tool (not the IIS management console.) Once restarted you can see the green arrow against the Ozibug ISAPI filter indicating that it is active.

Back to top
 
# workers.properties
#
# This file provides jk derived plugins with with the needed
# information to connect to the different tomcat workers.
#
# As a general note, the characters $( and ) are used internally
# to define macros. Do not use them in your own configuration!!!
#
# Whenever you see a set of lines such as:
# x=value
# y=$(x)\something
#
# the final value for y will be value\something
#
# Normaly all you will need to modify is the first properties, i.e.
# workers.tomcat_home, workers.java_home and ps. Most of the
# configuration is derived from these.
#
# When you are done updating workers.tomcat_home, workers.java_home
# and ps you should have 3 workers configured:
#
# - An ajp12 worker that connects to localhost:8007
# - An ajp13 worker that connects to localhost:8009
# - A jni inprocess worker.
# - A load balancer worker
#
# However by default the plugins will only use the ajp12 worker.
# To have the plugins use other workers you should modify the
# worker.list property.

#
# workers.tomcat_home should point to the location where you
# installed tomcat. This is where you have your conf, webapps and lib
# directories.
#
workers.tomcat_home=C:\jakarta-tomcat

#
# workers.java_home should point to your Java installation. Normally
# you should have a bin and lib directories beneath it.
#
workers.java_home=C:\jdk1.3.1_04

#
# You should configure your environment slash... ps=\ on NT and / on UNIX
# and maybe something different elsewhere.
#
ps=\
# ps=/

#
#------ ADVANCED MODE ------------------------------------------------
#---------------------------------------------------------------------
#

#
#------ DEFAULT worket list ------------------------------------------
#---------------------------------------------------------------------
#
#
# The workers that your plugins should create and work with
#
worker.list=ajp12

#
#------ DEFAULT ajp12 WORKER DEFINITION ------------------------------
#---------------------------------------------------------------------
#

#
# Defining a worker named ajp12 and of type ajp12
# Note that the name and the type do not have to match.
#
worker.ajp12.port=8007
worker.ajp12.host=localhost
worker.ajp12.type=ajp12
#
# Specifies the load balance factor when used with
# a load balancing worker.
# Note:
#  ----> lbfactor must be > 0
#  ----> Low lbfactor means less work done by the worker.
worker.ajp12.lbfactor=1

#
#------ DEFAULT ajp13 WORKER DEFINITION ------------------------------
#---------------------------------------------------------------------
#

#
# Defining a worker named ajp13 and of type ajp13
# Note that the name and the type do not have to match.
#
worker.ajp13.port=8009
worker.ajp13.host=localhost
worker.ajp13.type=ajp13
#
# Specifies the load balance factor when used with
# a load balancing worker.
# Note:
#  ----> lbfactor must be > 0
#  ----> Low lbfactor means less work done by the worker.
worker.ajp13.lbfactor=1

#
# Specify the size of the open connection cache.
#worker.ajp13.cachesize

#
#------ DEFAULT LOAD BALANCER WORKER DEFINITION ----------------------
#---------------------------------------------------------------------
#

#
# The loadbalancer (type lb) workers perform wighted round-robin
# load balancing with sticky sessions.
# Note:
#  ----> If a worker dies, the load balancer will check its state
#        once in a while. Until then all work is redirected to peer
#        workers.
worker.loadbalancer.type=lb
worker.loadbalancer.balanced_workers=ajp12, ajp13


#
#------ DEFAULT JNI WORKER DEFINITION---------------------------------
#---------------------------------------------------------------------
#

#
# Defining a worker named inprocess and of type jni
# Note that the name and the type do not have to match.
#
worker.inprocess.type=jni

#
#------ CLASSPATH DEFINITION -----------------------------------------
#---------------------------------------------------------------------
#

#
# Additional class path components.
#
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)classes

#
# The XML parser provided with Tomcat
#
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)jaxp.jar
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)parser.jar

#
# Tomcat's implementation
#
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)jasper.jar
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)servlet.jar
worker.inprocess.class_path=$(workers.tomcat_home)$(ps)lib$(ps)webserver.jar

#
# Javac as available from Java2SE
#
worker.inprocess.class_path=$(workers.java_home)$(ps)lib$(ps)tools.jar

#
# Setting the command line for tomcat
# Note: The cmd_line string may not contain spaces.
#
worker.inprocess.cmd_line=-config
worker.inprocess.cmd_line=$(workers.tomcat_home)/conf/jni_server.xml
worker.inprocess.cmd_line=-home
worker.inprocess.cmd_line=$(workers.tomcat_home)

#
# The JVM that we are about to use
#
# This is for Java2
#
worker.inprocess.jvm_lib=$(workers.java_home)$(ps)jre$(ps)bin$(ps)classic$(ps)jvm.dll

#
# And this is for jdk1.1.X
#
#worker.inprocess.jvm_lib=$(workers.java_home)$(ps)bin$(ps)javai.dll
#

#
# Setting the place for the stdout and stderr of tomcat
#
worker.inprocess.stdout=$(workers.tomcat_home)$(ps)inprocess.stdout
worker.inprocess.stderr=$(workers.tomcat_home)$(ps)inprocess.stderr

#
# Setting the tomcat.home Java property
#
worker.inprocess.sysprops=tomcat.home=$(workers.tomcat_home)

#
# Java system properties
#
# worker.inprocess.sysprops=java.compiler=NONE
# worker.inprocess.sysprops=myprop=mypropvalue

#
# Additional path components.
#
# worker.inprocess.ld_path=d:$(ps)SQLLIB$(ps)bin
#
                      
Back to top
 

#
# Simple worker configuration file
#

# direct the Ozibug servlets to the ajp12 worker
/Ozibug/Controller=ajp12
/Ozibug/Stylesheet=ajp12
                      
Back to top
 

REGEDIT4

[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0]
"extension_uri"="/OzibugServlet/isapi_redirect.dll"
"log_file"="C:\\jakarta-tomcat\\logs\\iis_redirect.log"
"log_level"="debug"
"worker_file"="C:\\jakarta-tomcat\\conf\\workers.properties"
"worker_mount_file"="C:\\jakarta-tomcat\\conf\\uriworkermap.properties"
                      
Back to top
 

<?xml version="1.0" encoding="UTF-8"?>
<Server>
  <xmlmapper:debug level="0">
  </xmlmapper:debug>

  <Logger verbosityLevel="DEBUG"
    name="tc_log"
    path="logs/tomcat.log">
  </Logger>

  <Logger verbosityLevel="DEBUG"
    name="servlet_log"
    path="logs/servlet.log">
  </Logger>

  <Logger verbosityLevel="DEBUG"
    name="JASPER_LOG"
    path="logs/jasper.log">
  </Logger>

  <ContextManager>
    <ContextInterceptor className="org.apache.tomcat.context.LoaderInterceptor">
    </ContextInterceptor>
    <ContextInterceptor className="org.apache.tomcat.context.DefaultCMSetter">
    </ContextInterceptor>
    <ContextInterceptor className="org.apache.tomcat.context.WorkDirInterceptor">
    </ContextInterceptor>
    <RequestInterceptor
      className="org.apache.tomcat.request.SessionInterceptor">
    </RequestInterceptor>
    <RequestInterceptor debug="0"
      className="org.apache.tomcat.request.SimpleMapper1">
    </RequestInterceptor>
    <RequestInterceptor debug="0"
      prefix="/servlet/"
      className="org.apache.tomcat.request.InvokerInterceptor">
    </RequestInterceptor>
    <RequestInterceptor debug="0"
      className="org.apache.tomcat.request.StaticInterceptor"
      suppress="false">
    </RequestInterceptor>
    <RequestInterceptor
      className="org.apache.tomcat.session.StandardSessionInterceptor">
    </RequestInterceptor>
    <RequestInterceptor debug="0"
      className="org.apache.tomcat.request.AccessInterceptor">
    </RequestInterceptor>

    <!-- Loaded last since JSP's that load-on-startup use request handling -->
    <ContextInterceptor className="org.apache.tomcat.context.LoadOnStartupInterceptor">
    </ContextInterceptor>

    <!-- The AJP12 Connector -->
    <Connector className="org.apache.tomcat.service.PoolTcpConnector">
      <Parameter name="port"
        value="8007">
      </Parameter>
      <Parameter name="handler"
        value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler">
      </Parameter>
    </Connector>

    <!-- Comment out the next section after testing -->
    <Connector className="org.apache.tomcat.service.PoolTcpConnector">
      <Parameter name="port"
        value="8080">
      </Parameter>
      <Parameter name="handler"
        value="org.apache.tomcat.service.http.HttpConnectionHandler">
      </Parameter>
    </Connector>

    <!-- Ozibug application definition -->
    <Context trusted="false"
      docBase="C:\jakarta-tomcat\webapps\Ozibug"
      reloadable="false"
      debug="0"
      path="/ozibug"
      crossContext="false">
    </Context>

  </ContextManager>
</Server>
                      
Back to top
 
Back to index