Tuckey URLRewrite How-To

Today I will walk through how to put into practice use the Tuckey URL Rewrite java web filter under an Apache Tomcat web server.

URL rewriting is the method of converting complex URL parameters into more human readable format to allow more simple and memorable URLs. This can be an important function if you start using frameworks or content management systems which automatically generate long and at times cryptic URLs. While URL rewrite on the more popular Apache HTTP Server is relatively easy to set up using the default mod_rewrite module, reproducing this functionality on Tomcat requires a little more work.

Standard URL: http://www.example.com/list.cfm?product=fruit&page=1&order=asc&perpage=30
Rewrite URL: http://www.example.com/list/fruit/asc/30/1

The GitHub repository of the XML entries used in this article https://github.com/bengarrett/devtidbits/tree/master/post_635.


URLRewrite can be found from one of 2 sources. The official website at http://www.tuckey.org/urlrewrite/ the developer’s repository at Google Code http://code.google.com/p/urlrewritefilter/downloads/list.

Extracting the downloaded URLRewrite archive reveals a single WEB-INF folder which contains a lib folder and the file urlrewrite.xml. Both these items will need to be copied to the WEB-INF folder of your Tomcat server root directory. For example if example.com was located in /var/www/www.example.com or c:\www\www.example.com the lib folder and urlrewrite.xml would go in /var/www/www.example.com/WEB-INF/ or c:\www\www.example.com\WEB-INF.

Content of Tuckey URLRewrite 4.0’s archive
Content of WEB-INF with URLRewrite
Content Of A Clean WEB.XML

Generally for most default installations of Tomcat the WEB-INF folder will only contain the single file web.xml. We will need to edit web.xml using a text editor to enable URLRewrite on Tomcat but because it is an XML text file. It can be machined parsed so I’d recommend editing it using a source code text editor such as NotePad++ on Windows or Textmate on OS/X.

Add the following code to web.xml anywhere contained within the <web-app></web-app> tags.

<!-- URL ReWriter -->
    <!-- set the amount of seconds the conf file will be checked for reload
    can be a valid integer (0 denotes check every time,
    empty/not set denotes no reload check) -->
    <!-- you can disable status page if desired
    can be: true, false (default true) -->
Edited WEB.XML

Let’s quickly go through these settings.

confReloadCheckInterval is a numeric value in seconds that tells how frequently URLRewrite should check your urlrewrite.xml rules for any changes. Normally with Tomcat the modification of an XML configuration file requires a restart before the changes are reflected. You can set this value to -1 to disable automatic checking, while our value of 0 will mean that URLRewrite will check the urlrewrite.xml on every HTTP request. It is a great setting while testing and developing but a resource waste if used on a production server.

statusEnabled is a Boolean value that enables a URLRewrite status page that is reachable via a web browser at http://www.example.com/rewrite-status. It is probably best to disable this feature on production servers.

logLevel sets how much logging should be produced by URLRewrite. While the default setting is INFO, I suggest using DEBUG while you are testing. Through in a production environment you will probably want to use ERROR or FATAL to limit logging as URLRewrite can generate some large log files very quickly with more verbose log settings.

statusEnabledOnHosts allows you set which IP addresses and hosts that have access to the URLRewrite status page previously mentioned.

Finally the <filer-mapping> tag tells what kinds of methods to pass through via URLRewrite. The tags <url-pattern></url-pattern> should be left as is to apply URLRewrite to the whole site. While the 2 <dispatcher></dispatcher> tags mean that URLRewrite should be used for all HTTP REQUESTS and HTTP internal FORWARDing.

Once done, save your web.xml file and restart your Tomcat server. If all goes well you should be able to point your browser to http://www.example.com/rewrite-status and an UrlRewriteFilter 3.2.0 build 1 configuration overview should be shown. Yes that 3.2 version number is incorrectly listed in 4.0. Point your browser to http://www.example.com/test/status/ and you should be automatically forwarded to /rewrite-status. When this works then congratulations as you now have URLRewrite enabled on your server. Now I will give you some helpful example rules that may come in use. These rules all go in-between the <urlrewrite></urlrewrite> tags located in the urlrewrite.xml file within the WEB-INF folder. Whenever a page is requested on your Tomcat server the URLRewrite application will in a sequential order process ALL the rules contained in the urlrewrite.xml.

