Using Helicon Ape under IIS6 (Windows Server 2003)

Hello everyone!
We are continuing to write about Helicon Ape tweaking and this article is about running our monkey on Windows 2003 Server. We've received a lot of responses from the users who haven't managed to configure Ape under IIS6. So we hope this article will give enough information to get Ape working for you.

Installation

If you still haven't downloaded Helicon Ape, please do on Helicon Ape Downloads page. Run installation and follow wizard instructions to setup Ape as you need. We want to notice that there are two types of inistallation: automatic and manual. We'll use the automatic one, cause there are no circumstances to force us do it manually. Below is the installation type window:

Please don't worry when you get the following warning:

It informs IIS6 users of necessity to perfrom specific mapping configuration. Details of this process are recounted below.
After successful Helicon Ape installation, let's look into its installation folder:

We'll give a brief explanation of some of the files in this folder as this may be useful for your further relations with Ape:
httpd.conf - server configuration, has the same meaning as in Apache. The rules put into it affect all the sites for which Ape is installed. It's worth mentioning that there are directives that may be used in server config only (e.g. VirtualHost).

smart_gzip_compression.conf - ready-to-use preset for mod_gzip and mod_cache. More info is given in the article How to enable mod_gzip compression for IIS7. Unfortunately, due to IIS6 technical restrictions mod_gzip and mod_cache modules are not available to Windows Server 2003 users.

error.log - log of debug messages. Verbosity of the log depends on the level set in LogLevel directive (debug value provides the most detailed log). If you feel that Ape is not working properly, check this log first. Name and location of error log file may be changed in ErrorLog directive.

rewrite.log - log of mod_rewrite operation. This file is really helpful when your mod_rewrite rules are doing something wrong. To see maximum details in this log please set RewriteLogLevel 9 in httpd.conf. Name and location of rewrite log file may be changed in RewriteLog directive.

Helicon.Ape.chm - that's our manual! It's worth reading, I swear;)

RegexTest.exe - mod_rewrite rules testing utility.

Helicon.Ape.Manager.exe - manager helping to configure Ape for your site without pain. Powerful text editor with autocompletion and syntax highlighting will make Ape configuration a real fun. Useful information about manager you can find here: Helicon Ape Manager - 10 helpful tips.
Other files help Helicon Ape work its miracles;)
Now let's open Helicon Ape Manager (Start->Programs->Helicon->Ape->Manager) to see default Ape settings. Click on «IIS Web Sites» in the tree to see the server config:

As you see almost all settings in httpd.conf are commented out. We don't recommend to uncomment any lines if you are not thinking of using them. That's why by default only mod_rewrite and mod_proxy are enabled - these module are the most popular ones.
After installation you may use Helicon Ape for free during 45 days. If Ape is doing well, you'll probably decide to buy it. After you perform a payment on our site you are given a license key. Open Help->About in Helicon Ape Manager and press «Register»:

Put obtained credentials into the corresponding fields and press OK.

Wildcard mapping

Now Ape is installed and registered but we haven't seen it working. As we stated above simple installation is not enough to have Ape working on IIS6. It's necessary to accomplish a ritual known as «wildcard mapping». In IIS Manager open properties for the target site or all sites («Web Sites»). In the opened dialog go to «Home Directory» tab. Then press «Configuration...» button. You'll get one more dialog where you need to press «Insert...» button for «Wildcard application maps». Now you ned to select aspnet_isapi.dll library. Default location for ASP.NET 2.0 is C:\Windows\Microsoft.NET\Framework\v2.0.50727\.
Don't forget to uncheck «Verify that file exists» check box! Here's the scheme illustrating described sequence of actions:

Ape is working
Well, all steps to make Ape working are now done. Let's check if it works anyway! Open Helicon Ape Manager and select a site for which you configured the wildcard mapping. We did it for «Default Web Site».
Pay attention that if you click on site or folder in the tree, manager opens existing or creates new .htaccess for this location (the file will be created only if you use editor and save the file).
Now we'll write the simplest rules for mod_rewrite (remember it's enabled by default?):

RewriteEngine on
RewriteRule .? - [F]

These rules will cause server to give 403 (Forbidden) response for all requests to the site. Notice that it's necessary to use RewriteEngine on directive as LoadModule directives in the server config just load Ape modules but don't enable them.

Save changes to this .htaccess (File->Save or Ctrl+S). Open browser and make request to any location inside the site you've chosen in manager (we configured Ape for «Default Web Site» that's why we have localhost in the address bar). The result should resemble this:

It's unlikely, but it may happen that you don't get the desired result. This situation is not covered in this article, so you'll need to address Troubleshooting section of our documentation. Besides, soon we'll tell you what useful information may be learned from log files.
As you remember httpd.conf has also mod_proxy module uncommented. Let's check its operation as well. Both modules are used really often, so it's vitaly important to ensure they work OK. Please delete all rules from .htaccess and add the following:

RewriteEngine on
RewriteProxy (.*) http://www.helicontech.com/$1 [L]

As you can see we use mod_rewrite directives but to enable proxy fuctionality mod_proxy module is used. So these rules actually check both modules operation.

If mod_proxy works fine, you'll get something like the following upon request to http://localhost/ape:

Limitations for IIS6
We've just made sure mod_rewrite and mod_proxy successfully work with IIS6. But not everything is flawless for this web-server. The thing is that Microsoft has completely reorganized modules interface in IIS7. That's why we've encountered certain issues trying to be good for both IIS7 and IIS6 users (though originally Helicon Ape was designed for IIS7). The vague ritual of wildcard mapping is a sacrifice made to provide support of two completely different architectures (IIS6 and 7). Compatibility chart shows what functionality is limited in IIS6 and we'll demonstrate how it shows up.
One of the modules that do not work for IIS6 is mod_headers. Click on «IIS Web Sites» in Helicon Ape Manager to open server config. Uncomment LoadModule headers_module line as shown in the picture and save changes:

Now open .htaccess where we put the rules for mod_proxy and write the following rules there:

RequestHeader set MyRequestHeader "Hello Server!"
Header set MyResponseHeader "Hello Client!"

The rules you've just written tell mod_headers to set HTTP request header with the name MyRequestHeader and value «Hello Server!», and HTTP response header with the name MyResponseHeader and value «Hello Client!».
To check whether the above rules work we need a tool that displays request/response headers. We use WFetch. And here's what it said:

Content-Length and Set-Cookie headers confirm correct operation of mod_rewrite/mod_proxy. But there's no MyRequestHeader or MyResponseHeader header. Probably mod_headers haven't fired. Let's figure out why. error.log will assist us in this.
Please open the server config again and uncomment LogLevel и ErrorLog directives as shown below:

Save changes and make one more request to the server. Now open error.log in Helicon Ape installation folder. It will contain the following lines:

The first line says that mod_proxy has executed correctly. Two subsequent lines warn you that mod_headers is not supported for IIS6. Pay attention that server hasn't returned any errors. Request was handled but no the way we wanted.

Conclusion

This article was written to prove that Helicon Ape does work (with some limitations) on Windows Server 2003. And it's really easy to configure. Hope that Ape will help you achieve desired results.
Best wishes,
HeliconTech Team.