Summary

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.

 


 

General Questions

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.

  • IIS_connector.bat
    Configures all sites in IIS to "site 0" or tied to global settings level (aka "(All)"). Sites inherit the filter and mappings are the site level, just like /JRunScripts.
  • Apache_connector.bat
    Configures the Apache connector. This batch file must be edited if using Apache 2 or installed to a location other than thedefault.
  • iPlanet_connector.bat
    Configures iPlanet or Netscape web servers. Needs to be edited always to correct -dir [https-sitename].
  • Remove_ALL_connectors.bat
    Uninstalls all configured Web Server connector information.
  • ConnectorList.bat (new in Updater 3)
    Lists all configured connectors and their settings. For Microsoft IIS, it lists all configured and unconfigured sites. Useful for ISPs to see which sites need to be configured. Use in conjunction with IIS_connector.bat to configure any newly added sites.
  • Upgrade_all_Connectors.bat (new in Updater 3)
    Used to upgrade all connector modules from a newer "wsconfig.jar." Upgrades may be required during Updater releases or when security patches for connectors are released.

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


Examples

  • Configure all existing IIS sites: (ISPs)



    java -jar wsconfig.jar -ws iis -site 0 -filter-prefix-only -map .cfm,.cfc,.cfml -coldfusion -v

    Does not automatically configure newly added sites after first"-site 0" run but users can run "-site 0" multiple times with IIS_connector.bat.
  • Configure a specific IIS site: (ISPs)



    java -jar wsconfig.jar -ws iis -site "web31" -filter-prefix-only -map .cfm,.cfc,.cfml -coldfusion -v

    On systems where all sites are .cfm, there is generally no need to configure an individual site.




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.

  • -filter-prefix-only

    Sets "ignoresuffixmap=true" which means to use the connector module as an extension. (Only used with IIS)
  • -coldfusion

    Instructs the connector installer (aka wsconfig.jar) that the installation is ColdFusion. In conjunction with -upgrade (Upgrade_all_connectors.bat), forces the replace of the connector module regardless of version or date stamp.




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:

  • The "deactivated" setting in the jrun.servlet.jrpp.JRunProxyService section in jrun.xml may have inadvertently been set to false when it was really intended to disable just the internal web server (JRun Web Server or JWS) in the jrun.servlet.http.WebService section. The "JRunProxyService" MUST be activated in order to configure any external web server connector.
  • You may be trying to use an Updater 3 wsconfig.jar with Updater 2 software. The communication protocols are different. If running Updater 3, the wsconfig.jar version (java -jar wsconfig.jar -info) should return 58498 or higher.
  • DNS issues. For example, the hostname on your machine does not match the entry in DNS, hosts file has an IP for your machine that isn't correct, and so forth).
  • Your web server service is not started.




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:

  • Pages return 404 or 500 errors.
  • Security Alert errors in the JRun default-event.log when trying to configure the web server using the wsconfig.jar: 04/21 07:23:29 error Security alert: attempt to connect to JRun server from a [Web Server IP Addr] host.
  • "Could not find JRun" type of errors running the web server config tool (wsconfig.jar): findServers(): attempting connect to port 2901 on host [CFMX IP Address] Could not connect to any JRun servers on host [CFMX IP Address]. Confirm that the JRun server is started.

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.

Microsoft IIS

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.

iPlanet/Netscape

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

Apache

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:

  • Unzip the mod_jrun20.so from the wsconfig.jar manually for your particular operating system. (connectors/apache/linux/prebuilt or connectors/apache/sparc-solaris/prebuilt, etc)
  • Place the mod_jrun20.so in thecf_root/runtime/lib/wsconfig/[n] directory, where [n] is the numeric directory found in the httpd.conf "JRun Settings" (example above is ../1)
  • Edit the httpd.conf file and change the JRun settings.

    Change from:

    LoadModule jrun_module"C:/CFusionMX/runtime/lib/wsconfig/1/mod_jrun.so"

    to:

    LoadModule jrun_module"C:/CFusionMX/runtime/lib/wsconfig/1/mod_jrun20.so"



    Change from:

    <IfModule mod_jrun.c>

    to:

    <IfModule mod_jrun20.c>
  • Restart Apache.




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.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy