URL Rewriting allows you to recode ugly URLs like
into something like
…while having a valid url…
…still passed to ColdFusion or your coding language of choice. Using the url examples above I will take you through implementation of rewriting in Apache with mod_rewrite and in IIS using a plugin ISAPI_Rewrite.
Implementation
To cater for URL Rewriting, you’ll need to add a “plugin” for your web server. URL Rewriting has been a de-facto standard on Apache for years, but has yet to reach mainstream acceptance in Microsoft’s IIS.
Apache
On Apache, you have the infamous mod_rewrite
IIS
On IIS, there are a number of mod_rewrite clones, either free or for a fee. As of this writing we’ve settled on ISAPI_Rewrite. Previously we used Ionic’s Isapi Rewrite Filter, but it had problems handling encoded URLs, specifically URL’s with % signs in them. The syntax employed by these plugins is mostly standard across the plugins, so you can almost always use the same code form mod_rewrite in the IIS plugins too.
Installation
By default, on my installation of Apache, mod_rewrite was installed but not enabled. So first, let’s check if it’s enabled. Look for the following line in your httpd.conf file:
If there’s a hash (#) at the start of the line, remove the hash, save the file, then restart your Apache service. You’re all set.
Configuration
To enable URL rewriting on specific domains, add the following configuration within the corresponding sections in your httpd.conf file. Unfortunately we couldn’t get it working everywhere just by pasting the code at the bottom. More information on how to structure your rules and how to write the following can be found at the RewriteRule man page.
Don’t forget to restart Apache again when you’re done. Notes
- On Apache, you have to specify “RewriteEngine On” before your RewriteConds and RewriteRules. You don’t need to do this for the ISAPI_Rewrite.
- From our own trial and error, it appears you have to have the flag at the end of every RewriteRule line to have rewriting work, otherwise you get weird 403/404 errors from Jrun.
- We used to have additional config that checked for physical files before rewriting. This has been removed for consistency with ISAPI_Rewrite, since it lacks this ability.
ISAPI Rewrite on IIS
ISAPI_Rewrite (http://www.helicontech.com/) is an ISAPI filter for IIS that allows rewriting of URLs. There’s two types of installation listed here. The first is the initial setup that only has to be done once for IIS. The second has to be done for EVERY new site you set up in IIS.
Initial Installation
Download “ISAPI_Rewrite Full” Installation is pretty straightforward. Using this installation, the software is installed in trial mode by default, that stops working after every 200 rewrites (after which you have to restart IIS).
Trial mode also disables the ability to apply the filter to individual sites. To have it work normally you’ll have to purchase a registration code (You want “ISAPI_Rewrite Full”, not the “ISA” one).
After I’d installed it myself the first time, the files under C:\Program Files\Helicon were all read only. Right click on the Helicon folder in a windows explorer window, click Properties, and make sure the Read-only checkbox isn’t ticked. If it is, untick it and apply it to all files and folders inside.
While you’re in the Properties window for the Helicon folder, click the Security tab and give SYSTEM full control over the folder. This is a crucial step! Once that’s out of the way, copy and paste this:
…at the end of httpd.ini (which is under C:\Program Files\Helicon\ISAPI_Rewrite\ by default).
Now go into IIS, right click on the root “Web Sites” folder, click Properties, and click on the ISAPI Filters tab. The installation should have added the ISAPI_Rewrite filter here automatically, but this isn’t where we want it.
Click on the ISAPI_Rewrite row, click Remove, and click OK to exit the Properties dialog.
Do a restart of IIS, and you’re done with the initial installation.
Installation for each new site that uses URL rewriting For each site that will be using URL rewriting, right click on its entry in IIS and click Properties. Click the ISAPI Filters tab.
Click Add…. Enter ISAPI_Rewrite for the Filter Name, and for Executable locate the ISAPI_Rewrite.dll file (Under C:\Program Files\Helicon\ISAPI_Rewrite\ by default). Click OK.
Click OK again to exit the site properties dialog.
Stop and start the site to have the filter take effect.
Notes
Unfortunately, (unlike IIRF) ISAPI_Rewrite doesn’t have the ability to check for physical files and directories before performing rewrites. This means that trying to go to a directory like /admin/ will end up with the URL rewritten and thrown at /index.cfm. What you need to do is add code that checks if the value of DocPath corresponds with a physical directory, and redirect to the index.cfm file inside the requested physical directory.
The code should look something like:
This is why we have to set up the filter for each site individually, otherwise sites that don’t have the above code will have /admin/ rewritten.
