CF911: Help, How do I connect sites to a new instance w/ the ColdFusion 10/11 webserver config tool?

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

The solution is relatively easy, and the problem could maybe be fixed (or at least warned about) by Adobe (and I just filed a bug report for it). Until that happens, I wanted to share this. For more, read on.

The situation

If you're using CF 10 or 11, in the Enterprise, Trial, or Developer edition, you can add a new instance of CF, just like you could in the old Multiserver edition of CF 9 or earlier. (And as with CF9, you cannot add instances using CF 10/11 Standard. If you're using that edition, you may not want to bother reading any further. Same with if you never add instances in Enterprise/Dev/Trial.)

And in that CF9 or earlier multiserver edition, you'd find that when you used the CF web server configuration tool (such as from the Windows Start menu, or from the command line in jrun4\bin), you could easily connect any site (in IIS, Apache, etc.) to any instance, whether the cfusion one or a new one you created.

(I'm speaking primarily of the UI version of the wsconfig, but even the command-line version let you point to any instance.)

The problem in CF10 or 11

In CF10 or 11, though, when you launch that web server configuration tool UI (typically from the Start menu in Windows), the UI will never let you point to any instance. See the image below:

Besides the confusion that it's also labeled "AppServer Cluster" (which only adds to confusion), the drop down will never list any instance names (not the cfusion, nor any new ones you add, though if you DO add a cluster, you can to point THAT there.)

The fact is that when you launch the wsconfig tool that way (like from the Windows Start menu), it's really running the wsconfig tool in [cf]\cfusion\runtime\bin. And as such, you can use it ONLY to connect sites to THAT instance (the cfusion instance).

But what if you DO add a new instance? How do you connect a site to that? (Some have wondered if they had to add the instances to a cluster just to be able to connect a site to the instance, and of course that's not necessary.)

Sidebar (a few comments):

FWIW, as far as I know, this is NOT AT ALL a problem limited only to Windows. I know I'm showing a Windows screen above to see the files, and referring to the Windows Start menu, but I'm pretty sure this issue is the same in using the wsconfig UI in any OS. The UI is a Java applet.

And yes, I do realize there's no Start "menu" in Windows 8 or Server 2012, but you can search for and launch the web server configuration tool when clicking its "start" button, and that web server config tool will launch this same java UI.

And finally, though I've not tried it, I suspect the same problem of only being able to connect to the current instance will happen with the command-line variant. I'd appreciate hearing from anyone who can confirm that.

Again, though, what gives with this issue of not seeing instance names in the wsconfig UI?

The simple (but not so obvious) solution

The simple solution, though not an obvious one, is to run the wsconfig tool FROM WITHIN THE INSTANCE to which you want to connect a site.

So if you've added an instance "instance1", run the wsconfig tool at [cf]\instance1\runtime\bin. (If you're on Windows, be sure to right-click and use "run as administrator". More on that later below.)

When launched that way, you STILL will not see any instance name listed as an option in the UI that pops up, but a connection made with that version of the tool WILL create a connection to that site (and that site only).

(And you should be able to name this instance if you run the wsconfig tool completely from the command line, with all the arguments, if you run things that way).

A curious observation

There's one more nuance to/curiosity about all this: once you DO add a site to another instance, you'll find that you now CAN SEE ALL connections of ALL SITES to ANY INSTANCES in the wsconfig tool UI, REGARDLESS of whether you open it in the cfusion or other instance directory. That only adds to some confusion. While it let's you SEE them as connected, note that it still does NOT let you point to the other instance(s) when you try to ADD a new site connection. Here's an example showing multiple instances connected to sites:

And it looks the same whether you launch it in the cfusion or other instances. I'll offer a thought on why this is so, in a moment.

Though I've known of this challenge of the wsconfig tool and instances for months, I just never got around to reporting it here, or filing a bug report. Sorry, just so busy. But I had someone ask me about it just tonight (someone quite experienced in CF), and I decided I really needed to put this out there (in addition to answering him directly).

A better solution, I'd propose (and have filed a bug report)

What could Adobe do? Well, it'd be great if they could get the "main" version of the tool (the one that runs from the Start menu) to work as it did before, letting you point to any instance. But I suspect the reason that can't and won't happen is the change in CF10+ so that each instance has its own complete directory. As I noted above, in CF9 and earlier, we ran the wsconfig tool from the jrun4\bin, and you'll remember that each instance was under jrun4\servers. So some things were in the instance, some things were at the top level (like the jvm.config, which applied by default to all instances).

In CF10+, they've changed things so that new instances are right under the cf directory, and they each have all their own things (their own jvm.config, their own wsconfig, and so on). That may be too important (and challenging) a switch to be able to "go back" to having "one wsconfig to rule them all". We can hope, but I doubt it will happen.

And remember how I said the tool DOES show all connections to all instances? I suspect that's because technically that info--the info indicating what sites have been connected to what connectors and instances--is actually stored in one of the few places that is NOT within an instance folder. It's in the wsconfig.properties file, in the [cf]\config\wsconfig folder. It can see it there. It's just that it doesn't seem to be able to find and name all the instances when the tool is trying to ADD connections.

Maybe we could argue that the wsconfig.exe tool should be moved to THAT LOCATION and be made to be able to list and allow adding sites to ANY instance.

In the meantime, Adobe could (and should) at least modify the UI (and the command-line tool's error messages, if needed) to clearly warn people that if they are trying to add a site to an instance other than cfusion, they MUST use the wsconfig tool from within that instance.

And I've just filed a bug report, reporting the issue and proposing the same thing. If you're bothered by this problem, do go add your votes/comments there. Adobe take votes very seriously in considering how to triage bugs. (Though I again applaud them for fixing so many bugs recently, as I blogged about last week.)

Some reminders/warnings about using the wsconfig tool

Finally, some reminders/warnings about using the wsconfig tool:

• Don't forget to use right-click and use "run as administrator" when running the tool in Windows. If you don't, some actions it should do will not be performed. (And sadly, even when you do this, you may find some things may not work right if you or someone before you forgot to do that in the past.) And no, it DOES NOT MATTER that you "are an administrator". The problem is that this tool is not able to prompt you to "elevate your privileges" like some other Windows tools do.
• Beware that when you run the wsconfig tool to "reconfigure the connector" (remove and then add back a connector), as you may need to do when a CF update calls for that), you WILL lose any tweaks you may have made to the connector files (as the Adobe team has blogged about for CF11 and CF10. For more on my warning about this and some other things related to reconfiguring the connector, see my comments 23 and 24 there.
• And about that "tweaking" discussed in the blog entry, as I have also mentioned in comments in the CF11 blog entry, note that sometimes really all you really need to "tweak" is the connector timeout (not the threads). I know that sounds heretical, but I've found it to be so in helping now dozens of people. See my comment 38 there.
• Finally, note that I've created a couple of bug reports related to those last two issues, as pointed to in comment 27 there. Again, if these issues concern you, add your votes to the bug reports.

I have quite a bit more I want to share about the wsconfig tool, and especially about dealing with issues when things don't work, and the the underlying configuration files (in CF, and the web server) which can get quite messed up when things go wrong, and how that happens, how to rectify things, and so on. I find myself helping people with this about every couple of weeks in my CF server troubleshooting consulting.

Of course there are a LOT of things I help people deal with, and some over and over, so I try to arrange time to write up these blog entries to help everyone. I welcome your feedback and encouragement.

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