I double-checked the owners and permissions of all the directories in question and everything was identical to how things are set on another RHEL VM in this cluster on which I haven't upgraded Tomcat and done the reconfiguration yet. I was at a bit of a loss, so I googled around a bit and the prevailing sentiment seemed to be this was related to either A) a config file copied from a Windows box and the line breaks were throwing things off (wasn't applicable in my case), or B) the fact that SELinux was enabled.

If you've been around the Red Hat flavors of Linux long enough you'll remember that SELinux used to be absolutely horrible. For years the very first thing you had to do on Red Hat and Fedora to get anything working at all was turn SELinux off, and for a long time I believe it was even Red Hat's recommendation under their breath to just shut it off. It's gotten better over the years, and honestly stays out of the way to the point where I'd almost forgotten about it.

Since I didn't have anything else to try, however, I went into /etc/sysconfig/selinux and changed SELINUX=enforcing to SELINUX=disabled, restarted the server, and voila the complaining from Apache went away.

What I still don't get is A) why this isn't occurring on my other RHEL box with the same setup, and B) why it just started happening now. The only potential weirdness here is that my document root is a symlink, but again, it's been that way since I setup up these boxes originally and it hasn't been an issue.

So if you run into this same problem the fix (at least until I have more information about why it's happening) is to disable SELinux, but if anyone has more ideas about why this might be happening I'd love to hear them.

• Tomcat committer
• tc Server developer
• responsible for keeping tc Server and Tomcat in sync
• memory leak detection in tomcat manager app
• recent logging improvements
• simplifying jmx access
• all of the above started in tc Server, but have been contributed back and implemented these features in tomcat
• don't want to get into having a significant fork of tomcat

• load balancer (round robin) -> httpd (sticky sessions) -> tc Server (clustered)
• don't go anywhere near tc Server clustering unless you absolutely have to--adds complexity and overhead
• only thing tc Server clustering gives you is the ability for users not to lose sessions if an instance of tomcat goes down
• ask yourself how big of a deal it is if your users lose their sessions when an outage occurs--if it's a big deal then you may need clustering

• ubuntu 8.04.4 64-bit VM
• vmware tools installed
• 64-bit sun jdk 1.6.0_21
• will be installing tc Server, Hyperic, etc. on this clean image

• don't run tc Server as root
• create a tcserver user
• owns the tc Server files
• runs the tc Server processes
• install to /usr/local/tcserver

• think about this in advance--may wind up with 100s of instances
• tc01, tc02, etc. as the instance name, then follow this for ports
  
• example scheme for ports
  
• 1NN80 - http
• 1NN43 - https
• 1NN09 - ajp
• 1NN05 - shutdown (if used)
• 1NN69 - jmx
• server and jvmRoute naming--consider linking server name to IP address, e.g. srvXXX-tcYY where XXX is the end of the IP address, YY is the tomcat instance number
  
• 1NN20 - cluster communication

• tc Server version names are e.g. apache-tomcat-6.0.29.A.RELEASE where the first part is the version of Tomcat, the "A" means it's the first release of tc Server based on that tomcat release
• if shutdown port is disabled, doing a kill -15 does a graceful shutdown. kill -9 works too and tomcat won't care, though your application might, so only do -9 if you have to
• created two instances of tc Server using the tc Server create instance script
• tc Server comes with templates for startup scripts--copy these over to /etc/init.d and edit as needed
• paramterize cluster addresses and ports in a catalina properties file
• can use ${...} notation in server.xml to hit the properties in catalina.properties

• switching to static node membership
• cumbersome for large clusters
• remove the <Membership .../> element
• need to add a bunch of config stuff after the <Interceptor .../> elements
• easier to use dynamic node discovery
• backup strategies -- tomcat gives you DeltaManager and BackupManager
• delta manager is simplest--replicates every session to every node in the cluster
• if your sessions use a lot of memory, delta manager doesn't give you much scalability
• if your limitation is CPU, delta manager gives you some scalability
• amount of network traffic on delta manager increases with the square of the number of nodes--not terribly scalable
• backup manager
• replicates session data to one other node in the cluster
• send options: synchronous vs. asynchronous
• in synchronous, writes session changes to other nodes, waits for acknowledgement, and then sends response to the user. can mean a lag for the user.
• asynchronous -- changes to sessions are put on a queue and the user gets the response immediately. means there's a chance that the cluster will be in an inconsistent state. use of sticky sessions means the consistency of the cluster doesn't really matter.
• because java thread running isn't deterministic, in asynchronous mode the session updates may not be processed in the same order in which they were placed on the queue, so if your application depends on these being processed in the same order this is a risk
  
• no need for the WAR farm deployer -- hyperic does this better
• WAR farm deployer has been removed from tc Server
  
• backup manager DOES know where the primary and backup nodes ARE for every session
• i.e. it doesn't actually store all the sessions from all nodes, but it knows where to get the session it lost
• backup manager scales much better than delta manager in both memory and network traffic
• network traffic scales linearly with number of nodes
• for availability on a small cluster, use the delta manager
• if you're worried about scalability, go with the backup manager
  

• create an hqs user
• hqs user owns the hyperic hq agent files
• the agent itself runs as the tcserver user
• os security considerations
• agent doesn't need root privileges to access OS mechanics, start/stop processes, etc.
• tc Server needs to be able to read WAR files uploaded via the agent
• don't want tc Server runtime running as root
• hyperic security considerations
• don't want agent connecting as hqadmin super user
• create a dedicated agent user
• requires create, modify, and delete privileges for platform and platform services only
  

• ERS = Enterprise Ready Server
• SpringSource's distribution of Apache httpd
• install ERS as root
• httpd processes run as nobody:nobody so this is fine
• remove the test instance
• create a new instance
• module configuration
• enable mod_proxy_balancer
• enable mod_proxy_ajp
• mod_proxy_ajp isn't quite as stable vs. mod_jk and mod_proxy_http
• mentioned something about mod_http now having remote IP addresses available--need to ask about this
• configure balancer in ers
  

<Proxy balancer://tc>
  BalancerMember http://ip.address.here:port route=tc01-uniqueID
  BalancerMember http://ip.address.here:port route=tc02-uniqueID
</Proxy>
 
ProxyPass /cluster-test balancer://tc/cluster-test stickysession=JSESSIONID:jessionid
ProxyPassReverse /cluster-test balancer://tc/cluster-test

Debugging Clusters

• need something in your apps that tells you which cluster node you're on
• also need something to spit out the session ID so you can test that the sticky sessions are working
• if your context path differs from your host name in tc Server, this may cause your cookies not to work since the hosts are different
• can use cookiepath in proxypassreverse directive
• easier: just have your context path match your host name
• anything you want replicated in sessions has to be serializable
• if your application can't support having everything in the session be serializable, terracotta will support non-serializable data in session replication
  

Starting httpd: httpd: apr_sockaddr_info_get() failed for host.name.here
httpd: Could not reliably determine the server's fully qualified domain name, using 127.0.0.1 for ServerName

The second part of that error is pretty common (and nothing to worry about most of the time), but I hadn't seen that first error message before.

A bit of scroogling and experimenting led to the solution quickly enough so this is another one of those "so I don't forget" blog posts more than anything, but hopefully it'll help someone else who runs into this.

In my case the server's host name didn't have a corresponding DNS entry yet, so to resolve the error I simply added the server's host name to /etc/hosts and pointed it to 127.0.0.1.

Of course depending on your situation you may want a DNS entry too, but I tend to have all the host names for the server itself in the hosts file on the server so it doesn't have to do a DNS lookup only to find itself. Particularly when you're behind a load balancer things get weird if you don't leverage your hosts file.

This came up a couple of times on mailing lists recently, and since it's something I sometimes forget to do when I set up new Windows servers with Apache, I figured I'd document it here.

If you're running into stability problems with Apache on Windows and can't switch to Linux, doing the following seems to help quite a bit.

First, find these lines in your httpd.conf file and uncomment them:

EnableMMAP off
EnableSendfile off

Then right below those lines, add this line:

 Win32DisableAcceptEx
 

Particularly if you're seeing errors along the lines of "The specified network name is no longer available. : winnt_accept: Asynchronous AcceptEx failed" or "The semaphore timeout period has expired. : winnt_accept: Asynchronous AcceptEx failed" that last line should eliminate those errors.

If you're interested in learning more about what's behind these errors, there's a nice post about it on the "My Digital Life" blog.

A few quick tips if you find yourself having to access a network drive from Apache and Tomcat on a Windows Server. This is all pretty much old hat but since I still get questions about this fairly regularly and was just setting up some things on some servers this weekend, I figured I'd write this up.

In my situation we're running an application on three VMs behind a load balancer, and users can upload files from the application. Since I didn't want to set up a process behind the scenes that copied uploaded files between all three servers (though it would have given me a chance to take another run at using Unison), we have an uploads directory living on a SAN. This way no matter which VM the user is on, the uploads all go to and are served from a single file system.

On Windows Server, by default services run under the Local System Account, which doesn't have access to network resources. So if you install Apache and Tomcat as services and expect to be able to point them to a UNC path for some of your content, that won't work out of the box. You need to be running Apache and Tomcat under an account that has network access. In most environments in which I've worked this type of account is typically called a "service account," because you'll end up getting a domain account just like your typical Active Directory user account, but of course it won't be associated with a human being.

Once you have that account in place, you go into your services panel, right click on the service, click on "Properties," and then click the "Log On" tab. You'll see by default the Local System Account radio button will be checked. Click the radio button next to "This Account," enter your service account information, click "OK," and then restart the service. At this point your service will be running under the service account and will have access to network resources. Note that you'll have to do this for each service that needs access to the network drive, which in my case meant doing this for both Apache and Tomcat.

That takes care of the web server and things at the Tomcat level in terms of basic access, but you'll likely be configuring an alias of some sort to point to the network drive. In my case I wanted /uploads to point to \\server\sharename\uploads, which meant setting up an alias in Apache, a Context in Tomcat, and a mapping in OpenBD. This is where a lot of people get confused, so I'll go through each of these settings one by one.

The necessity for a web server alias is probably pretty obvious. If you're serving an image directly from your web server, e.g. http://server/uploads/image.gif, if /uploads doesn't exist under your virtual host's docroot, then Apache will throw a 404.

Allowing Apache to access the network drive involves (depending on how you have Apache configured) using a Directory directive to give Apache permission to access the directory, and then an Alias directive so Apache knows where to go when someone requests something under /uploads. So the following goes in your virtual host configuration file:

<Directory "\\server\sharename\uploads">
  Order allow,deny
  Allow from all
</Directory>

Alias /uploads "\\server\sharename\uploads"

You may have other stuff in your Directory directive as well but that's the basics of what will allow Apache to see /uploads as the appropriate location on your SAN.

The next layer down will be your CFML engine. Remember that if in your CFML code you want to read or write files to /uploads, even though Apache knows what that is now, your CFML engine will not. I'm emphasizing that point because it's such a common source of confusion for people. If things are happening in your CFML code, it won't be interacting with Apache at all, so it won't know about the Alias you set up in Apache. Simple enough to solve with a mapping; just go into your CFML engine's admin console and create a mapping that points /uploads to \\server\sharename\uploads and that handles things at the CFML level.

Lastly comes Tomcat. Depending on how you're serving files, you may be proxying from Apache to Tomcat, so if Tomcat needs to know where /uploads lives, since it's not in the webapp's base directory Tomcat will throw a 404 unless you tell it where /uploads is located.

Tomcat doesn't have Aliases in the same way Apache does, but what you can do in Tomcat is configure multiple Contexts under a single host. So in Tomcat's server.xml (or in a separate host config file if you prefer), you simply add a Context that points /uploads to the network location:

<Host name="myapp">
  <Context path="" docBase="C:/location/of/my/app" />
  <Context path="/uploads" docBase="\\server\sharename\uploads" />
</Host>

So now you have things set up in such a way that Apache, your CFML engine, and Tomcat all know where /uploads really lives.

Another point of confusion for people on Windows is the concept of "mapped drive" letters. A lot of people think that if you map \\server\sharename to a drive letter of let's say D:, than in your code you can then access the uploads directory we've been using as our example via D:\uploads.

The simplest way to explain why this doesn't work is to point out that mapped drive letters are associated with a Windows user account. They don't exist at the operating system level. While you may remote into the server using your credentials, map to a network location, and assign that to drive letter D:, another user logging in won't see that mapping, and services running on the server under various user accounts definitely won't know anything about mapped drives.

This is why in all the examples above you see the full UNC path to the network resource being used. You have to use the UNC path in order to get this all to work correctly because that's the only way services running under a service account will be able to address the network resource.

Hope this helps eliminate some of the persistent confusion I see around this issue.

I'm setting up some new servers with some semi-complex URL rewriting and proxying going on of both the HTTP and AJP varieties. For this particular application the home page is actually a completely separate application that's running as its own webapp on Tomcat, and everything else runs from within the webapp itself. (I'll spare you the details; just assume I'm not insane and this was the best way to handle this situation.)

So for all this to work properly I have the following rewrite rule:

RewriteRule ^/$ http://otherapp/ [NC,P]
ProxyPassReverse / http://otherapp/
 

Then below that I have a bunch of AJP rewrites for the webapp itself. What was throwing me fits was that everything was working great except for this one rewrite rule, which would attempt to load indefinitely until I killed the request.

I stared at my virtual host config file for quite a while and finally paused on this line:

ProxyPreserveHost On

Given that the ^/$ rewrite rule is proxying out to a different host, it seems kind of obvious now that of course that would confuse Apache. Removing that line and adding some aliases for the other host's CSS and images directory did the trick.

Maybe no one else will be in this exact situation, but if you're ever faced with a blank white screen while waiting forever for an HTTP proxy to go through, this tip might come in handy.

First, in case some of you aren't using Mura but are reading out of general interest in URL rewriting (get a life! ;-), let's take a look at Mura URLs. Mura URLs are in the format http://server/siteid, where 'siteid' is an actual physical directory on disk. Since Mura is built on CFML it uses a directory index file of index.cfm, so when you hit http://server/siteid it's the equivalent of hitting http://server/siteid/index.cfm. The presence of a .cfm file is what triggers Apache to hand off the processing of that file to the CFML engine. This is rudimentary stuff I realize, but that index.cfm bit is important in this case since that's what we're going to be eliminating from the URL.

Pages other than the site index page in a Mura site have URLs along the lines of http://server/siteid/index.cfm/page-name, and the 'page-name' bit is not a directory or file on disk since all the Mura content is contained in the database. So if my site ID is 'foo' and my page name is 'bar', the URL for the 'bar' page would be http://server/foo/index.cfm/bar What I'd like my URL to be for that page, however, is http://server/foo/bar, so I want to eliminate index.cfm from the URL.

The solution for this is to use URL rewriting in your web server, which in my case is Apache and mod_rewrite. Using URL rewriting I can have the web server match certain URL patterns and translate these patterns into something different behind the scenes so things still work properly. So in this case I need a rewrite rule that will take the URL http://server/foo/bar and treat that as if it were http://server/foo/index.cfm/bar. Otherwise, Apache would be looking for a directory 'bar' under the 'foo' directory, which of course doesn't exist, so it would throw a 404.

Many of the URL rewrite examples I came across were designed for Mura sites that are also eliminating the site ID from the URL. This is all well and good, but since I'm working on an intranet site we want to keep the site IDs in the URLs (e.g. http://server/department), so that meant most of the examples I saw weren't quite right for my needs.

The tricky part (at least for me as a relative mod_rewrite amateur) is that instead of being able to say "take my server name, add 'index.cfm' to that, and then tack on the rest of the URL being requested," I had to take the first part of the URL being requested (the site ID, which again is a physical directory), then insert index.cfm, then tack on the rest of the URL being requested (i.e. everything after the site ID in the URL).

This is actually pretty easy if you want to create a rewrite rule for each site ID on the server, but that would mean additional Apache configuration and an Apache restart every time a new site is added to Mura. That seemed like a maintenance nightmare to me so I decided to try to come up with a solution that would handle eliminating index.cfm regardless of the site ID.

What I ended up doing was cobbling together several of the other great resources linked above for many of the other considerations with rewriting for Mura, and then came up with a rewrite rule that will leave the site ID in place, then add index.cfm, and then tack on the rest of the URL being requested.

Quite a lot of preamble for a one-line rewrite rule, but here it is in all its gory glory:

RewriteRule ^/([a-zA-Z0-9-]{1,})/(.*)$ ajp://%{HTTP_HOST}:8009/$1/index.cfm/$2 [NE,P]

Translation:

• Create a backreference match for alphanumeric characters and hyphens in the URL up to the first / (these are the allowed characters in Mura site IDs)
• Create a second backreference for everything else in the URL
• Proxy this to port 8009 on the server (since I'm using AJP proxying with Tomcat), but make the URL backreference 1 + /index.cfm/ + backreference 2
  

There are a few other rewrite rules involved to get this all working when you take into account things like image files, etc., and as I said above I'm standing on the shoulders of giants (thanks guys!), so here's the full set of rewrite rules:

  ProxyRequests Off

  <Proxy *>
    Order deny,allow
    Allow from 127.0.0.1
  </Proxy>

  ProxyPreserveHost On
  ProxyPassReverse / ajp://your-host-here:8009/

  RewriteEngine On
 
  # if it's a cfml request, proxy to tomcat
  RewriteRule ^(.+\.cf[cm])(/.*)?$ ajp://%{HTTP_HOST}:8009$1$2 [P]
  
  # if it's a trailing slash and a real directory, append index.cfm and proxy
  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
   RewriteRule ^(.+/)$ ajp://%{HTTP_HOST}:8009%{REQUEST_URI}index.cfm [P]

  # if it's a real file and haven't proxied, just serve it
  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f
  RewriteRule . - [L]
 
  # require trailing slash at this point if otherwise valid CMS url
  RewriteRule ^([a-zA-Z0-9/-]+[^/])$ $1/ [R=301,L]

  # valid cms url path is proxied to tomcat
  # MUST COME AFTER ANY OTHER FIXED/EXPECTED REWRITES!
   RewriteRule ^/([a-zA-Z0-9-]{1,})/(.*)$ ajp://%{HTTP_HOST}:8009/$1/index.cfm/$2 [NE,P]

Note that you can put the rewrite rules in a .htaccess file or in the virtual host configuration file. I prefer having the rewrite rules be defined as part of the virtual host, so in my case I have all this in the <VirtualHost> block in my virtual hosts config file. (I have a bunch of other stuff in the virtual host configuration as well but I left everything other than the parts relevant to the URL rewriting out to avoid any confusion.)

That's it! I hope that helps others looking into doing this with Mura, or that you at least learned a few things about mod_rewrite along the way.

I'll spare you all the gory details but yesterday afternoon--a mere few hours before I was set to do the cutover--ISAPI Rewrite started choking hard. I started getting "Bad Request (Request header too long)" errors, but only some of the time even on the same URL, so I hacked the registry as recommended by Microsoft in an attempt to fix it. That was followed with "Bad Request (Invalid Header Name)" errors, which led to another registry hack. This seemed to fix things for a while, but then suddenly IIS would stop responding and throw one of these two errors if I had any rewrite rules enabled. Things continued a downward spiral from there. I even tried installing the older version of ISAPI Rewrite but that would immediately throw a 500 error whether or not any rewrite rules were enabled.

Needless to say I had to cancel the migration, and after the problems with ISAPI Rewrite I had absolutely zero confidence in that solution. There was no way I could move forward knowing that at any moment and without reason the whole thing would come crashing down.

I don't like being backed into a corner, particularly by Windows, so I shut down IIS and installed Apache. This app has a ton of server configuration to it but once I don't trust something I simply can't use it, so the configuration work on the Apache side would be beyond worth the effort since I'd wind up with a solution I can trust. (I would have chucked Windows altogether but not really my call in this case, and given that I'm under a bit of a time crunch that was one more variable I didn't need in the mix right this second.)

Here's the steps I went through, and it actually was easier than I thought it would be.

Download and Install Apache

Actually first, make sure to shut down IIS and set the startup to "Disabled" in your services panel. Now that I have everything set up I'm going to uninstall IIS entirely, but it was handy to have around for a bit so I could fire it up and go into the IIS admin console to check my settings as I moved things to Apache.

So grab the Windows version of Apache (make sure and grab the version with SSL if you need it), run the installer (which takes all of about 10 seconds), and tell it to run as a service for all users. Next make sure when you hit localhost in your browser you get Apache's "It works!" message. Congratulations, you just freed yourself from IIS.

Connect ColdFusion to Apache

This server is running ColdFusion 8 Enterprise, and the OS on the new VM is Windows 2003 64 bit. The easiest way to hook CF into Apache is to open the Web Server Configuration Tool, which is under Start -> Programs -> Adobe -> ColdFusion 8. Since I had previously connected CF to IIS, when I launched the Web Server Configuration Tool it indicated that "localhost:cfusion" was hooked into IIS. I clicked that entry to select it, then clicked "Remove."

Next I clicked "Add" and waited about 60 seconds, and you'll see the "Add Web Server Configuration" screen. Choose the JRun Server you want to hook to Apache from the drop-down (if you have more than one), and choose "Apache" from the Web Server drop-down. Click the "..." box next to the "Configuration Directory" box and browse to your Apache conf directory, check the box "Configure web server for ColdFusion 8 applciations," and MAKE SURE to check the "Configure 32 bit webserver" box. I don't know this for a fact, but I'm pretty sure Apache for Windows is 32-bit. So even though I'm on a 64-bit box, when I didn't check that box Apache wouldn't start. This could be because I need a different version of the JRun shared object ... who knows. Apache's running great so at least at this point I don't have much motivation to look into it.

Also, click on Advanced, click on the "..." box next to "Directory and file name of server binary," and point to your httpd.exe. This way CF can restart Apache after it modifies your Apache conf file.

That's it--pretty simple stuff. Delete the IIS entry, add one for Apache, and you're done.

Basic Apache Terminology

Before moving forward with the specifics of the configuration, if you're used to IIS terminology like "web site" and "virtual directory," you'll be happy to know all that stuff exists in Apache, but it's called something different and of course you'll be editing a config file instead of clicking through configuration wizards. I prefer the directness of the config file approach anyway, and I bet many others will too once you get the hang of it.

Here's the basic terminology mapping between IIS and Apache:

• a "web site" in IIS is a VirtualHost in Apache
• a "virtual directory" in IIS is an Alias in Apache
• a "home directory" in IIS is a DocumentRoot (or docroot) in Apache
• a "host header" in IIS is a ServerName or ServerAlias in Apache
• a "default document" in IIS is a DirectoryIndex in Apache
  

Before digging into Apache, at a high level all I did to convert things over was to open up IIS Manager and make note of all my "web sites" and their home directories. These will become virtual hosts and docroots in Apache. Next, in each IIS site take a look to see if you have any virtual directories defined. If so, make note of these--they'll become Aliases in Apache.

With that basic information in hand you're ready to configure Apache.

Apache Configuration Files

One of the things I absolutely love about Apache is that you do all your configuration in configuration files. Once you get the hang of this approach, there's just nothing simpler than being able to open a file and make the changes you need instead of clicking through a mess of popup windows to find the one setting you need to change.

The main two configuration files that most people will need are httpd.conf and extra/httpd-vhosts.conf. These are both under the Apache conf directory. httpd.conf is the main configuration file where you set server-wide configuration details. You can actually shove everything in this one file, and that's how things were done in older versions of Apache, but it's much cleaner to keep things in different files and simply enable these additional files within the main configuration file.

I won't give you the full tour of httpd.conf since the docs do a very nice job of that, but I will go over what you'll likely need to edit in order to get things working the way most people want.

Going top to bottom in httpd.conf, the first thing you'll likely want to do is enable some modules. Specifically in this case since I know I'm going to be doing rewriting and proxying, I need to enable those modules since they're turned off by default. In the long list of LoadModule statements in httpd.conf, you'll want to uncomment (i.e. remove the #) these lines:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule rewrite_module modules/mod_rewrite.so

Next, if you're doing CFML stuff you'll want to add index.cfm as a DirectoryIndex, so find this section and update accordingly:

<IfModule dir_module>
  DirectoryIndex index.cfm index.html
</IfModule>

You can have as many directory indexes as you want, just separate with a space and realize they will get hit in the order in which they're declared.

Finally, you'll want to enable name-based virtual hosting so you can have multiple virtual hosts sharing the same IP address. Towards the bottom of httpd.conf, find this section and uncomment the Include directive that will load the virtual hosts configuration file. When you're done it should look like this:

# Virtual hosts
Include conf/extra/httpd-vhosts.conf

Save httpd.conf, and now let's take a look at how to configure your virtual hosts.

Virtual Host Configuration

Open up conf/extra/httpd-vhosts.conf so we can configure some virtual hosts. You'll be spending a lot of time in this file as you use Apache. First, make sure this line right after the big comment block at the top is uncommented:

NameVirtualHost *:80

This enables name-based virtual hosts for all IP addresses on port 80. Next you'll see a couple of examples of virtual hosts. You can either delete those or comment them out by putting a # on each line. I tend to leave them in there but comment them out for reference.

For your first virtual host, let's set one up for localhost because (at least in my experience) once you enable name-based virtual hosting, you have to have a virtual host even for localhost. Add the following section, adjusting the DocumentRoot as needed based on where you installed Apache:

<VirtualHost *:80>
  ServerName localhost
   DocumentRoot "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/htdocs"
</VirtualHost>

Save the file, and then restart Apache just to make sure all the changes we've made are working. If Apache doesn't restart don't panic, that just means you have a syntax error somewhere. Double-check everything and try again. If you can hit localhost in your browser and see "It works!", well, that message says it all I guess.

Note that if you have multiple IP addresses on your machine and want to tell a virtual host to use a specific IP, or if you want to run a site on a port other than 80, you can replace the * with an IP, and the 80 with whatever port you need.

Next let's configure a more real-world virtual host. I'll be using foo.com as my example, and we'll want people to be able to hit the site using foo.com or www.foo.com. I'm also going to tell Apache to use a log file specific to this site to make diagnosing problems and doing reporting easier. There are a few other things in here that I'll explain in a moment.

<VirtualHost *:80>
  ServerName foo.com
  ServerAlias www.foo.com

  DocumentRoot "C:/path/to/foo"

  Alias /CFIDE C:/path/to/CFIDE
   
  <Directory "D:/path/to/foo">
     Order allow,deny
    Allow from all
  </Directory>

  CustomLog "logs/foo-access.log" common
</VirtualHost>

The ServerName and ServerAlias information is pretty self-explanatory--foo.com is the primary name for this virtual host, but with the alias of www.foo.com, either foo.com or www.foo.com will hit this virtual host.

DocumentRoot tells Apache where to find the files that it will be serving when someone hits this virtual host.

I threw an Alias in the mix simply to show how "virtual directories" (in IIS speak) work. Let's say in this case I want foo.com to have access to my CF administrator or maybe the javascript files that are stored in the CFIDE directory, but that CFIDE directory is not inside this host's docroot. The Alias directive tells Apache that when someone is requesting /CFIDE on this virtual host, those files will actually be served from somewhere outside the virtual host's docroot.

The <Directory> directive requires a bit of explanation. For security reasons, by default all directory access (other than the default localhost site) is denied by Apache. This is done in the main httpd.conf file, so you can either make the change there, or I prefer to do this on a case-by-case basis inside each virtual host. In the case of a public site you won't know where people are coming from so you have to tell Apache to allow access to that directory from anywhere, which is done with the "Allow from all" line. I left this out, but note that you will likely have to add a <Directory> entry for the C:/path/to/CFIDE directory as well.

Finally, I tell Apache to create an access log specific to this site instead of using the global Apache logs.

For a lot of virtual hosts that's literally all there is to it. But since what started this whole process was rewriting issues, let's take a look at some of the cool things you can accomplish (and shoot yourself with) by using mod_rewrite.

URL Rewriting and Proxying

For the app in question we do a lot of URL rewriting and proxying so we can give the users a single site that actually is comprised of multiple sites, potentially on different physical servers. This is also a great way to handle long-term migrations where you have a legacy server that you don't really want to touch but still need content from, and you want to add a newer server in the mix.

As with everything else related to Apache this is powerful stuff, but the basics are relatively simple. I do love this quote from the mod_rewrite docs, however:

"The great thing about mod_rewrite is it gives you all the configurability and flexibility of Sendmail. The downside to mod_rewrite is that it gives you all the configurability and flexibility of Sendmail.''

Let's start with a basic rewrite rule, and then we'll look at what I have to do a lot of which is proxying. Let's say for whatever reason in the foo.com virtual host you want requests to foo.html to actually hit bar.html. First we need to enable the rewrite engine in our virtual host, so inside your <VirtualHost> block, add this line:

RewriteEngine on

Next we add a simple RewriteRule to tell requests for foo.html to be rewritten to bar.html:

RewriteRule /foo.html /bar.html [NC]

The [NC] bit at the end stands for "no case," so that way both foo.html and FOO.HTML will be rewritten to bar.html. There are a ton of flags to do various things outlined in the docs, and if you want some nice rewrite example examples they have those too.

So far so good? Next let's tackle proxying. Instead of a simple rewrite from foo.html to bar.html, let's say you want everything under a particular directory to be proxied to another server. To make the example more concrete, let's say your company has an intranet on one server and an employee directory that runs on another server, but you want people to be able to access the employee directory directly from your intranet. If you wanted to do a simple redirect from http://intranet/empdirectory to http://empdirectory, that's simple enough:

RewriteRule ^/empdirectory(.*) http://empdirectory$1 [NC,R]

The (.*) after /empdirectory will include anything that comes after /empdirectory, and this is tacked onto the end of the remote URL via the $1. The "R" flag tells Apache to do a redirect for this RewriteRule, and you can even set the status code for the redirect. This does change the URL in the user's browser, however, so what if you didn't want that to happen? This is where proxying comes in.

First, we change the "R" flag to a "P":

RewriteRule ^/empdirectory(.*) http://empdirectory$1 [NC,P]

Now we're proxying instead of doing a redirect (and note that mod_proxy needs to be enabled to use the P flag, which is why we did that earlier), but if this is all you do you'll notice that the URL in the browser still changes. This is because there's nothing in place to handle proxying the response back to the requestor. So we need to add a ProxyPassReverse directive, which will allow us to hit http://intranet/empdirectory and keep that URL while the content is actually served from http://empdirectory.

RewriteRule ^/empdirectory(.*) http://empdirectory$1 [NC,P]
ProxyPassReverse /empdirectory http://empdirectory

With all this in place you can serve content from another server without your users knowing they're hitting another server.

There are about a million and one other things you can do with mod_rewrite, but my only intent with this post was to share what I had to do in my specific move from IIS to Apache in the hopes it might help others who want to make this move.

Conclusion

Even though it was under duress, I'm honestly glad ISAPI Rewrite totally failed since that led me to setting up Apache on this box. After seeing ISAPI Rewrite have its various meltdowns I simply would not have felt comfortable using it. I'm sure I could have contacted support and gotten things figured out eventually, but it took me far longer to write this blog post than it did to switch to Apache, particularly since the rewrite syntax of ISAPI Rewrite is largely compatible with Apache's. I'm going to sleep much better at night knowing Apache is powering this app instead of being constantly worried that ISAPI Rewrite will have another meltdown.

I should have made this disclaimer at the beginning but I am in no way an Apache expert, so if there are different or better ways to do any of this, if anything is explained poorly or incorrectly, or if I omitted any important details, please comment.

File this one under "you can't win 'em all," or "hell has frozen over," or take your pick (though I refuse to file this under "hat eating" because it isn't a change of opinion, it's just a necessity in this case). Since I'm having to go through and set up Apache 2.2, Tomcat 6.0, and Open BlueDragon on a Windows 2003 Server, I figured I'd make lemonade and write up a step-by-step for those of you stuck in the same situation. So here's how to install all this very cool stuff on a very uncool operating system.

(If you prefer to read this in Google Docs, here's the link.)

All these steps should also work on Windows XP or Vista, which is handy for development purposes if you're on a Windows box, but again I can't really verify. If you're using XP I strongly, strongly encourage you to at a minimum install Apache as your web server. The version of IIS that comes with XP only allows you to use one web site, which for web developers simply isn't acceptable and in my opinion shields people from how things actually work in the real world. Sermon over.

Mac users--you will probably be able to follow along nearly line-by-line on this as well. It seems that the Mac install of Apache is nearly identical to the one on Windows (Apache on Linux is a bit of a different beast), and by default all the proxying stuff we're going to be using is enabled on the Mac. Not sure that's the greatest idea, but that's the way it seems to be on the Mac.

Before digging in, note that there's a LOT going on here, and that you'll reach a couple of points along the way where you may think, "It's working! I don't need to read the rest!" And if that particular setup works for you, that may be true. Realize, however, that even though later steps may supersede earlier ones, this is by design to give people a bit of a crash course in the various options involved and how they all work together. And you might want to read to the end to change a couple of settings so your server doesn't crash all the time. Seriously.

Also note that if you're here to learn how to use Tomcat and OpenBD with IIS, I can't help you. I have to draw the line somewhere. In all seriousness though, if someone has tips on getting IIS hooked into Tomcat I'd love to point people to it; I just don't personally have the experience to help people with that and won't be digging into IIS in this sort of setup. Ever. If you absolutely MUST embark on this fool's errand, here's some instructions that may help. Break a leg (or your registry).

So grab a cup of tea, coffee, beer, curare, or whatever floats your boat and let's do this thing.

Installing Apache 2.2

First, ensure that IIS is not installed, or at a minimum that it's not running and that you have the startup for the IIS service set to "disabled." This is probably obvious, but Apache will be your web server running on port 80, so if IIS is also running on port 80 you'll have a bit of a problem. I personally recommend uninstalling IIS altogether because you won't need it, and if you need other IIS-related services like FTP, there are much better options out there such as Filezilla Server.

Next, head over to http://httpd.apache.org/download.cgi and grab the "Win32 Binary MSI Installer." If you need SSL, make sure and grab the one that has OpenSSL included.

With Apache downloaded, run the installer, entering the appropriate information as you go. Note that for the rest of this how-to guide I'm assuming you installed Apache at C:\Program Files\Apache Software Foundation\Apache2.2, which is the default. I'll refer to this using {APACHE_HOME} for short, but where the full path is specified, if you installed Apache elsewhere you'll have to make the necessary adjustments.

At the end of the installation process you'll have Apache running as a Windows service, serving up HTTP traffic over port 80. Hit http://localhost just to make sure it's working. If you see this, you're golden:

If you don't see that, uninstall and give it another shot. Next we'll need Java.

Installing Java

Since Tomcat relies on Java to run, grab the latest Java SE Development Kit (JDK) from Sun's web site. As I'm writing this the latest version is JDK 6 Update 13. Make sure to get the JDK, not just the JRE. Download the installer, run it, and accept all the defaults or put Java in your preferred location; it makes no difference since we'll be pointing Tomcat directly to Java anyway. As long as you don't get any errors as you go, this step is done.

You may already have Java on your machine. That's fine, as long as it's Java 6 Update 10 or later since previous versions of Java had the classloader bug that made CFC performance not so great. If you have an older version now's a good time to upgrade.

Also a general note about Java since in my experience there seems to be some confusion in this area. You can have as many different versions of Java on your machine as you want. They don't conflict, they don't overwrite each other, they don't get in fights and cause your machine to crash. They just sit in a directory and are used by various application as needed. Now you may have specified a PATH and CLASSPATH in your environment variables that point to a particular version, and that's fine, because we will be pointing Tomcat explicitly to the version of Java we want it to use.

Installing Tomcat

For those of you used to using Adobe ColdFusion, you may not be familiar with what Tomcat is. Tomcat is a Java servlet container, meaning it can serve up Java web applications, and ultimately it's where we'll be deploying OpenBD. CFML engines are nothing more than Java web applications, so even if you install Adobe CF you're getting JRun, which is a JEE server as opposed to a servlet container, but the differences are unimportant for our purposes. So even though you aren't having to install it yourself, you still wind up with a "java server" on which the CFML engine is deployed.

To install Tomcat, go to the Tomcat download site and grab version 6.0.18 (most current as of this writing) of the "Windows Service Installer."

Note that since Tomcat runs on Java you can actually grab any download you want and it will work, but the Windows Service Installer is what you'll want on a production Windows server so Tomcat is installed, as the name implies, as a Windows service. This also gives you a little monitoring tool that lets you click buttons to stop and start Tomcat as opposed to having to--the horror--type a command in a terminal.

After the download, run the installer and again you can accept the defaults for the most part. During the installation process you will provide Tomcat with a user name and password. This is used to access the Tomcat Manager, and we'll cover that in a moment.

The installation will also prompt you for the location of Java on your machine. Although based on what I read Tomcat 6 can run on either a JRE or a JDK, personally I point Tomcat to the JDK as opposed to a JRE. This is perhaps out of habit since older versions required a JDK, but if you do use the JRE realize you may need to set slightly different variables if you start messing with your settings, specifically JRE_HOME instead of JAVA_HOME. Unless you have a reason not to, I'd recommend pointing to your JDK directory, which you downloaded and installed in the step above.

When the install is done you likely will want to go into your services panel and set Tomcat to start automatically when the machine boots. By default it's set to manual startup.

If everything went well and you didn't change the default port from 8080, which I don't recommend doing unless you really need to, you can now browse to http://localhost:8080 and see this:

As with the previous steps if something went awry, uninstall and give it another shot. In my experience this all does go quite smoothly though.

Accessing the Tomcat Manager

Since you provided a user name and password for the Tomcat Manager as part of the installation process, you can browse to http://localhost:8080/manager/html and log in.

It ain't fancy, but it does let you see what applications are deployed, active sessions, and some other good information. You can also reload individual web applications from the manager, which is handy if one app needs to be reloaded due to code changes or problems and you don't want to impact all the other applications on Tomcat.

So far so good? Excellent! (You did answer in the affirmative, correct?) Let's get our OpenBD on.

Installing OpenBD

As I said above, OpenBD and all CFML engines are Java web applications, so with Tomcat up and running the "install" of OpenBD is really just a deployment of the OpenBD Java web application, or WAR (which stands for Web ARchive. Yeah, I know--slick acronym eh?).

Much as people complain about the complexities of Java, deployment is one thing Java got 100% right in my opinion. WAR files are actually ZIP files that contain a deployment descriptor, which means any Java server that adheres to the Java standards (and they all do) will understand what a WAR file is and what to do with it. There are differences in how the specific Java servlet container or JEE server will handle the WAR, but we won't dig into that here. Just know that a WAR file is a standard in the Java world, and it means dead-simple deployment. Copy a single file to the right place and your application is deployed.

So where do we get this WAR file? Why from the OpenBD download page of course!

You can grab the latest stable (1.0.1 as of this writing) or the nightly build; either will work fine. Just make sure to grab the WAR file and not the Ready2Run or source code versions. (In case you're interested, the Ready2Run version of OpenBD is a pre-configured version of Jetty, another servlet container, with OpenBD already deployed.)

With the file downloaded, we now need to deploy it. Tomcat does auto-deployment of any WAR files that are dropped in its webapps directory, so copy the downloaded openbd.war file into {TOMCAT_ROOT}/webapps. Note that for the rest of this how-to guide I'm assuming you did NOT rename the WAR file. This is important once we get into URLs, context paths, and the other fun that comes later. If you know what you're doing and want to call it something else that's fine, just make the necessary adjustments as you go through this.

After copying the WAR file to Tomcat's webapps directory, give Tomcat a few seconds to do its deployment magic. If you're watching the directory you'll notice that an openbd directory will be created automatically; this is Tomcat expanding the WAR file. That's it, you just deployed a WAR file.

You may now browse to http://localhost:8080/openbd and you'll see OpenBD's test page:

Congratulations! You now have an instance of OpenBD running on Tomcat.

But what about Apache as the web server? Why is there a port number and that silly "/openbd" bit in the URL? Glad you asked, because the rest of this guide deals with making our base install more "production ready."

Virtual Hosts in Apache

Strictly speaking you don't need to use Apache as your web server. Tomcat has a very nice, very fast, production-quality HTTP connector called Coyote built in, and I'll probably cover using Tomcat without Apache in another blog post at some point. It does simplify the overall setup and if you don't need what Apache has to offer, it's one less moving part in your setup.

That being said, there are plenty of reasons to use Apache. Whether it's familiarity, or you need to run Perl, PHP, etc. on the same physical box as OpenBD, or you need Apache features that don't exist in Tomcat's web server, it's not at all uncommon to use Apache as the front-end web server in a setup like this.

The first thing we'll cover as far as Apache configuration goes is virtual hosting. Simply put, virtual hosting is the way you tell Apache to respond to different host names (e.g. foo.com vs. bar.com) on the same IP address. In IIS speak these are called "web sites," and it's the exact same concept. This is very handy for both production servers and development environments, so as a web developer you owe it to yourself to become well-versed in configuring virtual hosts.

By default virtual hosts are disabled, so the first step is to enable them. Open up {APACHE_HOME}/conf/httpd.conf, which is the main Apache configuration file, in a text editor. Scroll down towards the bottom of the file and look for the line

"# Virtual hosts" (without the quotes), or you could also do a search for that text. The line immediately following is "#Include conf/extra/httpd-vhosts.conf" (again without the quotes).

As you might guess, this directive includes the file conf/extra/httpd-vhosts.conf. The # is a comment in the Apache configuration file, so just delete the # from the Include line (NOT from the # Virtual hosts line since that actually is just a comment line), and save the file.

Any time you edit any of the Apache configuration files you need to restart Apache, but hold off on that for a minute because we have another file to edit. Now that we have virtual hosts enabled, which is what uncommenting the line in the last step accomplished, we need to configure a virtual host for localhost, because otherwise Apache won't know what to do when we ask for localhost in our browser.

Open {APACHE_HOME}/conf/extra/httpd-vhosts.conf in a text editor. At the bottom of that file you'll see some existing <VirtualHost> blocks. You can leave those as is for reference or delete them; at a minimum I'd say comment them out by adding a # to the beginning of each line, but even if you don't they won't be hurting anything.

After the existing <VirtualHost> blocks we're going to add a new one of our own. So add a couple of line breaks to the end of the file, and type the following:

<VirtualHost *:80>
    ServerName localhost
    DocumentRoot "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs"
</VirtualHost>

Let's explain this a bit. The VirtualHost part is probably obvious; you're just telling Apache that you're defining a virtual host. *:80 means "this virtual host applies to all IP addresses on this server for requests that come in on port 80." If you have specific IPs you need to worry about, you just replace the * with an IP address.

ServerName is the host name that comes to Apache as part of the HTTP request, and this server name will be checked against the host name in the request to see if it's the one that needs to handle the request. In this case we're specifying localhost, but you can imagine for a "real" site that would be something like mydomain.com. Note that if you also want this virtual host to respond to other host names, you can use multiple ServerAlias lines, e.g. ServerAlias www.mydomain.com. And finally, DocumentRoot is the path to the root of this virtual host, meaning where the virtual host's files are located.

Note that even though this is Windows we're using forward slashes (/) in the docroot path as opposed to backslashes (\). I think you may need to escape the \ by doubling them up if you choose to use those, so I'd recommend using forward slashes instead, even though that my look odd in a Windows path.

There are numerous other options involved with virtual hosts, so if you want to learn more (and you likely will), be sure and peruse the Apache docs on virtual hosts.

Save the httpd-vhosts.conf file, and at this point you can restart Apache from your Services panel. To restart Apache you can also right-click on the Apache icon that got installed in the lower right of your system tray (or whatever the heck it's called on Windows), choose "Open Apache Monitor" and then click the Restart button.

After the restart, hit http://locahost in your browser to make sure everything is still working.

That's all well and good but at this point we still don't have Apache and Tomcat on speaking terms. There are many ways to accomplish this, so let's look at one now.

Basic HTTP Proxying With mod_proxy

The idea behind proxying is, as the term itself implies, configuring Apache to serve as a go-between that handles requests coming into your web server and hands them off to Tomcat. Note that this is a bit different than the perhaps more familiar scenario of letting the web server handle the static content and only leveraging the CFML engine to do the CFML processing based on file extension. You can do things this way as well, but personally I prefer the proxy route because I find it simpler and more flexible. If you're famliar with mod_proxy and HTTP proxying, and you're thinking "but the performance sucks!", A) it doesn't really suck that badly, and B) we'll go a different route in a bit.

Done wrong proxying can be very dangerous so I strongly encourage you to read the Apache docs on mod_proxy. Call my old-fashioned but I like reading the manuals for things I use, at least to the point where I'm dangerous and can write up long blog posts teaching other people to be equally dangerous.

By default mod_proxy is disabled (unless you're on a Mac), and the default settings when you do enable it are safe, but as with everything if you don't know what the pitfalls are you can get into trouble. Specifically make sure you always have ProxyRequests set to Off, which it is by default, so I'm merely reiterating how important this is. If you set ProxyRequests to On, you may wind up with an open proxy server and the miscreants trolling the tubes LOVE open proxy servers.

So let's throw caution to the wind (seriously, it'll be fine) and enable mod_proxy. To accomplish this, navigate to {APACHE_HOME}/conf and open up httpd.conf in a text editor. Scroll down and look (or do a find) for "#LoadModule proxy_module modules/mod_proxy.so" (without the quotes) and uncomment that line.

This only enables the base Apache proxy module, which is necessary for all proxying, but there are add-on modules that handle specific kinds of proxying. At this point we want to do HTTP proxying so we'll need to enable the HTTP proxy module. This allows HTTP requests coming into Apache to be handed off (or "proxied out") to Tomcat. Scroll down a bit more (it's about 5 lines further down in my conf file) and find "#LoadModule proxy_http_module modules/mod_proxy_http.so" Uncomment that line, and save the file.

Don't restart Apache just yet--there's one more step involved.

Proxying to OpenBD From Apache

This is the moment you've all been waiting for (and if I didn't include all my poor attempts at witticism we would have gotten here sooner): we're now going to proxy to OpenBD from Apache. What this will do is eliminate the need to use the port and context path in the URL.

In order to accomplish this we simply need to add a new virtual host to Apache that proxies to OpenBD. Remember that virtual hosts are used to allow Apache to respond to multiple host names, and within each virtual host block we provide settings specific to that virtual host.

Navigate to your {APACHE_HOME}/conf/extra directory and open httpd-vhosts.conf in a text editor. We created a virtual host for localhost earlier so this should be semi-familiar. Scroll to the bottom of the file and add the following virtual host:

<VirtualHost *:80>
    ServerName openbd.local

    ProxyRequests Off

    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>

    ProxyPass / http://localhost:8080/openbd/
    ProxyPassReverse / http://localhost:8080/openbd/
</VirtualHost>

Let's look at the new information in this virtual host as compared to the simpler one we created for localhost. The basic VirtualHost, *:80, and ServerName pieces should make sense. Just note the ServerName, which indicates we'll be calling our OpenBD instance via the host name "openbd.local".

Starting with ProxyRequests is where things get interesting. ProxyRequests Off is telling Apache not to proxy requests. Now this may seem like a misnomer, because we are going to be proxying requests, but not in the way that is enabled by setting ProxyRequests to On. By setting ProxyRequests to On, you are allowing Apache as a whole (or a specific virtual host in this case) to act as a forward proxy server. This is bad unless that's really what you want, which 99.9% of the time it isn't. We will be proxying requests but setting ProxyRequests to Off does not disable the ability to use the ProxyPass directive, which is what we'll be using.

The <Proxy *> block tells Apache that it will be proxying all requests for this virtual host. As you can imagine, and as with everything related to Apache, you have a lot of granular control here, but for our purposes we're going to proxy everything out to Tomcat for this virtual host.

Within the <Proxy> block you can allow and deny traffic so you could, for example, only allow proxying if the request is coming from a specific IP or range of IPs. This refers to the remote client IP, so for publicly available sites this means that you have to allow proxying for requests coming from any IP address.

The Order directive dictates the order in which requests will be allowed or denied to proxy. By specifying an order of deny,allow we're telling Apache to process the Deny directives first, then the Allow directives. We aren't specifying any Deny directives in this case, but we do specify an Allow directive of "Allow from all" which, as I mentioned above, is necessary since on a web server we typically don't know where requests will be coming from. Of course if you do know where requests will be coming from and you want to limit access by subnet or something along those lines, this is a handy way to accomplish that.

Bottom line here is we're telling Apache to allow proxying for all requests that hit this virtual host. Check the Apache docs for more info on the Proxy directive, as well as the mod_authz_host docs for more info on the Order, Allow, and Deny directives.

Finally, we need to tell Apache specifically where it will proxy to as requests come in. Remember above when we hit our OpenBD test page with the URL http://localhost:8080/openbd? Well that's the same URL we're going to tell Apache to use when someone makes a request for the virtual host openbd.local. This is accomplished using the ProxyPass and ProxyPassReverse directives.

ProxyPass is the forward proxy action. The / following ProxyPass tells Apache that all requests that come into the virtual host, regardless of subdirectories, etc., are to be proxied to http://localhost:8080/openbd/ Please note the slash at the end of the proxy URL! Things don't work properly without that.

ProxyPass gets requests from Apache to Tomcat, but we also need to do the opposite, meaning proxy the response from the OpenBD webapp on Tomcat back to Apache. This is done via the ProxyPassReverse directive, and as the name indicates this is a way for Tomcat to hand things back to Apache. Technically speaking at that point, Apache is acting as a reverse proxy for Tomcat to proxy Tomcat's response back to the client.

Lots of explanation for a few lines of configuration ... bottom line is that now Apache and Tomcat are now communicating with one another. Make sure and save your httpd-vhosts.conf file before proceeding.

The last step here is to add an entry for openbd.local to your hosts file so you can hit that URL and have it resolve to an IP address. Open up C:\Windows\system32\drivers\etc\hosts in a text editor, add a line for 127.0.0.1 openbd.local and save the hosts file.

Lastly, restart Apache if you haven't already, and you can now hit http://openbd.local and see the OpenBD test screen. Make note of the CGI variables being dumped on the OpenBD test screen, however, because HTTP proxying is not without its limitations.

Proxying to OpenBD From Apache using Apache JServ Protocol (AJP)

At this point we have Apache passing the entire HTTP request off to Tomcat for processing. As you might guess this isn't the most efficient way of doing things, since the HTTP request is being passed around in all its uncompressed, plain text glory. That being said, I've seen perfectly acceptable performance with HTTP proxying, so if you're a wimp and want to stop there us cool folks who are going to forge ahead will forgive you.

The great thing about technology, and particularly open source, is that someone always invents a better mousetrap. In the case of proxying, that better mousetrap comes to us in the form of the Apache JServ Protocol (AJP for short). As the name indicates AJP is a protocol just like HTTP, but it's certainly not a common one since its sole purpose is to facilitate communication between Apache and Tomcat. Purpose-driven solutions do solve specific problems quite well, however, and AJP is no exception.

Why is AJP better than HTTP proxying? First and foremost it performs better. AJP enables binary, packet-based TCP connectivity between Apache and Tomcat so it's fast. This is in contrast to the plain-text format of HTTP. Using AJP, Apache can also maintain an open connection with Tomcat which avoids the expensive process of a new socket being opened for every request. This can mean you'll have more connections open, but it also means better performance.

Concerning CGI variables, with HTTP proxying things can get a bit weird. When you have Apache talking to Tomcat instead of the client (meaning a web browser) talking directly to Tomcat, it's probably not surprising that some of the CGI variables get lost due to the proxying, specifically these:

• Remote Client IP (CGI.REMOTE_ADDR) -- this becomes CGI.HTTP_X_FORWARDED_FOR


• Host name requested by the client (CGI.REMOTE_HOST) -- this becomes CGI.HTTP_X_FORWARDED_HOST, but note that you can use the ProxyPreserveHost directive to retain the remote host


• Host name of the proxy server -- this becomes CGI.HTTP_X_FORWARDED_SERVER

In addition to performance advantages, AJP also retains all of the original CGI variables by default. There are still some CGI problems, however, specifically with CGI.PATH_INFO, and this can wreak havoc with SES URLs that rely on this CGI variable. We'll address that a bit later. Just know that if you need important CGI variables like those listed above, they are retained by AJP. You can get the full skinny on AJP in the AJP docs.

Luckily since we already have the basic pieces for proxying in place, making the switch to AJP is pretty simple.

First, navigate to {APACHE_HOME}/conf and open httpd.conf in a text editor. Find the line "#LoadModule proxy_ajp_module modules/mod_proxy_ajp.so" and uncomment it. While you're in there you can disable HTTP proxying by commenting out the HTTP proxy line, but note that you DO need the base mod_proxy module enabled to do any proxying, which includes AJP. Having HTTP proxying doesn't hurt anything other than perhaps causing Apache to take up a bit more RAM, so either leave it enabled or disable it if you choose.

Once you have the AJP module enabled, save the httpd.conf file, but before restarting Apache we have to modify our virtual host settings as well.

Since AJP is its own protocol, you're probably already guessing that the http://localhost:8080/openbd/ bit in our proxy settings from above will no longer work (or won't be using AJP at any rate) since it's proxying over HTTP. To use AJP we have to make some adjustments in our virtual host settings, so open up {APACHE_HOME}/conf/extra/httpd-vhosts.conf in a text editor. Find the <VirtualHost> block we added above for HTTP proxying, and change it to the following:

<VirtualHost *:80>
    ServerName openbd.local

    ProxyRequests Off
    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>

    ProxyPass / ajp://localhost:8009/openbd/
    ProxyPassReverse / ajp://localhost:8009/openbd/
</VirtualHost>

Pretty darn similar! The only alterations we need to make here are to change the protocol from http:// to ajp:// and change the port from 8080 to 8009. AJP is built into Tomcat and enabled out of the box, so with Tomcat running it's already set up to respond to AJP requests on port 8009.

Save your virutal hosts file, restart Apache, hit http://openbd.local again, and be in awe at the tremendous speed increase. OK, hitting it yourself you might not notice, so just have faith that AJP is indeed going to be a more performant choice than HTTP proxying.

What you will want to make note of on the OpenBD test page is the CGI variables dump. The X_FORWARDED... CGI variables we saw when using HTTP proxying are now gone, and the normal CGI variables are back with their proper values.

But wait! There's more! Things may seem to be working OK at this point (and really they are for the most part), but we still have the little matter of the context path to worry about since it will cause issues in certain scenarios.

Context Paths in Java Web Applications

Let's take a brief detour to discuss context paths in Java web applications, and be aware that this will be far from a complete guide to this topic. I'm only going to explain what I think is the minimum required knowledge so we can understand what issues might come up related to context paths and how we can address them.

As we saw when we first deployed OpenBD on Tomcat what seems like several days ago (how long is this how-to guide anyway?), we accessed Tomcat directly via a URL containing port 8080, but also containing /openbd at the end. The openbd part of the URL is what in the Java web app world is called a context path, and it corresponds to the physical directory name in which the web application is deployed. There is a single ROOT web application in Tomcat that is the one web application that is absent a context path, and you'll see this in action by hitting http://localhost:8080, which displays the welcome page. If you look inside the ROOT directory under Tomcat's webapps, this is where you'll see the code and images for the Tomcat welcome page.

You can certainly run OpenBD as the ROOT application in Tomcat. By deleting the existing ROOT directory, renaming the openbd.war to ROOT.war, and dropping it in Tomcat's webapps directory, you would have an instance of OpenBD running as your ROOT (meaning "context path-less") application in Tomcat. I've found in my own use of Tomcat, however, that I prefer to have my applications isolated as opposed to leveraging a single web application on Tomcat for all my CFML applications, hence why I didn't just tell you to put OpenBD on Tomcat as the ROOT application to begin with.

Since everything is hitting Tomcat on port 8080, you can think of the context path as similar to putting subdirectories in the root of a web server and hitting everything by referring to the server name follows by the subdirectory name. Looking at it from the front end this makes sense; you have /openbd in your URL, and that corresponds to a directory in the docroot of Tomcat. Simple enough. From the backend perspective, however, things work a bit differently, because the backend code isn't really aware of the fact that it's inside this context path.

Let me explain by using the example of creating an instance of a CFC. Consider running this line of CFML within our /openbd context path:

<cfset foo = CreateObject("component", "path.to.Foo") />

As long as inside your openbd directory you have path/to/Foo.cfc, this code will work. Note that you did not have to refer to the CFC by using openbd.path.to.Foo. This differs from a plain old web server, because if you have an openbd directory under your docroot on a web server, and you don't have any virtual hosts dictating different behavior, you would have to use openbd.path.to.Foo to get to that CFC. Since openbd is our context path in this case, and by default an application inside a context path cannot see outside its context path, the area immediately inside the openbd directory is the root of the application as far as the backend code is concerned.

So far so good? Let's examine things from the front end of the equation again. Where things get tricky is with regular front-end assets like images, stylesheets, javascript files, etc. This is because where things like image paths are concerned, the context path does come into play since it's part of the request coming from the client. So whereas path.to.Foo works for a CFC inside the context path, <img src="/path/to/image.jpg" /> will not work; in this case you would need to use <img src="/openbd/path/to/image.jpg" /> instead. The killer is the initial / in that image path. To backend code, / resolves to immediately inside the context path. To front-end code, / resolves to one level above the context path, i.e., to the root of Tomcat as a whole.

How do we resolve this? More importantly, does it even matter? If you've used / in all your front-end code thinking that will get you to the root of your application, then it will definitely matter. If you've left that initial / off all your image, css, etc. paths, then you're safe ... for now. You'll still have problems when we do the last few steps in our setup however, specifically where SES URL parsing is concerned.

Why am I rambling on about all this stuff and having you perform certain steps only to have you change things immediately thereafter? Partially to torture you, sure, but mostly it's because I personally like going through things very systematically so I really understand what's going on and why I am doing each step, not to mention what the pros, cons, and consequences of making various decisions are. Also because if you go through things this way and survive, I hope you truly understand what's going on so you can A) address problems as they arise, and B) extend this knowledge as your configuration needs change.

Our next step--and luckily for both of us it's the penultimate step--is to create a virtual host in Tomcat to set the stage for our final configuration.

Configuring Virtual Hosts in Tomcat

As stated near the beginning of this how-to guide, Tomcat contains a full-blown web server, but we haven't touched that piece of things yet. Since we're interested in removing the context path from our equation, however, we now need to do just a small bit of configuration to Tomcat's HTTP connector. Check out the Tomcat docs on virtual hosting if you want to learn all about configuring virtual hosts in Tomcat, but for the purposes of this how-to guide we'll keep it very simple.

To review what we're doing and why we're doing it, on Tomcat we're going to set up a virtual host so we can point a host name within Tomcat to a specific directory as its root and not have to worry about the context path. The context path doesn't show up in the URL anymore given how we're proxying, but as described above it can still cause issues. Creating virtual hosts in Tomcat is actually very similar to how it's done in Apache; we simply edit a configuration file and restart Tomcat.

Navigate to {TOMCAT_HOME}/conf and open server.xml in a text editor. Scroll down towards the bottom of the file or search for the line beginning with <Host name="localhost"

Scroll down a bit more to find the closing </Host> line, which should be right before a </Engine> line. Right after the </Host> we're going to add a new host to Tomcat as follows:

<Host name="openbd.local">
    <Context path="" docBase="C:/Program Files/Apache Software Foundation/Tomcat 6.0/webapps/openbd" />
</Host>

And that's all there is to it. This is a bit different from virtual host configuration on Apache, but it's probably similar enough that you can see what's going on.

The name attribute in the <Host> tag will be the host name that this host will respond to, which is the equivalent of the ServerName in Apache. Note that the host name on Tomcat does not need to be identical to the host name on Apache since we'll still be proxying to Tomcat from Apache explicitly (we'll see that in a second). In the <Context> tag we set the context path to ""--meaning it won't have a context path!--and since we're losing the context path we need to tell Tomcat where to find the files for this host, which is the path indicated in the docBase attribute. Note again here we're using forward slashes in our Windows path.

Save the server.xml file and restart Tomcat. You can restart Tomcat via your services panel, or Tomcat has a configuration application similar to the Apache configuration application. If you don't already have it in your system tray, go to Start -> All Programs -> Apache Tomcat 6.0 -> Monitor Tomcat. This will cause a second icon to appear on the right-hand side of your system tray. One of these is for Apache, the other is for Tomcat. Right-click on the one for Tomcat and click on "Stop Service." Give it a few seconds, then right-click again and click on "Start Service." (Yeah, doing this from the Services panel is probably easier.)

After Tomcat restarts, check that things are working by hitting http://openbd.local:8080 in your browser. You should see the OpenBD test page.

The context path is now gone thanks to our host on Tomcat, but we're still hitting Tomcat using the port in order to bypass Apache, which lets us make sure our Tomcat virtual host is working properly. This method of hitting Tomcat remains available even once we hook Apache and Tomcat together, and it's a handy way to test Tomcat without going through Apache. If you ever run into any issues, this can help you troubleshoot which piece of your setup is having problems.

Finalizing the Apache Virtual Host Configuration

By now you're an old hat with this. There's one more tweak we need to make to our virtual host on the Apache side to get it talking to our newly created host on Tomcat. Open up Apache's httpd-vhosts.conf ({APACHE_HOME}/conf/extra/httpd-vhosts.conf) in a text editor and find the openbd.local virtual host we've been editing. All we need to do now is point to the Tomcat host instead of localhost and the context path:

<VirtualHost *:80>
    ServerName openbd.local

    ProxyRequests Off

    <Proxy *>
        Order deny,allow
        Allow from all
    </Proxy>

    ProxyPass / ajp://openbd.local:8009/
    ProxyPassReverse / ajp://openbd.local:8009/
</VirtualHost>

We're still using AJP, and still proxying in the same way, but now we're hitting our Tomcat virtual host without using a context path instead of ajp://localhost:8009/openbd/ as we were before. Note that we still need the port for proxying, but this won't show up in the browser since it's all done behind the scenes.

Save the file, restart Apache, and now--FINALLY!--you can hit http://openbd.local in your browser and see the magic working. The browser talks to Apache, Apache talks to Tomcat, Tomcat does its thing with OpenBD, and all is right with the world.

You're done now! Unless you want to learn the secrets of using CFML-based SES URLs that is ... and oh yeah. You'll want to read the last bit so Tomcat won't crash the second it's under load. (Do I know how to keep you reading or what?)

Search Engine Safe (SES)/Search Engine Friendly (SEF) URLs

This is a bit of a tangent, but some applications and frameworks in the CFML world do their own version of SES/SEF URLs using the CGI variable CGI.PATH_INFO. Well, with all this proxying going on, rather than go into the gory details allow me to summarize: this won't work. Since I'm most familiar with Mach-II's use of SES URLs (although BlogCFC and many other CFML applications do the same thing), I'll use Mach-II as my example to illustrate the problem.

If you enable SES URLs in a Mach-II application, the URL http://localhost/index.cfm?event=foo becomes http://localhost/index.cfm/event/foo. This request will make it through Apache just fine since Apache's not going to handle the request anyway, but once it hits Tomcat and OpenBD, you'll get a 404 because strictly speaking that path doesn't exist, and without us telling the server to translate CGI.PATH_INFO into something that OpenBD can comprehend and handle, it just won't work properly.

All is not lost, however. OpenBD ships with a SearchEngineFriendlyURLFilter and enabling it is as simple as uncommenting a chunk of XML in a configuration file, which if you've stuck with me this long, you're an expert at.

Head over to {TOMCAT_HOME}/webapps/openbd/WEB-INF and open the web.xml file in a text editor. Right inside the <web-app> node you'll see a chunk of XML that begins with the following:

<!--
    Uncomment the configuration of this filter in order to support search engine
    friendly URLs like http://127.0.0.1/bdj2eeregr/index.cfm/path/info. />
So do what the man (er, file) says and uncomment that chunk of XML! I just move the close comment (-->) up to right below the paragraph of explanatory text so I have the paragraph of text intact. Save that file and restart Tomcat, or you can navigate to Tomcat's web-based manager and reload the openbd webapp individually (see "Accessing the Tomcat Manager" above if you need a refresher on that).

Mission accomplished, you now have SES URL capabilities thrown into the mix.

One more tip I'll throw in for free: If you enable SES URLs you may notice you still have problems with things like image paths resolving correctly. Things like <img src="path/to/my/image.jpg"/> will definitely cause issues because based on the SES URL, it will be looking for images in the wrong place.

OpenBD has a nice quick fix for this. Just throw <cfbase> (yes, that's a real tag in OpenBD) in your HTML page's <head> block, and like magic the problem is solved. You can read up on <cfbase> on the OpenBD wiki.

Now, for the final act, let's give Tomcat enough breathing room so it doesn't crash when you try to us it in production. (Aren't you glad you read this whole thing?)

One More Thing ...

Java loves memory. By default Tomcat is given 64MB of memory. Is this a problem? You bet your overflowing stack it is. But luckily it's easy to fix.

On other operating systems you would get the pleasure of editing another text file, but on Windows you get a GUI to accomplish this task. Go to Start -> All Programs -> Apache Tomcat 6.0 -> Configure Tomcat. Click on the "Java" tab and you'll see this screen:

The settings at the bottom are the ones we're concerned with.

• "Initial memory pool" (equivalent of -Xms in JAVA_OPTS)


• "Maximum memory pool" (equivalent of -Xmx in JAVA_OPTS)


• "Thread stack size" (equivalent of -Xss in JAVA_OPTS)

In most cases you should only have to worry about the first two. All the reading I did on thread stack size basically said "don't worry about it unless you have a problem," so that's good enough for me.

So how much memory should you give Tomcat? Well buddy, how much RAM you got? Seriously though, particularly if you're going to be running Tomcat as the main application on a server, I'd give it as much RAM as you can. On a 32-bit machine with 2GB of RAM (just for a point of reference), I'd set the initial memory pool and the maximum memory pool both at 1024MB. If you have 4GB available, you can probably go 1.5 times that (realize as you approach 2GB allocated to 32-bit Java you're hitting its limits), but Tomcat seems to run pretty darn well in 1GB depending on how much you're hammering on it. If you're on 64-bit adjust accordingly.

Why set both the min and max memory settings to the same value? The theory is that you'll get better performance because Java's going to take up all the RAM it will ever use right when Tomcat fires up as opposed to having to grab more memory as the load increases. Also, if Java tries to grab memory at runtime and that memory isn't available, bad things may happen. Some people also believe that garbage collection runs more efficiently when the min and max memory settings are the same. I've had good luck with setting these to be the same so that's what I tend to do.

So set those values, hit "Apply" or "OK," and then restart Tomcat. You're now production ready.

If you're interested in learning more about Tomcat memory settings and issues, you can read more in the Tomcat Memory FAQs. I particularly enjoy the answers to the "Why do I get OutOfMemory Errors?" question. So helpful, and yet so snarky!

What About mod_jk?

If you're totally sadistic, you may want to dig into mod_jk. Then again, if you really need mod_jk, chances are you care enough to not be using Windows. If you're interested in mod_jk on Linux, check out Dave Shuck's blog. Either he's way crazier than I am or I'm way lazier than he is. This how-to guide's long enough as it is, so maybe I'll cover mod_jk another time. I personally like AJP proxying (and mod_jk actually uses AJP as its protocol) because it's fast, flexible, and easy to set up, but there are cases where mod_jk will be a better (or necessary) choice, e.g. more advanced load balancing, if you need support for larger packet sizes, etc. For now we'll leave it alone. You can thank me later.

Common Errors

Probably the most common error you'll see as you make configuration changes to your setup is 503 errors from Tomcat. This seems to be related to the fact that since we're using AJP, the connection to Tomcat can stay open so it doesn't restart correctly. That's largely anecdotal evidence, but I've even seen cases where according to the Windows service panel Tomcat wasn't running, but it was still serving up requests just fine. A restart of Tomcat, or Apache, or sometimes both usually fixes this issue.

Other than that I really haven't run into any additional problems enough to call them "common errors." It really is a nice, flexible, fast, powerful, and darn stable setup overall.

Where to Go From Here

Even with all this information this is only the tip of the iceberg in terms of what you can do with this setup. I didn't get into mod_rewrite at all, I only scratched the surface in many of the other areas, and I didn't even mention about 95% of what Tomcat and Apache can do, so I strongly encourage you to read the docs or get a good Tomcat book; I like Professional Apache Tomcat 6 (Wrox), but Tomcat: The Definitive Guide (O'Reilly) is good as well.

Thus endeth the lesson. I hope those of you who survived found it helpful. If there are any errors, incoherencies, or other suggestions you have to make this guide better, please let me know.

We now return you to your non-Windows operating system.

Comments