BonCode (www.BonCode.net)
11
BonCode Apache Tomcat
AJP 1.3 Connector
How to connect IIS to Apache Tomcat via the
Apache JServ Protocol v 1.3 using BonCode AJP
connector
© 2011-2016 by Bilal Soylu
2 | P a g e
Table of Contents
BonCode AJP 1.3 Connector ......................................................................................................................... 4
License....................................................................................................................................................... 4
The Beginning ........................................................................................................................................... 4
BonCode Connector Solution .................................................................................................................... 4
Prerequisites ......................................................................................................................................... 5
Note on http headers ............................................................................................................................ 5
The Package Content ................................................................................................................................ 5
How to Install Automatically ..................................................................................................................... 6
How to Install Manually ............................................................................................................................ 9
ASP.NET Web Services Extension Enabled on IIS6 (Windows 2003): ................................................. 12
Wildcard mappings: ............................................................................................................................ 12
Step 1: IIS6 Example of adding a wildcard map .................................................................................. 13
IIS7/8 Example of adding a wildcard managed handler ..................................................................... 14
Example of correctly installed files and directories on IIS on a Site basis (all): .................................. 15
OPTIONAL STEPS (INTERNATIONAL CHARACTERS) ............................................................................. 16
Sample web.config file (IIS6 only) ....................................................................................................... 16
The settings file (BonCodeAJP13.settings) .............................................................................................. 17
Example Settings file ........................................................................................................................... 25
Configuring the Connector for Performance .......................................................................................... 25
Enable Additional Logging ....................................................................................................................... 27
How to uninstall the connector .............................................................................................................. 27
Using the connector .................................................................................................................................... 28
The Issue with Path-Info ......................................................................................................................... 28
The Issue ............................................................................................................................................. 28
The Solution ........................................................................................................................................ 28
RFC Compliance .................................................................................................................................. 28
Differences with ISAPI ............................................................................................................................. 30
SSL Certificates .................................................................................................................................... 30
JVM Route Attribute ........................................................................................................................... 31
General Recommendations .................................................................................................................... 31
Unblock before use ............................................................................................................................. 31
3 | P a g e
Connector Thoughts ............................................................................................................................ 32
Setup Recommendations .................................................................................................................... 33
Connector Commands ................................................................................................................................ 35
Identifying the installed Version ............................................................................................................. 35
Listing known virtual directories ............................................................................................................. 36
Enabling Windows Application Log Entries ............................................................................................. 36
HTTP Headers and connector behavior ...................................................................................................... 36
Inbound White Lists ............................................................................................................................ 37
Inbound Black Lists .............................................................................................................................. 37
Using Header Data Support ........................................................................................................................ 38
Transmission of IIS Document Root ........................................................................................................ 38
Transmitting Virtual Directories Information ......................................................................................... 38
Working Principles .............................................................................................................................. 38
Testing Virtual Directories Setup ........................................................................................................ 38
Setup Additional Permissions Requirement ....................................................................................... 39
Scripted Deployment .................................................................................................................................. 42
Installing .................................................................................................................................................. 42
Installer Command Line Parameters ................................................................................................... 42
Installer Parameters File (installer.settings) ....................................................................................... 44
Uninstalling ............................................................................................................................................. 48
Troubleshooting .......................................................................................................................................... 50
Q&A ......................................................................................................................................................... 59
4 | P a g e
BonCode AJP 1.3 Connector
License
This manual is distributed under the Creative Commons v.3 license
(http://creativecommons.org/licenses/by/3.0/). The code is distributed under the Apache License
Version 2 (http://www.apache.org/licenses/LICENSE-2.0). In short, you are totally and utterly at your
own risk and merit if you use any samples provided.
Full source code can be downloaded from here:
https://github.com/Bilal-S/iis2tomcat
The Beginning
You are using Microsoft IIS 5, 6, 7, or 8+ as your webserver and want to connect it effectively to an
Apache Tomcat application server. You want to make this easy and do not want to install ISAPI based
connectors which have their own share of issues. Or, you may want to interoperate better using
multiple Tomcat applications with one IIS server.
BonCode Connector Solution
The BonCode AJP (Apache JServ Protocol version 1.3) Connector uses already existing pathways to
connect to Apache Tomcat. The AJPv13 protocol details can be found here
(http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html).
In general it is a preference question whether you use the ISAPI connection, which is the old C/C++ way
of connecting IIS to other protocols or the methods implemented in the BonCode connector.
There are several advantages with the BonCode connector though:
no ISAPI code (less risk of memory leaks, easier debugging)
no IIS6 vestiges or backward compatibility elements needed on IIS7+
all managed code .net extensibility framework
works on IIS5.1, IIS6, IIS7, IIS7.5, IIS8, IIS8.5
speed improvements
easier control by using IIS UI and handler mappings
no virtual directories and virtual mapping needed
configuration can be inherited to sub-sites and virtual sites
easy install/uninstall
support partial stream sending to browser (automatic flushing) with faster response to client
support both 32/64 bit of Windows with same process and files
transfer of all request headers to servlet container
build in simple-security for web-administration pages
5 | P a g e
Prerequisites
Besides Apache Tomcat, you will need a dot-net framework (3.51 or higher) installed on your machine.
The install packages includes .net version 3.5. This is also a standard feature in Windows 2008+ server
and Windows 7+. It can be downloaded for previous versions of Windows. The standard package
downloaded contains the installation stub that can be run separately if needed.
IMPORTANT: If you have already installed .net framework version 4 or 4.5 you do not need to install
3.51. If you receive a 500.21 error. Please see troubleshooting section.
Note on http headers
Http headers are important markers that are sent along with http requests on the internet. They can
denote the length of content, the type of content, how to treat the response etc.
The BonCode connector will send more headers along than any previous connection technology
between IIS and Apache Tomcat. Header name case as sent by browser will be preserved. However, if
header names are set by IIS only they will be lower cased, e.g. X-Forwarded-For will become x-
forwarded-for, this is to follow convention of previous connectors. Also, the connector will
suppress headers that do not contain any data (are blank), to save on network bandwidth and
processing. You can influence these and other behaviors by supplying settings that change how the
connector operates. See the “The settings file (BonCodeAJP13.settings)” later in this document for
details.
The Package Content
The BonCode IIS to Apache Tomcat connector consists of 2 mandatory and one optional file. Additional
documentation, license, and experimental files may be present based on the state of the build.
BonCodeIIS.dll
This is the main handler for the IIS communication process. It will intercept requests and pass
them to the protocol handler for translation.
BonCodeAJP13.dll
This is the implementation of JServ 1.3 communication protocol. This is the main library for
communicating with tomcat.
BonCodeAJP13.settings
This file is completely optional. It is a settings file that can be used to change behavior of the
connector. It needs to be placed in the same directory as BonCodeAJP13.dll in site wide
deployments. In global deployments, this file will need to be placed in system directory
(c:\windows)
Connector_Setup.exe
