CF911: Why/when you MUST update the web server connector for ColdFusion 10/11 and may have missed it

Note: This blog post is from 2013. 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.

In brief, a VERY common problem is that while they MAY WELL have applied the provided "updates" for CF, folks often do NOT notice that they may have to (and generally must) "update" the web server "connector" (if they are using an external web server, like IIS or Apache) as a separate manual step, after applying the update.

I explain here what that means, how do to it, and why you may miss that you need to.

Update in 2019:

Since writing this entry, I did one in 2019 on When and how to upgrade CF web server connector, easier since CF2016, which at least makes it EASIER to upgrade, though much of what I write here still applies. I also updated this post since originally writing it, in ways discussed below.

(Or if you'd rather just have me help you quickly help you analyze and rectify your situation, whether with regard to the connectors or any other CF server troubleshooting, I can do that in a brief consulting session, likely less than an hour, remotely and securely. I provide all the detail here for those who prefer to "go it on their own". For more on my consulting services, including rates, approach, satisfaction guarantee, and more, see the consulting page at carehart.org.)

Sections below

• The least you need to know
• So what is it to reconfigure/rebuild/update the connector?
• What's the situation with CF10 updates and the need to update the connector?
• About those numbered folders
• Should I back things up first?
• How to reconfigure (or rebuild) the connector
• Don't forget to "Run as Administrator"!
• Reconfiguring/rebuilding the Connector if you have multiple instances
• How can I know whether a given update DID offer an updated connector?
• You *may* only need to do an "upgrade" rather than a "reconfigure/rebuild" of the connector
• Where can I learn more about all this?

BTW, some use the phrase "reconfigure", "rebuild", and "update" of the connectors rather interchangeably. I do the same here, in case people come searching for either phrase. (Note: I'll mention later how there is in fact a difference between "reconfiguring/rebuilding/updating" the connector and a separate possible option to just "upgrade" the connector. It's quite different, but not always the right option to use. I discuss that below as well.)

[Update While I wrote this in 2013 for CF10, the same applies to CF11 and some of its updates, which also call for a rebuild of the web server connector. It's about 50% of the updates that to each that DO require a connector rebuild afterwards.

And here's great news for those on CF2016: this whole issue has finally has been addressed and the update mechanism DOES now properly update the web server connector for you, if needed. So all the below applies only to those still on CF10 or 11.]

I'll also explain how to easily tell if you have done the update or not, so you know whether all this applies to you. I'm betting it does.

Indeed, getting the web server connector updated is the solution to a majority of problems I see people have, when they feel that problems are tied solely to a recent move to ColdFusion 10 or 11.

Read on to learn much more about this issue of web server connector updating.

[Updates since Sep 2013:
1) Since writing this entry, I did a subsequent one on Still more reasons to make sure you have updated your ColdFusion web server connector, so be sure to read that next.

2) Also, someone asked in the comments if this problem (reported by me here in Sept 2013) still remains for newly downloaded CF10 or 11 installation files. Sadly, it absolutely does. While a new install includes whatever updates are current at that time, the installer may not then be updated again for months, so by the time you get it, it may not be several updates out of date. This is not a new problem.

Bottom line: YES, if you download CF10/11 to install it, you MUST do the following: a) downloading CF, b) apply whatever is the latest available update at that time, and c) update the connector, as discussed below.

3) Finally, one more update I want to slip in since writing this entry in 2013: do beware that one negative of rebuilding the connector (as described below, and for the important reasons discussed) is that you will lose any setting changes you may have made regarding the connector (such as to the workers.properties or uriworkermap.properties. These are discussed in the Adobe blog entries on tuning the connector, like this one for cf11 and this one for cf10.) Some good news is this problem was addressed somewhat in CF11, as of update 5. The connector tool (in CF11 only) at least now prompts you to backup your current connector files. It does NOT restore them, so that's still up to you to do. Either way, do be careful to save any such changes before rebuilding the connector as described below. ]

The least you need to know.

For those who wish I could "cut to the chase" (though it risks leaving a lot unsaid), here's the least you need to know, to determine if this is need to update your connector may be an issue for you: look in each "numbered" folder under [cf10]\config\wsconfig. In there, you will have a connector module, either isapi_redirect.dll for IIS or mod_jk.so for Apache.

If you're on Windows and that isapi_redirect.dll file is dated many months ago, then you have likely not updated the web server connector. For instance, If you've applied CF10 update 11 (latest as I write this) and are on IIS, and the DLL file is not dated May 2013 or later, then you have NOT reconfigured/rebuilt the connector and could have problems due to that. And if you're on CF10 and your DLL is dated March 2012, then you have not updated the connector AT ALL since CF10 cam out, and you can expect serious problems under even moderate load.

As for Apache, I'm not positive of which updates required an update but I know some did, so again, if you're on CF10 and that mod_jk.so is dated March 2012, then you have not updated it at all, which is really bad. If it's many months old, it may still not be as updated as it could be.

Do note that reconfiguring (or rebuilding) the connector does indeed involve more than just its updating that one .dll file (or the .so file in Linux), but includes its also updating other files within CF and also it updating appropriate files and configuration information in IIS or Apache. I'm merely saying that looking at that date of that connector module file is a quick check of whether you've done the reconfigure (or rebuild) of the connector at all.

So what is it to reconfigure/rebuild/update the connector?

I'll detail this more below, but in brief, as for reconfiguring/rebuilding/updating the connector, here's what is meant: opening the CF web server configuration tool (wsconfig tool), and "removing" whatever connections you may show existing for your given site/sites, then adding them back.

Under the covers, this process will remove and then re-add certain files/folders in the [coldfusion\config folder, and it will update your web server config files (including removing then re-adding the CFIDE and jakarta virtual directories in whatever site/sites you connect to. Do beware that if you or anyone else may have removed the CFIDE virtual directory from some sites in your web server config, you may want to go back and remove it again once completed.)

If you have only one connector listed there, you're done.

If you have multiple connectors, you would remove and re-add each of those. (If you have more than one, you should take note of what sites are listed so you can add them back appropriately. And I discuss below about backing up changes before proceeeding.)

If you may be running multiple instances of ColdFusion (meaning you're using CF Enterprise/Trial/Developer and you created multiple instances in the CF Admin Instance Manager), then you would need a different connector for each instance. While you can remove connectors for any instance in the tool, you will find that when you try to add back a connection, it does NOT offer a list of instance names in the dropdown. Instead, you have to open the wsconfig tool inside each instance's folders, at [cf10]\[instance]\runtime\bin. (Again, more on this later. Again, this section is "the least you need to know".)

Now, let's proceed with the rest of the info I think you ought to understand about this whole issue, which I've not seen pulled into any one place.

What's the situation with CF10 updates and the need to update the connector?

As most will know, since ColdFusion 10 came out in May 2012, there have been 11 "updates" (as of this writing). That's great that problems are being fixed. The bad news is that many people THINK that they have "fully updated CF10" by applying the latest update, when they may still NOT have "fully updated" their ColdFusion 10 implementation.

In each update, there is a "more info" link on the page for the update, shown in the "Server Update" tool of the CF Administrator, and in the technote it states whether after applying the update you may (and generally must) rebuild/reconfigure or at least "upgrade" the web server connector. The issue is that sometimes the updates include a fix to the connector (mod_jk.so for Apache, isapi_redirect.dll for IIS).

As I said above, if that connector file (as found in in each "numbered" folder under [cf10]\config\wsconfig) is still dated March 2012, then you have not updated the connector and can expect serious problems under even moderate load. And if it's more than a few months old, you probably have not updated the connector, as most CF10/11 updates do involve tweaks to that connector, requiring it to be reconfigured by you.

(Yes, yes, I know that the whole point of the CF10 auto hotfix mechanism was that it was supposed to be a single click update. In this case, it just seems that the updaters are not able to do the web server configuration updates. Since folks can have different web site configurations, I think I can understand Adobe not feeling they could step in and handle this for you. Still, it surely has left many in a situation where they are suffering needlessly for having missed this important step. Update: again, some great news is that in CF2016 this finally has been addressed and the update mechanism DOES now update the connector if needed.)

About those numbered folders

There is one "numbered" folder under the wsconfig folder, representing each connection made between an external web server and CF. if you configured the connector for "all sites" and nothing else, there should be just one folder, numbered "1". As you connect other sites to CF, whether to the one "cfusion" instance or to different instances you may have installed if on CF10 Enterprise, you will get another numbered folder.

BTW, sometimes people find when looking here that they do have multiple numbered folders, even though they have only one connector. That's ok if you DO really have multiple connectors listed in the wsconfig tool. If indeed you have only one instance and it's listed in the wsconfig tool as being connected to "all sites", then having more than one folder would be an indication of a mistake/problem (most typically that you failed to run the wsconfig tool "as administrator" on Windows. More below).

If you have multiple instances, again, you may have more numbered folders because you have connections between sites and instances.

There can be other situations where you have more numbered folders than you should and things ought to be cleaned up. This is not the blog entry to elaborate on that. If you think you have a problem, and want to solve it, contact me about my consulting services and I'd be happy to help, hopefully quite quickly since I have helped many others.

Should I back things up first?

Given all the above, and before you may proceed with the steps below, you would be wise to backup the key files that would be changed in a connector update. (Again, as an update since writing this in 2013, in 2014 CF11 came out and it DOES now offer to backup the settings before changing them, if you try to remove a connector.)

I have mentioned that the update (remove/re-add) will first remove and then re-add key files in the [coldfusion]\config folder (and its underlying numbered subfolders). You should consider simply making a backup of the entire config folder (it's usually not very big at all), so that you could either review what changed or recover if there's a problem. (I've also mentioned that CF11 update 5 now does offer to backup the connector files when removing a given connector: it saves the related numbered folder for that connector in a new backups folder within the wsconfig folder.)

I've also mentioned that the connector update will also remove and then re-add key configuration entries in your web server configuration, particularly the CFIDE and Jakarta virtual directories. But it will also modify other things (the "isapi filters" and "handler mappings" configuration in IIS, and similar settings in your Apache conf files).

It would be wise to back those up as well before proceeding. In the case of Windows, it's a bit challenging because you may have such web site configuration values in either the web.config of your web site(s) or (more likely) in the applicationhost.config file (in Windows\system32\inetsrv\config). I would recommend you backup each before proceeding. In Apache, note that you and/or CF may have updated more than just the httpd.conf file but also a mod_jk.conf and you/your folks may have updated still others that could be "included" from these. I'd backup the whole conf folder.

How to reconfigure (or rebuild) the connector

So to reconfigure (or rebuild) the connector, you could use the CF web server configuration tool, which in Windows is accessible on Windows from Start>Programs>Adobe>ColdFusion 10>Web Server Configuration Tool.

Note that if you are not the person who installed CF10, you won't have that menu option. Instead, you can run the wsconfig.exe as found in C:\ColdFusion10\cfusion\runtime\bin.

And Linux users also would run ./wsconfig in that folder.

Before you do that, though, consider the following important additional details:

• If you are running on Windows, don't run that tool yet. See the next section, on Don't forget to "Run as Administrator"!
• If you are running multiple instances of CF 10 (on a single machine), it's NOT enough to just run that wsconfig that I just mentioned. See the important section below, Reconfiguring/rebuilding the Connector if you have multiple instances
• Note that doing the reconfigure/rebuild of the connector will require a restart of the web server (IIS or apache). If you're not prepared to let that happen, don't proceed with a connector update.
• You *may* be able to get away with only doing an "upgrade" rather than a reconfigure/rebuild of the connector, though it's pretty rare. See the section below on that, You may only need to do an "upgrade" rather than a "reconfigure/rebuild" of the connector
• You may wonder why you've never heard about any of this. See Where can I learn more about all this?
• And as I added in an update near the top here, do beware that when you reconfigure/rebuild the connector, it will cause you to lose any settings to the files in those numbered folders, to be sure to save them off and re-apply them. CF11 now prompts you to do that since updates were made to the connector tool in update 5.

I'll note as well that for some users, it may be useful to point out that there is also a jar version of the wsconfig tool, at C:\ColdFusion10\cfusion\runtime\lib (or the runtime\lib under a given additional instance, if you have added any.) You can see the docs and command-line help for any of these tools to learn more about using them.

And as I mentioned at the outset, in "the least you need to know", to do a "reconfigure/rebuild" of the connector (as opposed to an "upgrade" of it), you use the option to "remove" and then re-"add" the site connection.

Don't forget to "Run as Administrator"!

If you're on Windows and on either Server 2008 or 2012, or on Windows 7, 8, or even Vista, you should run this connector tool "as administrator"--even if you would say you "are" an administrator. Just take my word for it as the voice of experience: remember always to right-click on the tool (whether launching it from the Start menu or running the exe) and choose "run as administrator". You may not see a difference in how things work, but I promise you it will affect how it does its updates both to CF and to IIS. Many people's connector problems are due to them or others having failed to do this, perhaps in previous attempted connector updates. Things can get quite messed up, and this is not the post to talk about how to undo that mess. I can help via my consulting, as discussed elsewhere here.

Reconfiguring/rebuilding the Connector if you have multiple instances

If you may have implemented multiple CF10 (or 11) instances on a single box (only an option in CF Enterprise/Trial/Developer), then you will find that unlike CF9 and earlier, the WS Config Tool does NOT list your available instances. (Update: This problem is fixed in the connector tool in CF2016.)

Instead, you need to run that wsconfig as will be found in each instance (such as C:\ColdFusion10\instance1\runtime\bin), which will rebuild the connection of any selected web site(s) to that instance.

And as I said above, you can check the date of the isapi_redirect.dll (for IIS, or mod_jk.so, on Apache) in the numbered folders under config\wsconfig after doing the reconfigure/rebuild, to confirm that the file's date is relatively recent.

How can I know whether a given update DID offer an updated connector?

This is a reasonable question. I keep saying you want to check the date of the connector file (.dll or .so file) to make sure it's "recent". Why don't I say what date to look for?

Well, the problem is that the date to which it should "be updated" depends on which CF update you've applied and also what web server you're using..

Adobe's technotes for each update often DO tell you if you need to update the connector after applying a give CF1/11 update. Just note that if you or others may have skipped doing that on a previous update (where it WOULD have been called for but you did not), then you will STILL need to do it after this later update you're applying.

Sadly, there's no single page on the web which lists what date a properly updated file will have for each corresponding CF update. I've thought about doing one. For now, you just need to review the technote for any update you are applying (and any you're skipping), and hope that if a connector update WAS required that Adobe indicated that. (Note that sometimes I have added comments in the Adobe blog posts where they have announced a given CF updates, to indicate whether the technote DOES say that or I have found that the connector IS updated based on testing.)

You *may* only need to do an "upgrade" rather than a "reconfigure/rebuild" of the connector

I had mentioned above that some of the updates only require an "upgrade" of the connector, not a full update/reconfigure/rebuild. A reconfigure/rebuild is actually easier (and will do the job, even if only an "upgrade" is required), but for some folks an upgrade may be preferred.

To do an upgrade, if it's called for, you go to a different directory, C:\ColdFusion10\cfusion\bin\connectors, and run Upgrade_all_connectors.bat (or Upgrade_all_connectors.sh, if on Linux). While you can double-click that file to run it, from a file explorer, it would be best to run it from the command line, so you can see any output from the result of executing it (which output is lost if you just double-click the file to run it).

And again, if you are on one of the more modern versions of Windows I listed above, you should open the command prompt "as administrator", which you can do by using start>programs>accessories and right-clicking on "command prompt" (among other ways).

(It is indeed lamentable that there is no "upgrade" option listed in the GUI for the web server configuration tool. You have to do it via the command line. It would be nice if some day Adobe may add that. Update: CF2016 did add that.)

But the point here is that this "upgrade" option does indeed just "upgrade" rather than "reconfigure/rebuild" the connectors, which is suitable for some but not all of the CF10/11 updates, and isn't quite as heavy-handed (reconfiguring the connectors causes CF to remove/rebuild files in that CF [coldfusion]\config folder and also updates your web server configuration as appropriate.)

Again, the technotes for each update (offered via the "more info" link on each update screen) will explain if a given update calls for "upgrade" vs an update/reconfigure/rebuild.

Where can I learn more about all this?

So after reading all this, you may be wonder, "how the heck am I supposed to have known all this?". Well, it's really not that buried.

• First, as I noted at the outset, there has been mention of this in most of the recent CF10 updates, literally on the update page shown to you as you apply the updates in the CF admin "Server Update" feature. It's just that many miss the mention, or don't read the "more info" link offered, which points to the technote. Now, it's worth noting that Adobe has only a couple of paragraphs of room on that update page, so that's why they don't get into more detail, but leave it to the technote to elaborate. And even then, some of the technotes have not been as clear as they could be on all this above. Obviously, there's a lot to communicate. They tend to be rather spartan. I hope this info will help more people facing these challenges.
• I'll also note that there is info on both the update process and running the web server configuration tool, both the GUI and the command-line interface, in the CF Admin docs. Many are surprised to find that there even are docs for the CF Admin. (There is also online help, on each page of the Admin, accessed by clicking on the "?" in the top right corner, but often that is less than what's in the fuller docs.) See especially:
  • Web server configuration
  • Server Update section
  • There is also coverage of web server configuration in the "Installing CF10" manual. See Configuring web servers.
• Besides the docs, there is much MUCH more info all about the CF10 update mechanism in a blog entry written by Adobe engineer Krishnap, offered at ColdFusion 10 Hotfix Installation Guide.

Finally, again if you need help with any of this, I provide CF server troubleshooting as an independent consultant. If you may interested to learn more, see my consulting page.

Update: Again, since writing this entry, I did a subsequent one on Still more reasons to make sure you have updated your #ColdFusion 10 web server connector, so be sure to read that next.

Hope all that's helpful. Let me know your thoughts.

For more content like this from Charlie Arehart:

• Signup to get his blog posts by email:
• Follow his blog RSS feed
• View the rest of his blog posts
• View his blog posts on the Adobe CF portal

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