Custom 404 pages with ColdFusion 8, MacOS X and the difference with IIS

For one of the projects we are working on (news will be revealed very soon) we will need to redirect a clean URL like “http://www.mydomain.com/mybox” to a certain record.

Of course, our first thought was that it is easy to create a custom 404 page, add this to the web server configuration, get the query_string and do some stuff with it. Easy right?

Well, in our findings we see that Apache 2.2.6 gives us a empty query_string, where as IIS on Windows Server 2003 returns a nicely formated query_string in the form of “404;http://www.mydomain.com:80/mybox”. Needles to say, that this posts a challenge since we would need to have the “mybox” part of the URL to make something meaningful with it.

Here are the following steps to make this work on Apache.

1. Create a custom 404 page

Simply create a new ColdFusion page. We called ours “404.cfm” and put it in the web root (or in the root of your host directory). Within the template add a <cfdump var=”#cgi#”> or a #cgi.query_string#.

2. Add this to the httpd-vhosts.conf file

Since we are working with different local hosts we are changing the virtual host directives, this gives you a additional value to have custom 404 error pages for each host. If you don’t need that or simply want to have a general 404 page then edit the httpd.conf file and change or add the line “ErrorDocument 404 /404.cfm” (around line 414 in the httpd.conf file).

For virtual hosts do the same, but simply put this line “ErrorDocument 404 /404.cfm” within the virtualhost directive!

3. Restart Apache and test

Within the terminal restart Apache with “/usr/sbin/apachectl restart”. Now surf to the URL “http://www.mydomain.com/mybox”. Do you land on your custom 404.cfm page? If so, you should see a empty “query_string”. If you get an error instead of your page, make sure that you have done step 1 and 2 correctly.

Ok, once it is working we can now get on with the show. That is, we will need to get the rewrite module working. Without it enable, you will never get the query_string value filed. Good thing is, that Apple included Apache 2.2.6 and already compiled it with the rewrite module. If your installation varies or you try this on another Apache version then make sure you compiled Apache with the rewrite module.

4. Check for the rewrite module

Again go into your httpd.conf file and look for the line “LoadModule rewrite_module libexec/apache2/mod_rewrite.so”. Make sure it is NOT commented (that means, is does not have a “#” in front of it).

You will also need to look for the line “AllowOverride None” (about line 210) and change it to “AllowOverride All”.

Save and close httpd.conf.

5. Create a .htaccess file

This part is the key to all of the above. Create a new file, called “.htaccess” and put it in the directory of your 404.cfm page. within the .htaccess file add the following lines:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (.*) /404.cfm?%{REQUEST_URI}

This will make sure that the complete URL string gets passed to your 404 page and thus in the cgi.query_string scope.

6. Restart Apache and test

Within the terminal restart Apache with “/usr/sbin/apachectl restart”. Now surf to the URL “http://www.mydomain.com/mybox”. You should see the “mybox” part now in the query_string.

That’s it. Hope this helps some others as we have spent quite some time figuring this out.