[Looking for Charlie's main web site?]

When and how to upgrade CF web server connector, easier in recent CF releases

Note: This blog post is from 2019. 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.
Did you know that when you update ColdFusion, there is often a need to also update ("upgrade") the web server connector (for IIS and/or Apache)? Did you know that's gotten easier to do since CF2016 came out?

In this post (updated in Oct 2023, for reasons discussed below), I discuss:

While the connector update/upgrade process is indeed simpler since CF2016, I'll note that the CF update technotes for the recent releases (from 2016 to even 2023, I have confirmed in Oct 2023) still don't currently discuss the process for upgrading the connector, let alone how it's gotten easier. So what I share below may be a big (and nice) surprise, even for those who diligently read the CF update technotes.

Knowing when a connector upgrade is needed

The need to "upgrade" (update/recreate) the connector is mostly new since CF10, which was the first release where CF was based on Tomcat (and the underlying Tomcat web server connector, which Adobe modifies to support some functionality needed by some CF users). There were rare occasions that the old JRun-based connector (used in CF6-9) needed updating.

Thankfully, since CF2016, Adobe has included a table at the bottom of each CF update technote indicating both whether the current update and ANY previous updates may have required a connector upgrade. If you may be skipping some CF update, and THAT update indicates it called for the connector to be updated, then you need to upgrade it with

On "update" vs "upgrade" vs "recreate" connector

Here's a point of common confusion. If you look at the table at the bottom of the CF update technotes, the column heading indicates "Connector recreation required". It really should say "connector updgrade required". (This issue remains in Oct 2023 as I update this blog post, and I have just raised that issue again to Adobe.)

It's confusing because those who've been around a while may recall that PRIOR to CF2016, one DID have to "remove and recreate" a connector in order to "upgrade it" (or "update it", they're all same thing). As this post will explain, doing this "upgrade" is a lot easier as of CF2016, in the CF wsconfig GUI tool, though it was always an easy option for those who ran the wsconfig tool at the command line instead. Let's move on to discussing that.

How to apply the connector upgrade, via wsconfig gui or commandline

First, note that the wsconfig tool can be run either as a GUI or as a commandline tool. Also, there are helper scripts that even make working from the command line easier.

And good news (for those who use the wsconfig GUI) is that in CF2016 and above, it's far simpler to update the connector than it had been with CF11 and 10.

Upgrading connectors via GUI in CF2016 and later

Many may not notice it, but there is a new "upgrade" button in the wsconfig tool UI (to go with the -upgrade option in the wsconfig command-line tool that has long been available). One need merely run the wsconfig UI, choose an existing connector (from the list of them, such as might say localhost:cfusion), and then click "upgrade".

Note that you do need to do that for each connector.

And note that the tool will restart the web server on each upgrade. Sadly, you cannot prevent that web server restart. Indeed, it happens regardless of whether you click the "ok" button on the prompt indicating that, or if try to click the "x" on that prompt window.

Upgrading connectors via commandline

Whether you are working on a headless implementation of CF (no GUI) or just prefer to better automate/script things, note again that you CAN run the upgrade process by using the wsconfig tool from the command line instead. There are actually a couple of options for this.

1) First, the wsconfig tool itself can be found (as an exe in Windows or script in *nix) in the cfusion/runtime/bin folder (not cfusion/bin). You can get help from the tool itself at the command line (using --help).

In Windows, open the command prompt "as admin" and cd to the directory, such as:

cd \ColdFusion2018\cfusion\runtime\bin

wsconfig --help

(If the windows pops open and then closes, you have forgotten to open the command prompt "as admin".)

On Linux/MacOS/Solaris, you need to run as root (so using su, sudo, or other options as you may prefer), for instance:

cd /opt/coldfusion2018/cfusion/runtime/bin/

sudo ./wsconfig --help

As for the arguments needed for doing the upgrade, those differ based on your web server, web sites, and such. Besides that help offered in the command, you can also find more on these args documented here.

2) Second, there are also helper scripts (bat files for Windows, sh files for Linux) that further facilitate performing connector operations, including simply upgrading all connectors. See those files in the cfusion/bin/connectors folder (yes, quite a different folder than the others above, and mentioned only briefly in that last docs page.)

In particular, note the available " upgrade_all_connectors" script, which will indeed upgrade all connectors. It runs the "wsconfig -upgrade -v" command for you. Here is the Windows example:

cd \ColdFusion2018\cfusion\bin\connectors

upgrade_all_connectors.bat

And the *nix example:

cd /opt/coldfusion2018/cfusion/bin/connectors/

sudo ./ upgrade_all_connectors.sh

Note that this tool will indeed run updates of all connectors identified in the current CF version, whether IIS or Apache (someone on Windows could be running either or both). How does it know? They're listed in the config/wsconfig/wsconfig.properties file, which is how the wsconfig tool knows show what connections are displayed in the GUI as well.

Sadly, the tools above don't make any backups of what they going to change. Update: See the next section for how with the CF update in Oct 2023, the wsconfig upgrade process DOES backup the files that are changed.

So it's in your interest to take caution to first make copies of the files that the wsconfig tool would update (in CF and in your web server). This post is not the place to discuss all those details. I will say that if you want to be extra careful, take a snapshot if you're running a VM, or a backup of your machine or at least your web server config folders and the config/wsconfig folder within coldfusion. See a bit more in the next section.

If you run into trouble with these tools, I can help of course (often nearly immediately and quickly).

Update in Oct 2023: the wsconfig upgrade DOES now make a backup of the files it changes

Here's great news, and I am updating this post to point it out: as of the updates to CF2021 and 2023 in Oct 2023 (updates 11 and 5, respectively), the wsconfig tool DOES now backup the files it will change.

