Blog

I recently had a need to do a massive search and replace on a whole tree of text files. There are a million ways to do this, but I wanted the simplest possible way. The ideal solution would be short enough to memorize, cross-platform, and flexible. The first option rules out the scripting languages (syntax would be too arcane to memorize for a one-liner, and too long to memorize for a proper solution).

Then I remembered seeing a BASH one-liner (using external programs) to tackle this same task. I went hunting and re-found the find and sed tools. This solution is ideal. It's cross platform (using Cygwin on Windows, which I always have installed), it's a simple line of code, and it's very flexible.

The Apache Software Foundation's Tomcat servlet container was developed with an external module to connect it to other web servers using a protocol called AJP. The code is implemented in a project called JK. It is often referred to as mod_jk, because that's the name of the Apache HTTPD module. For some reason, the implementation for IIS is called ISAPI_Redirect.

The connection between IIS and Tomcat (or any of the numerous other servlet containers that have implemented AJP receivers to work with JK) is relatively simple. The JK DLL is installed into IIS as a filter + extension. It is configured to activate itself on certain URL patterns. For those patterns that match, the DLL sends an AJP packet to the servlet containers (called "workers") that have been configured. Assuming the servlet container has an AJP listener turned on, it then responds with the content of the response.

Note: Communication via AJP can be configured to happen on any port. By default, the port is 8009. AJP is not a secure protocol, so this port should be limited to communication between internal servers. Port 8009 should not be open on the external firewall.

Installation

First, download the JK 1.X Win32 binary from the an Apache mirror:
http://jakarta.apache.org/site/downloads/downloads_tomcat-connectors.cgi

If using IIS 5 or newer, download the isapi_redirect-1.x.exe. The EXE installer is the most convenient installation method.

The installer places all its files in C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\. Example (usable) configuration files are placed in the conf subdirectory.

Registry configuration is also set up at HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0. The registry keys point the ISAPI dll to the configuration files in C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\conf.

You'll also find a new Virtual Directory, called jakarta in the IIS Web Site configuration window. This directory is needed to forward the requests on to the application server, although it will not be present in your site's URLs.

Setting up a Context

To set up a context (an application hosted in a subdirectory of the site), you need to edit the
uriworkermap.properties file in the installation folder. This file maps URLs to workers. A "worker" is an instance of Tomcat, Jetty or another application server that supports the AJP protocol. The term more accurately applies when mod_jk is used in a load balancing environment.

The uriworkermap.properties simply identifies URL patterns that should be forwarded to an application server. The URL will not be changed in the process, so IIS mapped URLs must be identical to the context/URL configuration of the application server.

For example, assume we have applications (contexts) called accounting, intranet, and development set up in Tomcat. When using Tomcat's own HTTP, the URL for the accounting application woudl be http://localhost:8080/accounting. To set up this application to be accessed through IIS, we'd modify uriworkermap.properties like so:


/accounting/*=ajp13w


In this case, ajp13w identifies the name of the Tomcat worker. The name ajp13w is the name of the default installation worker (which will likely be configured correctly if IIS and Tomcat and IIS are on the same server). The mapping indicates that all requests to the accounting subdirectory be sent to Tomcat.

Note: You'll need to restart IIS to get the new URL mappings to activate.

Division of Labor

You may want to divide responsibilities so that IIS handles static files, and only dynamic content is served by the underlying application server. This is typically done by unmapping certain file extensions in the uriworkermap.properties file. Unmap directives are identical to mapping ones, with an added ! as the first character.


!/accounting/*.jpg=ajp13w
!/accounting/*.gif=ajp13w
!/accounting/*.png=ajp13w
!/accounting/static/*=ajp13w


The above directives would cause mod_jk to not forward JPG, GIF and PNG requests for the accounting context. It also causes the entire static subdirectory to be ignored by mod_jk as well.

Now to make sure IIS knows where to find these files, we'll need to set up a Virtual Directory where these files can be found. In this case, we'll set up an IIS Virtual Directory called accounting (it must be the same as the context). We'll point that virtual directory to the same one that hosts the application server files.

HTTP Authentication

In many cases, you'll want the application server to continue to manage authentication. This setup is more portable (the same username database will be used on any web server), and it saves the effort of configuring usernames and passwords through Windows or IIS.

If your application uses HTTP Digest or Basic authentication, you'll need some special configuration, as IIS will normally try to hijack the application servers authentication attempts.

By default, the jakarta Virtual Directory has its own Directory Security settings turned on (Integrated Windows authentication is enabled, I believe). If you want authentication to be handled by the application server, you'll need to turn off all but Anonymous access in the Directory Security tab for the jakarta Virtual Directory. The same applies to context Virtual Directories if you're using them.

I recently found an article on ASPN that demonstrates using Python to modify Environment Variables, especially the PATH variable.

The key to the article is that it demonstrates a way to make Environment Variable changes persistent. It does this by modifying the registry directly. After editing the registry, it causes a broadcast to be sent indicating the change in system settings. Although the example is in Python, this process is possible with any language that can access the Win32 system API.

After all these years, Windows still provides a tiny little edit box for editing the PATH (and other) environment variables. It's especially annoying when setting up scripting languages like Python, Perl, Ruby and Groovy for PATH access.

To make this setup process easer, it helps to define HOME variables for each scripting language. To do this, we need to use the Registry Editor to add new environment variables.

1. Open the Windows Registry Editor: Start->Run->regedit.
2. Navigate to HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment.

Most of the material in this tutorial comes from two places: How to Install Ruby on Windows, and Windows Success Stories in Rails.

Ruby installation is extremely simple on Windows, thanks to the Nullsoft installer. The installer copies the Ruby binaries to a path of your choice and adds the bin directory to your PATH.

1. Download the Ruby Installer.

For developing Java servlet-based web applications, I prefer the startup speed of Jetty combined with the configurability of Apache. This tutorial describes how I connect Jetty and Apache through mod_jk in a development environment.

Installing Jetty

To use the Windows NT service, we need the Jetty "extra", package. Download the distribution from the downloads page on the Jetty Web Site. This can be either a tarball or a zipped archive.

Unzip the archive to c:\jetty. The zip structure has an internal folder structure, so the final location will be c:\jetty\jetty-%VERSION%.

Setting up the Windows Service

The Windows Service is configured by customizing the extra/win32/wrapper.conf file. The following lines should be inserted in their logical positions (i.e. config.3 comes after config.2 and config.1).


wrapper.java.classpath.3=../resources

wrapper.logfile=d:/www-logs/jetty-wrapper.log


There are a few things to note in the configuration changes above. First, the Jetty STDOUT log has been directed to our universal logging directory at d:/www-logs/jetty-wrapper.log. Secondly, we're not using the default admin.xml and jetty.xml locations. We've pointed those to our universal configuration directory at d:/www-config. We'll cover the contents of the jetty.xml file later.

After applying the changes to the wrapper configuration, the NT service is installed with the wrapper.exe application. Run the following commands from the extra/win32/ directory.


wrapper -i wrapper.conf


Jetty Server Configuration: jetty.xml

As mentioned earlier, the primary Jetty configuration file, jetty.xml, has been moved to a new location in our setup. For the most part we copy the settings in the default jetty.xml. Be sure to enable the AJP13 listener. This is how Jetty supports mod_jk.





8009
5
20
0
443





No other changes are strictly required, but I'll include the following as an example of a web application context.




/tempo
d:/projects/exampletarget/webapp-stage



Jetty can now be started and stopped with the Windows net command. As long as Jetty is running, it will accept properly configured mod_jk requests sent from Apache.


net start jetty
net stop jetty


I don't normally host production web sites with Apache running on Windows. However, I develop primarily on a Windows machine, and Apache's configuration options are far superior to IIS. Things like mod_rewrite and wildcard configuration files greatly simplify the development cycle for me.

I've put together this tutorial to explain how I have set up my Apache2 environment in Windows. This setup should be easy to modify to fit several different strategies.

Installation Process

Apache's automated installer works very well now. I do not recall exactly, but I believe my last install used all default settings, with the exception of the install path (I use c:\apache\%VERSION% instead of the c:\Program Files mess).

Post-Install Configuration

Apache's configuration begins with the httpd.conf file, which is located at %APACHE_DIR%\conf on Windows systems. I typically make several changes to this file, and then use wildcard imports to bring in virtual hosting directories and other optional hosting features.

The first change is to add a wildcard Include at the top of the file. This will bring in optional functionality (PHP, JK, etc). I would prefer this statement to come at the bottom, but mod_jk requires a specific loading order in the Apache config. Note that the .conf files are stored on the D drive. This separates them from the operating system, easing the setup for re-installs/crashes of the Windows hard drive.


Include "d:/www-config/*.conf"


Other documents on this site describe the contents of the .conf files.

Next, set up the DocumentRoot directive to a location on the D drive as well. Replace the default DocumentRoot value with the one below.


DocumentRoot "d:/www"


Then point the logs to a unified logging directory, also on the D drive. Replace the default ErrorLog and CustomLog entries with those below.


ErrorLog "d:/www-logs/apache-error.log"

CustomLog "d:/www-logs/apache-access.log" combined


Lastly, I like to host development projects in aliased subdirectories. I've found that wildcard Includes work well for this task. I add one to the last line of httpd.conf.


Include "d:/www-config/vhost.*"


Despite the name, the vhost.* files do not contain Apache <VirtualHost> entries. Here is an example file.


Alias /projectname d:/projects/projectname/target/webapp-stage


Order Allow,Deny
Allow from All



Apache's web site has its own Windows hosting guide. It is much more extensive than this tutorial, so check it out.

I found this article:

http://www.thompsonbd.com/chris/tutorials/apachessl.html

The convert command can convert FAT or FAT32 drives to NTFS drives. http://www.microsoft.com/technet/prodtechnol/winxppro/maintain/convertfat.mspx

I am currently setting up my Acer TravelMate 800 with Windows XP. I am planning to install the OS, all necessary updates, WinRAR and Norton SystemWorks. I'll then make a Norton Ghost image to save the base install state (with both Windows XP and Norton Utilities activated).

Windows XP was installed with my Version 2002 disc. After completing the install, I used the Acer installation discs to install all drivers. A restart is required after most of the drivers. Norton Systemworks Premier was installed and activated. I ran Windows Update and Norton LiveUpdate repeatedly until no more updates were available. I then ran a full Norton Antivirus scan and installed WinRAR.