Pretty URL, SES Friendly URL Pass-Through

The most common use of URLRewrite would probably be to enable a 3rd party framework or CMS to use pretty URLs. The rule below is a generic setup that could be adapted for many uses. Generally speaking this should always be the LAST rule listed in your urlrewrite.xml rule set. The rule passes all URL requests to the index.cfm file except requests with URLs pointing to files or folders listed in the <condition></condition> tag regular expression value. So with this rule the URL http://www.example.com/list/apples would be displayed as is in the user’s browser but URLRewrite will actually pass http://www.example.com/index.cfm/list/apples to the Tomcat server. You do want to make sure that the page that contained within the <to></to> tag value is also listed in the (not equal) <condition></condition> value otherwise you could run into an infinite loop.

<rule enabled="true">
    <name>Generic Pretty URLs Pass-through</name>
    <condition type="request-uri" operator="notequal">^/(index.cfm|robots.txt|osd.xml|flex2gateway|cfide|cfformgateway|railo-context|admin-context|files|images|jrunscripts|javascripts|miscellaneous|stylesheets)</condition>
    <to type="passthrough">/index.cfm/$1</to>

Permanent Redirection

This rule is specifically for when you want to do a permanent redirection using the HTTP code 301. If we break this rule down, the <rule enable=""> Boolean enables you to selectively turn off this rule without the need to comment it out. The <name></name> tags contains the label you wish to use to describe the rule. <from></from> tag contains a regular expression to forward all requests for the documents.cfm page plus any URL parameters. While <to></to> is the new URL to redirect to. The attribute type tells URLRewrite to send a permanent direct code to the browser requesting the URL, while the attribute last = true tells URLRewrite not to process any further rules for this page request.

<rule enabled="true">
    <name>Permanent redirect example</name>
    <to type="permanent-redirect" last="true">/file/list/document</to>

Selective HTTPS Enforcement

If you have HTTPS setup on your server you can use URLRewrite to enforce certain folders, URL paths or files to only be served on an encrypted HTTPS protocol. The <condition></condition> tag is used to enforce additional policies as to when the rule should be implemented. The attribute type with a value of scheme and the attribute operator with a value of equal states that when the URL scheme (http, https, ftp, etc) is equal to HTTP then apply this rule.

<rule enabled="false">
    <name>Force HTTPS example</name>
    <note>Automatically redirects adminstration requests to a secure protocol.</note>
    <condition type="scheme" operator="equal">^http$</condition>
    <to type="permanent-redirect" last="true">https://www.example.com/CFIDE/administrator/$1</to>

Railo HTTPS Enforcement railo-content.

<rule enabled="false">
    <name>Force HTTPS example</name>
    <note>Automatically redirects adminstration requests to a secure protocol.</note>
    <condition type="scheme" operator="equal">^http$</condition>
    <to type="permanent-redirect" last="true">https://www.example.com/railo-context/admin/$1.cfm</to>

Conditions Based On URL Parameters

You can also apply conditions to user supplied URL parameters. In the example below the condition looks for the URL parameter named fruit and sees if its value is either kiwi, apple or orange. If the values match then it redirects to a replacement URL which also incorporates the parameter. The URL request http://www.example.com/list.html?fruit=apple would forward to http://www.example.com/list/fruit/apple.

<rule enabled="true">
    <name>Selective fruit example redirect</name>
    <condition type="parameter" name="fruit" operator="equal">(apple|kiwi|orange)</condition>
    <to type="permanent-redirect" last="true">list/fruit/%{parameter:fruit}</to>

Extra Help

Secure Railo Administration (railo-context) On Your Railo Server.

Updated August 2014: Tested to work with the latest Railo and UrlRewriteFilter versions.

