[Looking for Charlie's main web site?]

Setting up ColdFusion to process html or other file extensions

Note: This blog post is from 2011. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.
As a follow-on to my last entry, Setting up CFBuilder to process htm files with the ColdFusion editor, I wanted to offer more info for those who may want to know more about this--or ensure that more is shared with any who would consider doing this.

If you're looking for how to configure CFBuilder to open htm files with the CFML editor, see that other entry. This one instead is about the related idea of having CF (the server) process htm (or other) file extensions. There are certainly pros and cons.

First, how to configure it in CF

Since I suspect some of the first people to come look at this will be those who want to do it, for any reason, the good news is that yes, you can do it, and it's been documented by many. I won't rehash the details, but instead will point you at any of several resources that do. It's not heard, though it does require a restart of CF (and perhaps your web server) to take effect.

Update for CF10: I wrote this entry in 2011, and since then CF10 has come out and things are indeed different. Michael Sprague has documented how to do it in CF10. (Thanks for sharing that as a comment, Michael!) We now need to edit the uriworkermap.properties file for any web connectors we have setup with CF. See the aforementioned blog post for details. Beyond those differences detailed there, some of the other info I share below may still be of interest to those on CF10 and beyond.

First, Adobe documented it long ago. It's a pretty old and barebones article. It makes only a passing reference to the need to also change the configuration in your web server. To be clear, you do need to make the needed changes to the web.xml file if using an external web server like IIS or Apache, but the point is that you also then therefore need to also make changes in that external web server.

Fortunately, a CF8-era Adobe technote does address that additional detail. And this solution works for CF 6, 7, 8, and 9. (With Zeus being built on Tomcat, it may well be quite different then.) Do be careful to look closely at the values, as some may change from release to release ("macromedia_mapping" vs "coldfusion_mapping").

Other writers also addressed the issue over the years. They may be older, but you may get useful ideas from them. For instance, Peter Bell blogged about it including IIS and Apache, while several others covered IIS including Brian Anderson of Hostek, Steve Cross, and Tony Weeg, and Steven Erat to pick just a few.

2017 Update: A commenter pointed out that one of the links in this 2011 post no longer worked, and I see that I had a few such now-broken links. I have updated those not working as of 1/13/17 with links to the web archive version of the pages as captured at some time in the past. I'm sure I have other posts from years gone by that could benefit from such updates, but with almost 500 posts I probably will only correct those that people point out have issues. :-)

My point is, clearly many do find this an intriguing idea, for whatever reason. So why might one want to?

Why people might want to do this

There can be several reasons why people want to do this, some reasonable and some questionable.

I suspect that many delight in (or are compelled to explore) the idea of "hiding" their server implementation. By using htm files rather than cfm ones, no one need know they use CF (by the URLs of their page requests).

Of course, they could use still some other extension, whether some new one not used by anyone else, or perhaps one that others do know, and the solution above works for that as well.

For instance, I've known people who have configured things so that files with the php extension were handed to CF: not because they wanted CF to process PHP code, of course, but rather just because they did NOT use PHP and therefore just wanted to make it seem to the world that they did.

They may hope to throw hackers off the trail, or may want to avoid having to explain to folks that/why they use ColdFusion (sad that this should be the case, but some have felt the need).

Why people might not want to do this, and counters to such concerns

For all those who like the idea, there are probably more who spurn it, again for a number of reasons.

I'll say that while on the surface their concerns may seem clear-cut, as with so many things, "it depends". Those who might still want to try the alternative configuration for whatever reason might offer some reasonable counters to those concerns. Again, I'm not on either side in this debate. I'm just reporting observations for consideration. :-)

The concern of processing all HTM files as CFM, and the counters

For one thing, those who do not like the idea would point out that having htm files processed by CF runs the risk that now EVERY htm file will be processed by CF, even if it has no CFML in it at all, which of course would add overhead for the page execution time and would also add useless overhead to CF.

A counter some may propose is that one could set things up to use *.html extensions for "real" html pages and *.htm for "html/cfml hybrid pages, so that hopefully at least you only have CF process what you really think should have CFML.

Still others would note that they could also control whether and when they do this in the web server, so that perhaps it's only some website or some directories for which this configuration change (htm files being handed to CF) is made.

The concern that some things other than CF might be confused by the change

I noted above that some might use this approach simply to define not htm files but instead some other extension to be processed by CF. There's no real performance impact to doing that.

But it does raise the specter that some things may be confused by the change, if they expect to look for/find/use only cfm extensions. Possibilities include editors, log analysis tools, and so on. (I addressed how to change CFBuilder to open HTM files with the CFML editor in the last entry.)

Might there be other solutions, though?

Even with these concerns and their counters, some might want to propose still other solutions to achieve the goal of obfuscation (hiding the fact that you're running cfm files, if that's the main goal of the above). Let's take a look at a couple.

Using no extension at all

For one thing, some could just set things up so as not to use a file extension in their URLs at all. There are various ways to do this.

First, one could rely on the web server support of default documents (like index.cfm) to point to one file in the directory. No, this may not suit everyone, but I in fact do that frequently on my own site, such as for http://carehart.org/presentations/, http://carehart.org/articles/, or http://carehart.org/consulting/. I never bother with the index.cfm, as the web server figures it out for me. Again, though, that approach only works when you can have one file per directory.

There are still other ways to have CF process requests for files that have no extension at all, 2005 era discussion of one way to do it, including settings for IIS and Apache.

I could identify still others (to support requests with no extensions), but this is getting far afield of the goal of this post.

Another solution: URL Rewriting

I'm sure some have been champing at the bit the whole time they've been reading this article, because they know something that perhaps others do not. Another solution for all this trickery above would be to use URL rewriting instead, so that you don't change the file extensions but instead you just don't use any at all in the URL.

With that approach, you configure things on your server (often via an extension to your web server) so that when people ask for one file, they're really sent to another. So if someone asks for url abc (whatever that is, in terms of domain, path, file, path_info), they are instead shown the result of processing file xyz (whatever that may be, to suit your interests), but the browser URL still shows the url as abc.

URL Rewriting can completely hide the underlying server implementation, or whatever level of it you choose, such as hiding what extensions you use, your use of query string/URL variables within code, your use of deep directory structures, and so much more.

This is not the place to discuss and debate all the pros/cons and even alternatives for URL rewriting, but I'll note that I do have a category for them with several alternatives (free and commercial, for Windows and Linux) at my CF411 site's category for URL Rewriting Tools .

BTW, the URLs for my cf411 site are themselves processed by a rewrite rule, though slightly different from what was just discussed. Note that that url I just shared, http://www.cf411.com/urlrewrite, ends up as http://carehart.org/cf411/#urlrewrite. You'll see that in the browser. Not only does the domain change (I wanted to people to get to it as cf411.com), but you also end up within a given subdirectory of my carehart.org site (the cf411 site is really just a subset of that main site).

And finally the URL ends up showing use of a page anchor (the #) to jump down in the very long page to the section chosen.

I wanted to be able to share URLs without all that noise. You've got to admit that cf411.com/urlrewrite is just smoother than carehart.org/cf411/#urlrewrite. :-)

Of course, I could have implemented the rewrite to keep that "new" url hidden. I just didn't bother. But if you're new to url rewriting, do remember that you CAN have the "resulting" url hidden from the user.

So, there you have it. A problem, some solutions, some concerns, some counters to those, and still other alternatives. I'm sure some are thinking "man, I never thought there could be so much to consider for this simple idea". But as always, there are just lots of things to consider, and as a troubleshooting consultant, it's my job to find, understand, and offer solutions to such problems.

But I could well have missed something significant. I know that some people may have far more experience with this particular problem (and to be honest, this is not one I help people solve often. It came up today for one user, so I researched and wrote here about it.)

But I do recognize that there is often more to a problem than seems to most at first, and I wanted to share the observations with any who may appreciate it. That's how I roll. Let me know what you think.

For more content like this from Charlie Arehart: Need more help with problems?
  • If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
  • See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed
In case anyone is interested, the process for setting this up changed slightly for ColdFusion 10.

# Posted By Michael Sprague | 5/30/12 9:54 AM
Thanks for sharing that, Michael.
Two things:
1. One reason for processing HTM files as CFM files is if you are converting a website to CFM from HTM you may not want to change all of the links to the converted pages to have the new CFM extension.
2. Doesn't URL rewrite confuse and annoy search engines?
Can someone share how to do this on CF10? The link to the CF10 is no longer working. Thanks in advance.
# Posted By Jack | 1/12/17 4:32 PM
Jack, thanks for pointing out the broken link. No need to ask if "someone" can help. I'm still here creating and managing the content. :-)

Indeed, I see that the post (from 2011) had a few such now-broken links. I have updated those not working as of today with links to the web archive (archive.org) version of the pages as captured at some time in the past.

That's something you should take note of, in case you ever come across any other such broken links. Some people just don't keep their sites going for years and so many old links do break , so the archive.org service is a wonderful one to take advantage of.

And I'm sure I have other posts here from years gone by which could benefit from such checks and updates, but with almost 500 posts I probably will only correct those that people point out have issues. :-) So again, thanks.
Is modifying the uriworkermap.properties the only thing in this process? Do you not modify the web.xml or isapi setting in IIS? This alone isn't working for me. I'm completely stumped moving from CF9 to 2016.
# Posted By Tony B | 1/24/17 5:34 AM
Tony B,

I am running in the same thing on 2016 and IIS 8.5
Tony B,

I found that I had to add to the C:\ColdFusion2016\cfusion\wwwroot\WEB-INF\web.xml a servlet mapping for my custom extenstion. I choose an unused id number (in my case 32 and 33) see example below.. Restarted CF and my *.do file that didn't work before worked.

<servlet-mapping id="coldfusion_mapping_32">
   <servlet-mapping id="coldfusion_mapping_33">
Hi, guys (Tim and Tony). Yes, you still need to do the web.xml changes in CF10 and above. That was indicated in the blog post from Michael Sprague that I pointed to (and whose link I updated when Jack complained it was no longer working.) Note that he had said in his post, "In CF10, there is now an *additional step* that is required due to TomCat" (emphasis mine).
Just did this in ColdFusion 2018 for CentOS 7 and Apache 2.4; the missing step was to modify mod_jk_vhost.conf to make sure that the .htm extensions were handed off to ColdFusion to the servlet:

AddHandler jakarta-servlet .cfm .cfml .cfc .cfr .cfswf .htm
# Posted By Ryan Peters | 2/23/20 6:59 AM
Thanks, Ryan, for confirming that the concept and approaches discussed still work (generally) in 2020. To be clear, a couple of resources I pointed to back then (2011) did indeed cover that additional line for Apache. But being older, they just mentioned putting it in httpd.conf, while CF10 and above does indeed store the addhandler in the mod_jk_vhost.conf (or other locations), so thanks for making that additional point for readers.

I might create a new version of this post to pull all the info together in one post and using latest approaches for Apache, IIS, and CF.
Copyright ©2024 Charlie Arehart
Carehart Logo
BlogCFC was created by Raymond Camden. This blog is running version 5.005.
(Want to validate the html in this page?)

Managed Hosting Services provided by
Managed Dedicated Hosting