(Some will recall that since CF11, the tool made backups when you REMOVED a connector. I had complained to Adobe that this was nice but not enough, and this update addresses that problem finally.)

What updating the web server connector actually does

Usually, all the upgrade process will do is update the connector file (isapi_redirect.dll for IIS, or mod_jk.so for Apache), as typically found in the coldfusion config/wsconfig directory and the numbered folder associated with the selected connector (for Apache, the numbered folders may exist elsewhere, as your conf file references to ColdFusion will indicate).

As an aside, you may want to even look at the date of the .dll or .so file, in your connector folder, to see what date it is. This is how you can know if the file is out of date. Again, per the discussion above, many CF updates DO call for an update to the connector. If you have skipped that, you may find that your dll or so file is quite dated, which could be the cause of some problems you experience with CF. For CF2018, as of the current update 6 as I write this post (or CF2016, as of the current update 13), the file should have a Nov 2019 date. If it does not, that's confirmation that you need to update the connector (after applying the latest CF update.)

As a tip, if you do have multiple connectors to update, you could copy this one updated .dll file (for IIS, or .so file for Apache) into the other folders, and then restart the web server to effect the change in all of them. (Technically, the connector update may do more than just change that file, so this work-around should be used with caution.)

Note also that if you may have tweaked your setup to point the web server config at a different location than CF would use by default (as some do with Apache in Linux), you may need to copy the updated connector file to that new location.

Upgrading connectors via GUI for CF11 and 10

As a follow-up to my earlier discussion about how the wsconfig GUI now offers an "upgrade" button, back "in the old days", it was indeed more tedious. You would have had to REMOVE and then RE-ADD the connector (with the wsconfig tool). I discussed that (and the need to update the connector) in a 2013 post, "CF911: Why/when you MUST update the web server connector for ColdFusion 10/11 and may have missed it", and a follow-on post to that.

That process of removing/re-adding the connector was sometimes trivial, but sometimes a nightmare--especially if you had "tuned the connector" settings, or if you had manually tweaked some other aspect of the connector configuration. Those would be lost in the "remove" and you'd have to re-add the settings after the "re-adding".

Sadly, even folks using CF2016 and above don't know about the new upgrade button, so are still removing/re-adding the connector the "old-fashioned way", which is tedious and more error-prone.

Conclusion

This new upgrade button approach should be a great relief for them to learn about. (And I hope Adobe will please improve their ColdFusion update technotes to clarify the availability of this upgrade button for folks.)

If you need help with any of the above, I welcome questions here, of course, but I can also help you do the updates or connector upgrades, or other updates (such as the JVM or FusionReactor) via my short-term remote consulting, with satisfaction guaranteed.

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
Comments
Charlie Arehart, you are a CF lifesaver. Thank you for the post, for your concise information, for being there! I've appreciated your work since CF Developer magazine.
# Posted By SD | 7/28/20 8:39 AM
Thanks for the kind regards. As you may have noticed, yours is the first comment on this post since I wrote it nearly 9 months ago. So any encouragement is indeed appreciated. :)
Our security scan indicated our tomcat is outdated... we are on windows 2016 now and running cf10 enterprise and have applied all the 24 patches already.

How can we update the tomcat and leave cf10 without the need to upgrade CF10 as our budget is very minimal.

Is this possible?

Thanks!
# Posted By Dave | 2/11/21 2:41 PM
Dave, in a word: no. You cannot upgrade the Tomcat that underlies CF.

There's a bit more to consider, though.

First, as you may already know: with your being on CF10, you have more problems than your Tomcat being outdated. Adobe has not updated CF10 since 2017 (5 years after it came out in 2012), and they stopped updating CF11 in 2019, and will stop updating CF2016 as of later this month. The currently supported versions of CF are 2018 and 2021 (which came out in November).

But I realize that's not where you want to focus attention, given "very minimal budget". Sounds like time for you to explore Lucee, the open source alternative CFML engine. I realize "budget" may also refer to time". Some find the move to Lucee trivial and fantastic, others find it challenging and frustrating. But the allure of free may make it worth the effort.

As for this post, it's about updating the web connector that comes with CF. And whatever version one is on, they should always be sure to update that (wsconfig).

Getting back to being dinged about Tomcat being out of date, note that even people on CF2021, or the current latest updates of CF2018 and CF2016 would be dinged by security scans which say they are still on an "outdated" Tomcat.

But if they ARE on at least the March updates for CF2016 or 2018 (or CF2021), note that Adobe DID then implement an important security fix that WAS specific to Tomcat (addressing the "Ghostcat" vulnerability"), and they did it in such a way where while the Tomcat version did not change Tomcat to a version after they updated for that, the changes in CF and the connector DO address the ghostcat vuln. So at least they are not vulnerable to that.

We have to wait now for Adobe to create an update for CF2021 or CF2018 that will update Tomcat to a still more-recent version than it currently offers.

I realize that's of no help for you on CF10. Just sharing it for others reading alone.
Just applied the ColdFusion 2018 Update 14 (released May 2022) to a Linux server and ended up having to SSH onto the server, cd into the /opt/coldfusion2018/cfusion/bin/connectors and `sudo ./upgrade_all_connectors.sh`. Finally back in business. Thanks, brother!
# Posted By Steve Withington | 6/29/22 1:08 AM
Thanks, Steve. Glad to help wherever I can.
I can not thank you enough for this post, truly a life saver.
# Posted By Connor Maher | 10/24/23 9:22 AM
Thanks, Connor. Always a delight when an old post (in this case, from 2019) still helps people. And in fact I had updated this post earlier this month, so I'm all the more glad you found it after that.
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