In this example I will show you how to quickly and dynamically lock down your server to block access to the Railo administration features that are enabled by default. This modification will require an additional download and the restarting of each Railo web server you wish to protect.

You will require the popular UrlRewriteFilter by Paul Tuckey (http://tuckey.org/urlrewrite/) to be installed on your server.

The install instructions and download link for the filter application can be found at http://tuckey.org/urlrewrite/#install.

If you are using Railo Express you need to create a /lib sub-directory in the webapps/www/WEB-INF directory and place urlrewritefilter-4.0.3.jar in there. Both web.xml and urlwrite.xml need to be created and placed in webapps/www/WEB-INF.

Copy and insert this code below into your web.xml. It will tell your server to load the UrlRewriteFilter and to rescan the urlwrite.xml every 60 seconds for any changes. This is important in case in the future you need to re-enable the Railo administration without the need of restarting the server.

The GitHub repository of the XML entries used in this article https://github.com/bengarrett/devtidbits/tree/master/post_321.

<?xml version="1.0" encoding="utf-8"?>

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

<!-- UrlRewriteFilter -->
        <!-- set the amount of seconds the conf file will be checked for reload
        can be a valid integer (0 denotes check every time,
        empty/not set denotes no reload check) -->
         <!-- you can disable status page if desired
         can be: true, false (default true) -->

Now edit your urlwrite.xml to look something like this.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
    Configuration file for UrlRewriteFilter

    <rule enabled="true">
        <name>Disable Railo</name>
        <!-- HTTP Status code 404 equals Not found -->
        <!-- You could also change it to 401 = Unauthorized or 403 = forbidden -->
        <set type="status">403</set>


You can now restart your server and then try to access http://www.example.com/railo-context/admin/web.cfm or http://www.example.com/railo-context/admin/server.cfm. Hopefully if all went well both pages will return a HTTP status 403. If you need to re-enable these pages, edit your urlwrite.xml and change the rule enabled attribute value to false.

Install Railo on a simple, barebones, Ubuntu Server Linux within a Sun VM Virtual Box virtual machine

This article written in early 2009 is out of date.

This tutorial assumes you have a basic knowledge of virtualisation, Linux and the use of the command line. It will walk you through though and explain most things in detail.

I created this tutorial mainly for ColdFusion and CFML developers who create applications and need to test those applications on a wide variety of CFML platforms. Railo in a virtual Ubuntu Server allows you to test and develop on a Linux platform while also checking for Railo CFML compatibility. As an added bonus, because we will be setting up a barebones, virtualised server with no graphical user interface, the resources used on your host machine will be much lower.

The basis of this server will be a barebones, Linux Server running Ubuntu Server 8.04. Web hosting will be covered by Apache Tomcat 6.18. It will require Sun Java 6. File transfers to the server will be done using FTP via ProFTPd and obviously our CFML server will be Railo 3. We will also install the text based web browser ELinks to fetch some files that are not on the Ubuntu repositories.

You first need to download a copy of Ubuntu 8.04 LTS Server Edition from here http://www.ubuntu.com/getubuntu/download. The LTS means long term support, whereby the Ubuntu developer Canonical will continue to support this edition of the operating system until April 2013.

Start off by loading Sun xVM VirtualBox and pressing the New button.

Follow the wizard and when you reach VM Name and OS Type, give your new virtual machine a name. We will call ours Railo Server. Make sure your Operating System is Linux and the version is Ubuntu.

VM Name and OS Type

The next screen, Memory can be left at the default of 386 MB.

The Virtual Hard Disk screen sets up the emulated hard drive for Ubuntu. Create a New disk. When given the option of Hard Disk Storage Type, I recommend selecting Dynamically expanding storage. When prompted for Size, you can reduce the default 8.00 GB down to 2.00 GB. Once you have Finished creating a new virtual hard disk, it should be now selected by default.

Virtual Hard Disk

Press Next and review the Summary screen and then press Finish.

Now with your newly created virtual machine selected, press the Settings button. Select the CD/DVD-ROM tab. Select the Mount CD/DVD Drive checkbox and the ISO Image File radio. Push the browse folder icons on the right of the ISO Image File to bring up the Virtual Media Manager.


In the Virtual Media Manager select the Add button and browse to your Ubuntu Server download which should have a name similar to ubuntu-8.04.2-server-i386.iso. Once added to your CD/DVD Images, press Select and you will be returned to the Settings dialog.

Virtual Media Manager

Back in the Settings dialog, select the General tab and the Advanced sub-tab. I found I needed to select Extended Features: Enable PAE/NX otherwise Ubuntu would fail to boot after installation. If you wish you can select the Extended Features: Enable VT-x/AMD-V. You might also wish to deselect the Floppy from the Boot Order. If you want to add a description of your virtual machine, select the Description sub-tab.


Select the Network tab, Adapter 1. Make sure the Enabled Network Adapter is checked and then change the Attached To: pull down from NAT to Host Interface. Now if you have more than one host interface on your computer (most laptops have at least two, wired and wireless). Make sure the interface which you use to connect to the Internet is selected.


Once your settings are complete, press OK and then Start your virtual machine.

Two quick tips for users of VirtualBox. If you accidentally click the virtual machine window with your mouse and loose the pointer, press the right Ctrl key to have it returned. Also if your Ubuntu virtual machine window blanks out, this is due to the Ubuntu screen saver. Simply press the right arrow key when you have the VirtualBox window as your focused application and your shell should be returned.

Your virtual machine should now boot and you will quickly arrive at an Ubuntu language request screen. Select English and then press enter for Install Ubuntu Server.

Install ubuntu

After a few moments you will be taken to a text based install system. Again select English and press enter. Choose your country, territory or area.

On the Detect Keyboard Layout screen I used the arrow keys and select No to manually choose a keyboard. I found the automatic detection took more effort than the manual, but your use might vary.

The installer will now do its thing for a while.

When prompted for a hostname on the Configure the Network screen. Change the default from ubuntu to a name of your choice. I used railo.

Choose your time zone or city.

On the Partition Disks screen, under Partitioning Method: select Guided – use entire disk. Select disk SCSI1. Accept the recommended settings by selecting Finish partitioning and write changes to disk. You will then be prompted to write changes to disk, accept Yes.

Ubuntu will now partition and resize your virtual hard drive and copy its files from the ISO CD/DVD image.

The next prompt will Set up users and passwords for your primary account that we will use to login to Ubuntu. Choose a Full name, either your own or something on the lines of Railo. The Username can be anything of your choice, I will use railo. Then set a password that you will remember. This password will be used quite a fair bit later on.


Ignore and leave blank the HTTP Proxy information when prompted.

On the Software selection screen, do NOT select any software and instead just Continue.

Select software

Once the installation is complete, you will be prompted to restart the system, so Continue and the installer does this automatically.

Finish installation

Ubuntu will now start up and you will be taken to a login prompt. Login with your previously set username as login and password.

Railo login

Now we will update the Ubuntu repository lists and available packages.

sudo apt-get -y update

When prompted your sudo password is the same as your login password. The sudo command allows you to run other commands temporarily as ROOT user.

Now we update your Ubuntu Server with the latest available, stable packages. I highly recommend you do this step otherwise you may encounter some networking bugs related to VirtualBox that have since been solved with software updates.

sudo apt-get -y upgrade

I suggest rebooting after the upgrade for the changes to take effect. You might also want to unmount the Ubuntu CD. You can do this by selecting the Devices, Unmount CD/DVD menu item from the virtual machine program window.

sudo reboot

Sudo reboot

Once you have re-login we will need to install a text based web browser. I recommend ELinks.

sudo apt-get -y install elinks

Once installed, run ELinks and tell it to browse to the Tomcat website.

elinks http://tomcat.apache.org

In ELinks we need to change a setting to make the browser look slightly more appealing. Press Esc S T to bring up the Terminal options dialog and under Frame handling: select VT 100 frames. Press V O to save these changes and exit the dialog.

Terminal options

Select Tomcat 6.x from the list on the left of the page. In ELinks you navigate between hyperlinks by using the arrow keys, and pressing enter to select.

ELinks Tomcat web

On the download page, use the arrow keys to scroll down the hyperlinks until you see a light-blue heading 6.0.18 (this might be a different number if Tomcat is updated). Under it there should be the headings Binary Distributions * Core: select * tar.gz (pgp, md5) and this should start your Tomcat download. Just make sure you Save the file when prompted. Save to file ./apache-tomcat-6.0.18.tar.gz

Selecting Tomcat download

Save Tomcat download
Active download

Once your download is complete, press the Esc key on your keyboard to bring up the ELinks menu. F for File. X for Exit.

Back at the prompt we now need to install Sun’s Java.

sudo apt-get -y install sun-java6-jdk

When asked, agree to the licensing terms. Once Java has been installed we can now install Tomcat 6.


Should display our downloaded copy of Tomcat, apache-tomcat-6.0.18.tar.gz. We will move this archive to a more appropriate directory, install then run Tomcat.

A quick Linux tip for newbies, in shell instead of typing the full directory or file name, use the Tab key. For example for the command listed below you could type; sudo mv ap Tab /o Tab Enter cd /o Tab Enter

sudo mv apache-tomcat-6.0.18.tar.gz /opt/
cd /opt/

Uncompress Apache Tomcat archive.

sudo gunzip ./apache-tomcat-6.0.18.tar.gz

Unpack Apache Tomcat package.

sudo tar xvf apache-tomcat-6.0.18.tar

Rename Tomcat’s directory to something more simple.

sudo mv apache-tomcat-6.0.18 tomcat
cd /opt/tomcat/

Run Tomcat.

sudo /opt/tomcat/bin/startup.sh

Test Tomcat.

sudo elinks http://localhost:8080

If successful you should see a page with the header of The Mighty Tomcat – MEOW!

Now we need to download Railo. In ELinks, Alt key F G to go to a new url.

Scroll down with the arrow keys until you see the heading Railo Custom. From there move the cursor over the link (but do not download) All OS, railo- (30 MB). Now with the link highlighted, press Alt L D to Save to file but change the default download name from ./index.cfm to ./railo.war.

Railo war download

Exit ELinks. Now we are going to modify Tomcat’s webapps directory structure.

sudo mv /opt/tomcat/webapps/ROOT/ /opt/tomcat/webapps/OLDROOT/

Now copy the downloaded Railo package into the Tomcat webapps sub-directory, but while we copy it we will also give it a new name.

sudo cp railo.war /opt/tomcat/webapps/ROOT.war

If Tomcat is running it will automatically detect the placement of ROOT.war in the webapps directory and create the new directory ROOT.

cd /opt/tomcat/webapps/

We can test that Railo is working by using ELinks.

elinks http://localhost:8080
Railo admin

With that all working we have a running Java based web server, running an open source CFML engine by default. But lets adjust some of Tomcat’s settings, such as the default port. Currently we have Tomcat running on port 8080 rather than the default HTTP port of 80.

We are going to use the nano text editor to change the Tomcat server configuration XML file. Nano is a very simple text editor that uses the CTRL key for most of its commands.

sudo nano /opt/tomcat/conf/server.xml

Ctrl _ 67 Enter should take you to line 67 which has the following
<Connector port=”8080″ protocol=”HTTP/1.1″



Crtl x y Enter will save the changes.

Change Tomcat default port #
We also need to modify one more configuration file to improve the performance of Tomcat. Otherwise you might find Railo runs slower then expect. Edit this file.

sudo nano /opt/tomcat/bin/catalina.sh

Press Ctrl _ 72 Enter to take you to a blank line and add the following text.

# Increase Tomcat memory
JAVA_OPTS="-Xms256m -Xmx256m"

Save the changes by pressing Ctrl x y Enter

Optimizing Tomcat

Lets restart Tomcat to implement the changes.

sudo /opt/tomcat/bin/shutdown.sh
sudo /opt/tomcat/bin/startup.sh
elinks http://localhost/

Congratulations you now have Railo, running as the default application on the Apache Tomcat server. You can reach Railo’s administration page using this link.


The default password is admin. Now obviously a text based browser is not the best means of viewing the Administrator page. So quit ELinks and run this command.


Hopefully you should only have one network card listed and a Local Loopback. Your network card will be the first item listed usually as eth0. Look under the 2nd line for inet addr: and there should be a numeric IP address listed, in my case it is Take note of your IP address.

ifconfig results

In your favorite web browser on your host computer, point it to the following address…

http://[noted ip address]/railo-context/admin.cfm

(I would replace [noted ip address] with to have

Other useful pages to note are listed below. These allow you to administrate and view statistics on the Tomcat web server. But both of them require you to create a custom user account.

http://[noted ip address]/manager/status
http://[noted ip address]/manager/html

Back in your VirtualBox window edit the following file.

sudo nano /opt/tomcat/bin/catalina.sh

Save the changes and edited the following so you can access the Tomcat management features.

sudo nano /opt/tomcat/conf/tomcat-users.xml

Replace these lines.


With the following but make sure you change the password.

<role rolename="manager"/>
<user username="railo" password="[password of your choice]"

Save the changes, quit nano and restart Tomcat.

sudo /opt/tomcat/bin/shutdown.sh
sudo /opt/tomcat/bin/startup.sh

Now with your web browser return to http://[noted ip address]/manager/status and use your new username and password. If successful you should be taken to a Server Status page where you can monitor your Tomcat server performance.

With your CFML web server up and running we now have to create a way to allow you to upload files to it. For this we will install a FTP server.

sudo apt-get install -y proftpd

When prompted at the ProFTPd configuration screen, select standalone.

Before we test the FTP server we need to adjust some settings.

sudo nano /etc/proftpd/proftpd.conf

In the file change.

UseIPv6 = on
UseIPv6 = off
ServerName = "Debian"
ServerName = "Railo"

I like to adjust the default FTP server timeouts as when developing and testing. I find it annoying if I have to continuously be reconnected every time I transfer a file or navigate the directories.

TimeoutNoTransfer = 600
TimeoutNoTransfer = 65256
TimeoutIdle = 1200
TimeoutIdle = 65256

As this server is only being used internally we do not have to worry so much about security. So to keep things simple we just use the same user account that we use to login to shell.

User proftpd
User [your server login username]

If you want live file transfer status when connected to the FTP server, go to line 78 and replace.

# UseSendFile off
UseSendFile on

Go to the last line of the file at the very bottom of the file and type in the following to restrict all other user accounts from use in the FTP server.

# Restrict user logins
<Limit LOGIN>
AllowUser [your server login username]
# Disable ident lookups to speed up connections
identLookups off
# Default folder on connection
DefaultRoot /opt/tomcat/webapps/ROOT/

Quit and save the file.

We now need to claim ownership of the Tomcat webapps directory so when we connect with an FTP client we can modify folders and upload files.

sudo chown -vRf [your server login username] /opt/tomcat/webapps/

Now restart the FTP server for the new settings to come into effect.

sudo /etc/init.d/proftpd restart

Now using your favorite FTP program on your host machine, connect to the FTP on the virtual machine. You will use the same IP address as your web browser. So for me I would use the following settings…

Port: 21
Server Type: File Transfer Protocol or FTP
Login Type: normal
User: railo
Password: *******

ftp to railo

Finally we need to automatically run our new servers every time our virtual machine is rebooted. So back in your shell edit the following.

sudo nano /etc/rc.local

Add the following below. You do need to make sure it is all placed above the line exit 0.

# Start up Apache Tomcat web server
/opt/tomcat/bin/startup.sh start
# Start up ProFTPd FTP server
/etc/init.d/proftpd start

Editing boot file

Exit and save, then reboot your virtual server to test your new adjustments. Hopefully your Tomcat and FTP should now run at boot by themselves.

sudo reboot

If you ever wish to shutdown the server.

sudo shutdown -P 0

Congratulations you now have a fully functional, virtual, CFML web server ready for you to play with. You don’t even need to login at shell for the server functionality to work.