This document describes the past and current behavior of the connector installer for ColdFusion MX (Standalone) Application Server. There were many changes to the Updater 3 connector installer to enhance it's use with ISPs with multi-site installations.
Where are the latest connectors?
For ColdFusion MX, download the latest ColdFusion MX Updater.
Are pre-Updater 3 installs compatible with Updater 3 connectors?
No, they are not. You must install Updater 3 to get the latest connectors and connector installer.
What is the wsconfig.jar?
This is the web server configuration tool. It installs and configures the JRun filter module (aka connector) for ColdFusion MX. It's also called "Connector Installer" or CI.
How do I know what version of the wsconfig.jar I currently have? What about the connectors themselves?
You can check to make sure that ColdFusion MX, including the web server connectors, was successfully updated as follows:
Run the following command line: (Windows shown)
c:\cfusionmx\runtime\jre\bin\java -jar c:\cfusionmx\runtime\lib\wsconfig.jar -info
The result should be: Macromedia JRun 4 (Build 58498).
In Windows Explorer, right-click on c:\cfusionmx\runtime\lib\wsconfig\jrunwin32.dll and select Properties.
Select the "version" tab. You should see File Version: 4.0.0.58498.
In Windows Explorer, right-click on c:\cfusionmx\runtime\lib\wsconfig\1\jrun.dll and select Properties.
Select the "version" tab. You should see File Version: 4.0.0.58498.
These are the current shipping ColdFusion MX Updater 3 connector versions.
To determine the version on Unix platforms, look at the Web server error log files: /logs/error.log (Apache) or /logs/errors (IPlanet/Netscape).
What are the .bat files incf_root/bin/connectors on Windows and why aren't these files on UNIX/Linux?
The .bat files help Windows users configure typical connectors like IIS or Apache on Windows without having to dig through the documentation for command line switches. They are located incf_root/bin/connectors.
On Unix and Linux installations where users choose to configure a web server on installation, a file calledcfmx-connectors-run.sh is installed incf_root/bin/connectors/. This contains all the correct switches for iPlanet and Apache and can be edited and used. If you do not have this in your installation, download it here. Future Updaters will include scripts for Linux and Unix.
How does the "-site" argument work as it pertains to IIS installations?
Sites are defined in the IIS metabase by number and name. Users configuring sites can use either the site number (from -list in ConnectorList.bat) or by site name, for example, "Default Web Site."
| IIS Site # | IIS Name | ColdFusion MX name/IIS site # |
| 0 | Master Properties | (All) / 0 |
| 1 | Default Web Site | (None) / 1 |
| 2-n | Web01,Site02,... | (None) / 2-n |
Are the wsconfig.jar -filter-prefix-only and -coldfusion switches new?
These switches are used to configure ColdFusion MX specifically. -coldfusion is new in Updater 3.
How do I get debug information for support while running the connector installer?
Look at the wsconfig.log for activity and use-Dtrace.ci=1 on the command line to see debug output if there are problems configuring your web server. Support will need this information.
java -Dtrace.ci=1 -jar wsconfig.jar [switches]
For each web server, what switches are mandatory during configuration?
If you have a Windows system, look at the .bat files incf_root/bin/connectors for details.
| Web Server | Command Line | Comments |
| Microsoft IIS | -coldfusion -ws iis -site [n] -filter-prefix-only -map .cfm,.cfc,.cfml | Site name or number accepted. Site name is case-sensitive. |
| iPlanet | -coldfusion -ws iplanet -dir "[path to /config]" -map .cfm,.cfc,.cfml | No -filter-prefix-only |
| Netscape | -coldfusion -ws netscape -dir "[path to /config]" -map .cfm,.cfc,.cfml | No -filter-prefix-only |
| Apache | -coldfusion -ws apache -dir "[path to /conf]" -map .cfm,.cfc,.cfml | No -filter-prefix-only |
I notice that when I run 'java -jar wsconfig.jar', a graphical UI is invoked with a JRun branding. The same thing happens when I run cf_root/runtime/bin/wsconfig.exe. Why can't I use these to configure my sites?
There are plans to do this in a future release of ColdFusion MX. At this time, users should not use the UI or use wsconfig.exe.
For Windows and IIS, the UI does not implement certain switches that are specific to ColdFusion MX, such as "-filter-prefix-only" and "-coldfusion". The UI does not set the .cfm mappings for the extension by default. IIS can serve up .cfm source (aka "View Source" problems) when the ColdFusion MX server is down because IIS has no idea what .cfm mappings are.
What can I do to resolve errors -12, 10053, or 10054 in the connector log files (jrun[date].log in IIS, error.log in Apache, errors in Netscape/iPlanet)?
These are resolved in the newest connectors in Updater Release 3.
How do I debug hanging conditions?
Hanging conditions can be diagnosed by obtaining a java stack trace. See TechNote 18339, Debugging stack traces in ColdFusion MX.
Trying to configure, I get the error "Could not connect to any JRun servers on host localhost. Confirm that the JRun server is started." Why does this occur?
This can happen in several circumstances:
What adjustments need to be made as an ISP with multiple sites being hosted on one server?
The cacherealpath attribute needs to be set to false in the jrun.xml. Otherwise, the wrong page may be displayed if templates of the same name exist under multiple sites. For instructions on how to change this setting, please see TechNote 18258.
My web server is multihomed with IP addresses in several different subnets. Is there any special setup for this configuration?
Yes, you must modify thecf_root/runtime/lib/security.properties file. Change the jrun.subnet.restriction or trusted.hosts settings using the instructions in the file. If you do not, you may see the following symptoms:
These issues are typically encountered when configuring a new web server instance or if a change was made to an existing web server, such as changing its IP address, causing it to fall out of the subnet mask or trusted.hosts list in security.properties.
I've followed the instructions in this TechNote but have still been unable to successfully configure my webserver. What else could I check?
Another program on the system may be interfering with the configuration process. Close all other programs, temporarily disable any unneeded services, anti-virus software, and firewall software and run the connector installer again.
The ColdFusion module for IIS is jrun.dll.
What are the major behavioral changes in Updater 3 in how the installer works?
The ColdFusion MX Gold installer only configured "Default Web Site" during installation if the user chose Microsoft IIS. The connector installer would install mappings and a site-level filter on the Default Web Site.
Prior to Updater 3
The connector installer (wsconfig.jar) installs a filter and a set of mappings (.cfm, .cfc) in IIS. The configuration is determined by the behavior of the [-site] argument. The -upgrade switch compared dates of old and new jrunwin32.dll and jrun.dll in wsconfig.jar to decide whether to replace them.
Due to a bug in laying down the files in Updater 1 and 2, the jrun.dll and jrunwin32.dll "last modified" date was set to the date they were installed on the system. The existing modules had anewer date than the ones in the wsconfig.jar so they were not replaced. This could happen if you installed ColdFusion MX Gold - configured IIS during install - then immediately installed Updater 2. (Fixed in ColdFusion MX Updater 3 or higher)
Updater 3 and beyond
Updater 3 makes it easier to administer the JRun filters/modules for ISPs who need to add/remove single sites frequently. Pre-Updater 3 installer code made this more difficult. The effort is now reduced. The number of \wsconfig\[n] directories is less by allowing the user to runcf_root/bin/connectors/IIS_connector.bat over and over and adding sites to the "Master Properties" and mappings at the global IIS level. ISPs or multi-homed systems can add sites without having to worry about the complexity of the ../runtime/wsconfig directory structure (some pre-Updater 3 systems might have 50 separate module directories - one for each site).
Changes to command line switches
Changes to the command line switches for the wsconfig.jar (Web Server Configuration Tool) are as follows:
| Switch | Pre-Updater 3 | Updater 3 and beyond |
| -site 0 (IIS_connector.bat uses this) | Configure (All) UNCONFIGURED sites when connector installer is run. Adds a GLOBAL filter in IIS. Adds mappings at the global level. Adds a /JRunScripts virtual directory for each individual site. Could only run once. After that each site had to be added individually (-site "web03") with its own /wsconfig/[n] directory. |
(change) Adds any newly added sites to the"All" (site 0) list. "-site 0" can be run repeatedly to add sites at the GLOBAL level. Adds mappings at the site level for each individual site. Can simplify multi-site systems with one \wsconfig\[n] directory/jrun.dll. |
| -site [n] non-zero | Configures site-level filter in IIS. Adds mappings at the site level. Creates additional directory undercf_root\runtime\wsconfig\ with jrun.dll. ISPs could have 100 directories each with jrun.dll. Hard to manage. |
No changes. |
| -site 1 (Default Web Site) |
Standard configuration during CFMX Gold install. Creates cf_root\runtime\lib\wsconfig\\1 directory. Installs mappings locally like "site [n]" above. |
No changes. |
| -r -site"name" (remove one site) |
Removes individual site if added as 'site [n]' (non-zero). Note: Could not remove if originally added via "-site 0" (All) global area. |
Removes site configuration. Doesn't matter if it was added to -site 0 (All) or [n]. |
| -list | Format only showed site names. | Format shows configured and unconfigured site list. Shows site numbers and names. |
| -coldfusion | Not available. | Used in conjunction with -upgrade to force replace of connectors and jrunwin32.dll. |
| -upgrade | Date compare used to replace older connectors. (Problematic since all connectors got installed with last modified"Today" rather than the date inside the wsconfig.jar. Made upgrades difficult and sometimes fail silently.) |
Force mode to upgrade connectors. Uses version check. |
| -filter-prefix-only | Not used in IIS_connector.bat. | Added to IIS_connector.bat (IIS specific) |
Why do I get the error "IIS web site "web03" does not exist" when running the command line?
The -site switch queries the metabase and the name of the site is case-sensitive. Maybe the site is "Web03". Use IIS Admin or ConnectorList.bat to view the site name.
I've added new sites and they're not serving ColdFusion pages. Why doesn't '-site 0' configure all my sites?
The behavior of '-site 0' is to configure all unconfigured IIS sites into the global Master Properties of IIS at the time the connector installer runs. Any newly added sites can be configured to the global level by repeatedly running the IIS_connector.bat file which contains the "-site 0" switch. It may be a good idea to do a -list first to see all configured and unconfigured sites or run the ConnectorList.bat which does the -list for IIS for you.
How do I configure my newly added IIS sites to the Master Properties (-site 0, "(All)") section so there is only one /wsconfig/[n] directory for all my sites?
Updater 3 was rearchitected to be more user friendly for ISPs or users with multi-site installations. You can continuously run IIS_connector.bat which uses the "-site 0" argument to add all unconfigured sites to the "(All)" or at the Master Properties level in IIS. Use:
java -jar wsconfig.jar -list
or
connectorlist.bat in cf_root/bin/connectors to show configured and unconfigured IIS sites.
Updater 2 users with working systems which have many /wsconfig/[n] sub-directories may leave their installation as is. Updater 3 will not change the configuration.
Does adding a single site with "-site [sitename or number]" in it's own SEPARATE configuration still work in Updater 3, creating an additional /wsconfig/[n] directory and configuration and ColdFusion module (jrun.dll)?
Yes. We did not provide a batch file for this functionality but replacing "-site 0" with "-site [n]" or "-site [sitename]" in the IIS_connector.bat run from the command line fromcf_root/bin/connectors will still work correctly.
java -jar ..\..\runtime\lib\wsconfig.jar -ws IIS -site"web03" -filter-prefix-only -map .cfm,.cfc,.cfml -coldfusion -v
I'm manually configuring IIS but the command line option fails with the error below. What causes this error?
Error getting IIS web site list from the metabase. The IISAdmin service can not be disabled.
The connector installer has detected that the IIS Admin service is disabled in the services control panel. The connector installer cannot configure IIS when this service is disabled. Enable the service by setting the IIS Admin Service startup properties to manual or automatic and then re-run the connector installer.
The ColdFusion module for IPlanet isjrun_nsapi35.dll (Windows) andlibjrun_nsapi35.so for Unix/Linux.
Why is -filter-prefix-only not used in the .bat files?
This switch is only used for Microsoft IIS. It tells the IIS filter to pass any request with .cfm, .cfc, or .cfml in the request to the extension and also allows IIS security to be used before the extension is run.
I get an IMAGEMAP error when serving .cfm pages from my document root. What's wrong?
A bug in the installer, logged as issue 49425, causes the setting"ignoresuffixmap" to be set to true in the obj.conf. It should be set to false.
What would a typical Web Server Configuration Tool command line configuration for Unix/Linux look like?
Netscape:
/opt/coldfusion/mx/jre/bin/java -jar /opt/coldfusionmx/runtime/lib/wsconfig.jar -ws nes -dir [location of /config] -map .cfm,.cfc,.jsp,.cfml -coldfusion
iPlanet:
/opt/coldfusionmx/jre/bin/java -jar /opt/coldfusionmx/runtime/lib/wsconfig.jar -ws iplanet -dir [location of /config] -map .cfm,.cfc,.jsp,.cfml -coldfusion
The ColdFusion module for Apache 1.3 is mod_jrun.so (Windows or Unix/Linux) and for Apache 2.0 ismod_jrun20.so (also Windows or Unix/Linux). We strongly recommend all users upgrade to ColdFusion MX Updater Release 3 to take advantage of the latest fixes.
Why is -filter-prefix-only not used in the .bat files?
This switch is only used for Microsoft IIS. It tells the IIS filter to pass any request with .cfm, .cfc, or .cfml in the request to the extension and also allows IIS security to be used before the extension is run.
Where is the Apache connector source located and how can I compile my own Apache EAPI connector?
For ColdFusion MX Updater Release 3 or higher, the code and compile instructions are included incf_root/runtime/lib/wsconfig.jar in the /connectors/src/ApacheModule.zip file. See ApacheBuildInstructions.txt in the ApacheModule.zip.
I'm on Linux/Solaris. Can I use the binaries in Updater 3? What conditions will require me to compile the Apache connector from source?
See the following two questions for information.
How can I get rid of the error "[warn] Loaded DSO /opt/coldfusionmx/runtime/lib/wsconfig/1/mod_jrun.so uses plain Apache 1.3 API, this module might crash under EAPI! (please recompile it with -DEAPI)"?
Users getting this message will need to compile the Apache 1.3.x connector and replace the existing one. For ColdFusion MX Updater Release 3 or higher, the code and compile instructions are included incf_root/runtime/lib/wsconfig.jar in the /connectors/src/ApacheModule.zip file. See ApacheBuildInstructions.txt in the ApacheModule.zip.
My system is running slow/crashing. We have an Apache version with mod_ssl or a variant. We see a lot of sockets in CLOSE_WAIT state. How can I resolve this?
Users encountering this scenario will need to compile the Apache 1.3.x connector and replace the existing one. For ColdFusion MX Updater Release 3 or higher, the code and compile instructions are included incf_root/runtime/lib/wsconfig.jar in the /connectors/src/ApacheModule.zip file. See ApacheBuildInstructions.txt in the ApacheModule.zip.
I'm using Linux/Solaris with ColdFusion MX Updater Release 2 and have implemented the suggestions and connector binaries from TechNote 18340. What should I do?
ColdFusion MX Updater Release 3 provides higher stability and numerous bug fixes above what is provided in TechNote 18340. We strongly recommend applying ColdFusion MX Updater Release 3.
What would a typical Web Server Configuration Tool command line configuration for Unix/Linux look like?
/opt/coldfusionmx/jre/bin/java -jar /opt/coldfusionmx/runtime/lib/wsconfig.jar -ws Apache -bin /opt/apache2/bin/httpd -script /opt/apache2/bin/apachectl -dir /opt/apache2/conf -map .cfm,.cfc,.jsp,.cfml -coldfusion
My Apache system hangs in some cases. What are the -12, 10053 and 10054 errors in the error.log?
These errors and the hanging conditions are fixed in ColdFusion MX Updater Release 3. If you have a configuration that requires you to recompile the connector (EAPI warnings in Apache 1.3 or CLOSE_WAIT), use the Apache connector source in Updater 3. The code and compile instructions are included incf_root/runtime/lib/wsconfig.jar in the /connectors/src/ApacheModule.zip file. See ApacheBuildInstructions.txt in the ApacheModule.zip.
What is the easiest way to remove an Apache configuration?
On Windows, if no other web server is configured, you can usecf_root/bin/connectors/Remove_ALL_connectors.bat. This will do a -u(ninstall) of all connectors.
Another way is to use the -r(emove) switch (platform independent) if you have more than one connector configured so other web server configurations are preseved. Use the -dir switch to identify the /conf directory to the connector installer.
/opt/coldfusionmx/jre/bin/java -jar /opt/coldfusionmx/runtime/lib/wsconfig.jar -r -ws Apache -dir /opt/apache2/conf -v
I've configured Apache 2.0 on my system but it appears to deploy the Apache 1.3 connector mod_jrun.so instead of mod_jrun20.so and configures httpd.conf incorrectly. No pages are served or the source code is seen. Can I still configure Apache 2.0?
Yes. There are some Apache installations (Mandrake for one) that aren't recognized by the connector installer at this time. Most supported Apache installations are recognized such as Apache.org, RedHat, IBM and Stronghold and others.
If you have the problem described above, here is what the httpd.conf may look like:
.. # JRun Settings LoadModule jrun_module "/opt/coldfusionmx/runtime/lib/wsconfig/1/mod_jrun.so"<IfModule mod_jrun.c> JRunConfig Verbose false JRunConfig Apialloc false JRunConfig Ssl false JRunConfig Ignoresuffixmap false JRunConfig Serverstore"/opt/coldfusionmx/runtime/lib/wsconfig/1/jrunserver.store" JRunConfig Bootstrap 127.0.0.1:51010 #JRunConfig Errorurl <optionally redirect to this URL on errors> AddHandler jrun-handler .cfm .cfc .cfml .jsp .jws</IfModule>
You can still get Apache 2.0 working even if the installer does not recognize it as an Apache 2.0 installation by doing the following:
Should I ever have to compile the Apache 2.0 connector manually as is needed sometimes with Apache 1.3?
All known issues were addressed in ColdFusion MX Updater 3. Only the Apache 1.3 connector needs to be compiled manually and only if the error.log shows the EAPI warning or if the Apache version is some mod_ssl derivative.
What Apache versions are currently supported with ColdFusion MX Updater 3?
Macromedia suggests users run the latest Apache web server versions. At times, Apache will release security fixes or point releases and the connector may throw "unsupported version" errors during configuration or on startup with the newer Apache version. When this happens, Macromedia will release a new wsconfig.jar that will work with the latest ColdFusion MX updater.
ColdFusion MX Updater 3 works with Apache 2.0.43-2.0.45. If you use ColdFusion MX with Apache web server 1.3.x, Updater 3 is supported with version 1.3.26 or later.
Twitter™ and Facebook posts are not covered under the terms of Creative Commons.
