ColdFusion Server 4.5
Release Notes -- Updated November 22, 1999

Contents

• System Requirements
• Before installing ColdFusion on Linux
• Upgrading to ColdFusion 4.5
• Known issues: All platforms
• Known issues: Windows NT
• Known issues: Linux
• Known issues: Solaris
• Changing the way Tokens are generated
• Migrating a ColdFusion UNIX registry to ColdFusion 4.5
• Redirecting processing to a Custom Error Page
• Load Balancing and Failover with ClusterCATS
• Configuring the Apache Web Server
• Running Allaire Forums under ColdFusion 4.5

Welcome to ColdFusion Server 4.5. One of our goals in this release is moving to a new platform-independent code base. This evolution means changing many of the core libraries that support functionality like CFMAIL, CFPOP, CFHTTP, and CFLDAP.

Use these release notes to stay apprised of important information relating to ColdFusion Server installation and configurations. On this page, you'll also find details about known problems.

Many new features and enhancements make this a significant upgrade, as well. For information about new features and enhancements, see the New Features page.

ColdFusion Server System Requirements

ColdFusion Server 4.5 Enterprise Edition for Windows

System

• Windows NT 4.0
• Intel Pentium or higher
• 100 MB hard disk space
• 128 MB RAM

Web servers

• Microsoft Internet Information Server (IIS) 4.0
• Netscape Enterprise Server (NSAPI) 3.51 and 3.6
• Apache API 1.3.6 and higher
• WebSite Server API (WSAPI)
• Common Gateway Interface (CGI)

NOTE: Load-balancing and fail-over support is available only on IIS (4.0) and Netscape (3.5 and 3.6)

ColdFusion Server 4.5 Professional Edition for Windows

System

• Windows 95/98 or Windows NT 4.0
• Intel Pentium or higher
• 50 MB hard disk space
• 32 MB RAM (128 recommended)

Web servers

• Microsoft Internet Information Server (IIS) 4.0
• Netscape Enterprise Server (NSAPI) 3.51 and 3.6
• Apache API 1.3.6 and higher
• Microsoft Personal Web Server (PWS)
• WebSite Server API (WSAPI)
• Common Gateway Interface (CGI)

ColdFusion Server 4.5 Enterprise Edition for Linux

System

• Red Hat Linux 6.0 or greater
• 64 MB RAM (128 MB recommended and required for clustering support)
• 70 MB hard disk space (100 MB required for clustering support)

Web servers

• Apache API 1.3.6 and 1.3.9

NOTE: Load-balancing and fail-over is supported only on Apache (1.3.6 and 1.3.9) Web servers.

ColdFusion Server 4.5 Professional Edition for Linux

System

• Red Hat Linux 6.0 or greater
• 64 MB RAM (128 MB recommended)
• 70 MB hard disk space

Web servers

• Apache API 1.3.6 and 1.3.9

NOTE: Load-balancing and fail-over is supported only on Apache Web servers.

ColdFusion Server 4.5 Enterprise Edition for Solaris

• OS: Solaris 2.5.1, 2.6, or Solaris 7 running on Sparc
• Memory: 128 MB
• Disk space: 128 MB
• Web Servers : Netscape or Apache

Patches Required for Solaris 2.5.1:

• Solaris patch 103640-19 or higher (kernel patch)
• Solaris patch 103663-10 or higher (libresolv.so for threaded applications)
• Solaris patch 106529-04 or higher (LibC: Shared library patch for C++)

Solaris 2.5.1 with ClusterCATS load balancing:

• Solaris patch 103582-18 or higher (/kernel/drv/tcp patch)

Patches Required for Solaris 2.6:

• Solaris patch 105181-09 or higher (kernel patch)
• Solaris patch 105591-06 or higher (LibC: Shared library patch for C++)

Patches Required for Solaris 7:

• Solaris patch 106327-05 or higher (LibC: Shared library patch for C++)

[These patches are available at access1.sun.com]

Packages Required:

The following package must be installed on your system:

• SUNWxcu4 -- The XCU4 Utilities

Web servers

• Netscape Enterprise Server (NSAPI) 3.51 or 3.6
• Apache API 1.3.6 or higher
• Common Gateway Interface (CGI)

NOTE: Load-balancing and fail-over support is available only on Apache (1.3.6 and 1.3.9) and Netscape Web servers.

Before installing ColdFusion on Linux

Before installing ColdFusion on Linux, please note the following considerations:

• Allaire recommends running your RedHat Linux web server on a single-processor Pentium machine. We have found that this configuration currently handles heavy load slightly better than a multi-processor machine configuration. For large Linux site deployment using Linux server farms, the load balancing and service-level fail over capabilities of ColdFusion Enterprise can be used to maximize overall site efficiency, scalability and availability.
• For performance reasons, Allaire recommends that during the RedHat Linux 6.x install, you choose either a Linux "Server" or "Custom" installation rather than a "Gnome" or "KDE" Workstation installation. After installation is complete, you should also make sure that your server network is configured properly, and that the line "ServerName" in /etc/httpd/conf file is uncommented and "localhost.localdomain" is changed to "yourserver.domain.com".
• The installation procedure assumes you are installing from a CD. If you purchased and downloaded ColdFusion from the Allaire Online Store, follow the download instructions found there and then follow the install procedure below, substituting the CD location for the directory in which you downloaded ColdFusion.
• You must log in and run the installation as root. The installation script will prompt for the user you want ColdFusion to run as (default "nobody"), and it is recommended that a ColdFusion machine user account be created and supplied to the installation script for security reasons.
• By default, the installation script installs ColdFusion into the /opt directory. If you want to install ColdFusion into a different directory, you must create that directory before running the installation script. The installation script will create a symbolic link from /opt/coldfusion to wherever you installed ColdFusion.

Upgrading to ColdFusion 4.5

Note the following when upgrading to ColdFusion 4.5 from previous releases of ColdFusion:

• ColdFusion Server version 4.5 ships with the Administrator setting, "Suppress whitespace by default," enabled. Some CFML applications have depended on CFML' s pre-4.5 behavior, which was to leave all whitespace present in the template. Such applications can be fixed in one of two ways:
  1. Disable the "Suppress whitespace by default" feature in the Administrator. Note that the server must be restarted for this change to take effect.
  2. Use <CFPROCESSINGDIRECTIVE SUPPRESSWHITESPACE="NO"> tags to guard the code that depends on the pre-4.5 whitespace preserving behavior. This is similar to using an HTML <PRE> tag around preformatted data.
• CFCATCH.EXTENDEDINFO is now available for all structured exception types. Certain unstructured exceptions, caught by CFCATCH or CFERROR with TYPE="ANY", may not contain an EXTENDEDINFO variable. All such exceptions can be distinguished by their type, which will be "UNKNOWN."
• In releases prior to ColdFusion Server 4.5, the ColumnList function would return columns added by QueryNew in random order. Now ColdFusion returns columns in the same order in which they were added.
• ColdFusion 4.5's CFCATCH selection logic differs slightly from ColdFusion 4.0. In ColdFusion 4.0, the first matching CFCATCH block encountered would be selected to handle an exception. ColdFusion 4.5 scans a CFTRY tag's entire list of CFCATCH blocks to find the closest match. For example, if a CFTRY tag has a CFCATCH TYPE=TEMPLATE block, followed by a CFCATCH TYPE=MISSINGINCLUDE block, ColdFusion 4.0 will select the TEMPLATE block to handle a MISSINGINCLUDE exception, while ColdFusion 4.5 will select the MISSINGINCLUDE block. ColdFusion 4.5 can be reset to handle a template using ColdFusion 4.0 rules by setting the compatibility setting, <cfsetting catchexceptionsbypattern=no>
• The cfcrypt utility has been renamed cfencode.
• The ColdFusion Administrator Settings page has been broken into two separate pages: Settings and Caching.
• A new Locking page has been added to the ColdFusion Administrator Server section to cover the new engine options for locking of shared scoped variables (server, session, application). For details about the new locking options in the Adminstrator refer to New Features document.
• UNIX only: Because ColdFusion no longer uses the Bristol WindU libraries, the Fast Date/Time Parsing option has been removed from the Server Settings page. This option is no longer necessary.
• Allaire does not recommend running a mixed-version cluster. All cluster members should be upgraded to the same version.
• Cluster members on Solaris servers must be deleted prior to upgrading to V4.5. The cluster members should be recreated once V4.5 has been applied.
• Session-aware load balancing is enabled by default on V4.5.
• Cluster members join a cluster in active mode by default.

Known Issues: All platforms

• In order to make use of the CFSERVLET tag in ColdFusion 4.5, you need to make sure you have a compatible version of JRun. JRun 2.3.3 build 156 is the appropriate build. This patch can be downloaded from the ColdFusion Beta site. This patch will be available during the beta cycle and on the ColdFusion 4.5 CD thereafter.
• If the default client storage is set to "Cookies," the "Browse" buttons in the ColdFusion administrator will generate an error. This is due to the use of CFLOCATION and cookies on the same page (11114).
• CFEXECUTE captures program output from the child program's "standard output" file, but not from its "standard error" file. Since many programs send error diagnostic output to "standard error," a program may seem to have produced no output when it did, in fact, produce diagnostics.

  Workarounds include:

  1. Within the child program, redirect error messages and diagnostics to the standard output file.
  2. Use a wrapper program or shell script that redirects the child program's standard output and standard error streams to the wrapper's standard output stream. Then use CFEXECUTE to invoke this wrapper. [12869]
• In ColdFusion 4.5, the site-wide "Missing template" handler (selected via the Administrator) will not install itself as a default MISSINGINCLUDE handler, which would handle missing template errors from <CFINCLUDE> or <CFMODULE> tags. To install the site-wide template as a MISSINGINCLUDE handler, include this tag in your Application.cfm:

  		<cferror type="exception" 
  		  exception="MissingInclude" 
  		  template="myApp_missingTemplateHandler.cfm">

  Substitute the name of your site-wide missing include handler for "myApp_missingTemplateHandler.cfm"

• If you are using DateCompare to compare two dates and both dates are exactly the same except that the first date passed is earlier by x seconds, you would expect a return value of -1 if you passed "s" as the 3rd parameter. In fact, it returns 1. (9339).
• Developers should avoid using CFSCRIPT keywords as variables in their code. The Evaluate function will handle some of them currently, but this behavior may be changed in a future release.
• Only one instance of ColdFusion can be run on any given system at a time.
• The _eurodate and the _date form field suffixes for server side validation do not work properly. The problem allows dates like 01/25/1997 in the _eurodate field and dates like 25/01/1997 in the _date field. (1173)
• The data source name "Registry" should not be used when creating an external data source for client variables. A data store named "Registry" already exists for the option of storing client variables in the registry.
• The MOD operator returns an invalid negative number when using large numbers (10 digits). For example, the statement, "#Evaluate(3013228971 MOD 256)#", should return 171 but instead returns -85. This works on some, but not all 10 digit numbers. (2588)
• If you include a CFHEADER and a CFLOCATION in the same template and run it, you will get "Document contains no data" even though the URL in the CFLOCATION, when run by itself, results in page output. (2356)
• Currently, <CFSETTING SHOWDEBUGOUTPUT="Yes"> simply restores the original level of debugging (which is usually none). We hope to fix this in a future release, but there is a workaround: Use the ColdFusion Administrator to turn on debugging output, then include <CFSETTING SHOWDEBUGOUTPUT="No"> in an Application.cfm file. This will build the necessary high-level data structures to collect debugging output, but it will suppress the display unless a subsequent <CFSETTING SHOWDEBUGOUTPUT="Yes"> tag is processed.
• Passing numeric data to the ColdFusion IsDate and ParseDateTime functions can yield unexpected results. For example, IsDate may return TRUE for numeric data that are not dates. This may be attributable to the underlying Windows API functions on which these ColdFusion functions are based. We are investigating this issue. This behavior occurs when passing data ColdFusion interprets as numeric. For example, single decimal point numeric data such as "0.1," "21.6667", multiple decimal point numeric data, such as "1.2.3", and comma separated data, such as "0,1" create unexpected results.

  To work around this behavior, it is always advisable to only pass string data in a supported format to the IsDate and ParseDateTime functions, or, generate date-time data using the Now or CreateDate functions.

• The encrypt function gives different output than it did in 4.0.x version. (10446)

Known Issues in this release: Windows NT

• The ColdFusion uninstaller doesn't stop CF services, and doesn't remove the services. If CF services are running, uninstall complains that cfserver.exe is in use, and aborts. After manually stopping the services, uninstall runs, but the services aren't removed. (12166)
• The CFQUERYPARAM tag is not inserting data correctly on Informix using the native driver. (12483)
• The CFIMPERSONATE tag, using the TYPE=OS attribute won't work if the account under which ColdFusion is running does not have rights to logon the user.(12544)
• The behavior for COM objects that return a VT_NULL has been changed. In previous versions the return values was "TRUE". In the current version, the return value is an empty string (""). This was implemented to be consistent with other scripting languages, and given that the current version of ColdFusion does not have a concept of NULL values.
• Java suport requires JDK 1.2 or JRE 1.2 to be installed, this can be found at http://java.sun.com/products/jdk/1.2/jre/index.html.
• To continue using the CFX_J custom tag, please navigate to the Custom Tags page, and delete the current entry for CFX_J. Now add a new entry with the same name, and specify the type as "Java". Please leave the "Classname" empty (important).

  You will now be able to use the the CFX_J tag as before.

  Please note that Allaire will phase-out this tag in future releases, and recommends that you simply convert it to a Java Custom tag.

  For example, if you currently use the CFX_J tag that has the CLASS attribute set to "Foo", then to use a Java CFX, you would do the following:

  1. Rename your custom tag to something like "CFX_Foo".
  2. Add the "java" custom tag using the ColdFusion Administrator. Specify the classname as "Foo" (case sensitive) in the appropriate field.
  3. Call you custom tag from your template using CFX_Foo instead of CFX_J. You should omit the "CLASS" attribute in the tag.
• In the ColdFusion Administrator a limitation in the Verity implementation may cause problems if you repair a Verity collection and then attempt another action such as a purge before the repair has completed processing. In the event that a problem does occur, you should delete the affected collection, re-create it, and then re-populate the collection with the original content. The safest approach is this: During a repair, NO OTHER ACTION should be taken.
• When creating a Verity collection, make sure the collection directory name contains no spaces.
• Using brackets ([ ]) in the CRITERIA attribute of CFSEARCH causes an error in CFSEARCH. (7183)
• COM/DCOM support for Intel platforms is available only under NT 4.0 or greater, and DCOM enabled Windows 95. An error message with the following text will be displayed when running under platforms that do not support it:

  This OS does not support COM/DCOM. Please verify that you 
  	are running NT 4.0 or DCOM enabled Windows 95. 
  	CoInitialize has not been called

  A patch for Windows 95 can be found at http://www.microsoft.com/msdn. (DCOM for Windows Version 1.1).
  There could still be some problems reported when using objects that do not have a threading model, and potentially have not been made thread-safe. Some of these objects have been generated using older versions of Delphi (3.0), and VB.
  To work around these issues, change the threading model to "Free" by using "OleView", or have the vendor of the object/development tool provide you with an updated conforming object.

• Using an ODBC driver, CFUPDATE does not update datetime fields correctly for SQL Server 6.5 or Sybase System 11. It inputs a time portion of 00:00:00 no matter what time you provide. This does not happen with CFQUERY or CFGRIDUPDATE. (7162)
• Due to a limitation in the Win32 API date formatter, the DateFormat function will not work on dates prior to 1/1/1601. (1056) If you try passing a date earlier than this to the ColdFusion DateFormat function you will get the following error:

  Error Occurred While Processing Request
  	Error Diagnostic Information
  	An error has occurred while processing the expression:
  	DateFormat(date,"mmm dd yyyy") 

• The "LOCALE" attribute can be used to set arguments for the the call to init_orb(..). This is specific to VisiBroker orbs, and has only been tested with the 3.2 C++ version.
  
  The value should be of the form (note that each type-value pair has to start with a leading "-"):
  

  	<CFOBJECT TYPE=CORBA
   	..
  	LOCALE=" -ORBagentAddr 199.99.129.33   -ORBagentPort 19000" 
  	..>
  

Known Issues in this Release: Linux

• The LSParseDateTime() function will only work in the English Locale. [12523]
• When creating a datasource for Sybase on Linux the server attribute has to match the case of the interfaces file or you will not be able to get connected to the server. We're researching the issue at this time.
• The CFOBJECT tag is only supported for Java objects (TYPE=JAVA) in this release.
• Verity is not currently supported on Linux. As a result, the CFINDEX, CFSEARCH, and CFCOLLECTION tags are non-functional. (10678)
• For this release, Red Hat 6.0 or greater is supported. We are working to extend support to other Linux operating systems. If you are not using the Red Hat installed Apache server and instead are using another distribution, you should remove the Red Hat Apache package with the command "rpm -e apache". This will prevent ColdFusion from trying to configure the wrong web server.
• You may need to install the Red Hat package "apache-devel" to get the Apache header files and the "apxs" command needed to rebuild the ColdFusion module if you do not have Apache 1.3.6 installed.

Known Issues in this Release: Solaris

• The CFOBJECT tag is not supported.
• The ODBC drivers have been upgraded to version 3.5, and now reflect the name change from Intersolv to MERANT. Included in this new version of the drivers is support for Microsoft SQLServer.
• The ODBC Microsoft SQLServer MERANT driver only supports version 6.5 of SQLServer at this time.

MERANT also warns that this driver is not threadsafe. Because the driver is running in ColdFusion, a mutli-threaded environment, the driver can only safely support one database connection at a time.

• To continue using the CFX_J custom tag, please navigate to the Custom Tags page, and delete the current entry for CFX_J. Now add a new entry with the same name, and specify the type as "Java". Please leave the "Classname" empty (important).

  You will now be able to use the the CFX_J tag as before.

  Please note that Allaire will phase-out this tag in future releases, and recommends that you simply convert it to a Java Custom tag.

  For example, if you currently use the CFX_J tag that has the CLASS attribute set to "Foo", then to use a Java CFX, you would do the following:

  1. Rename your custom tag to something like "CFX_Foo".
  2. Add the "java" custom tag using the ColdFusion Administrator. Specify the classname as "Foo" (case sensitive) in the appropriate field.
  3. Call you custom tag from your template using CFX_Foo instead of CFX_J. You should omit the "CLASS" attribute in the tag.
• Advanced security is currently unsupported in this release. Do not select Advanced Security during the installation.
• In the ColdFusion Administrator a limitation in the Verity implementation may cause problems if you repair a Verity collection and then attempt another action such as a purge before the repair has completed processing. In the event that a problem does occur, you should delete the affected collection, re-create it, and then re-populate the collection with the original content. The safest approach is this: During a repair, NO OTHER ACTION should be taken.
• When creating a Verity collection, make sure the collection directory name contains no spaces.
• Using brackets ([ ]) in the CRITERIA attribute of CFSEARCH causes an error in CFSEARCH. (7183)
• The precompiled Apache 1.3 module for ColdFusion 4.5 will only work with Apache 1.3.6 or 1.3.9. During the installation, you have the option of using the 'apxs' script shipped with Apache to build and install a module specifically for your installed version of Apache 1.3.
• ClusterCATS requires that the group btcats exist. It will attempt create this group during the ColdFusion installation using groupadd. If you are using NIS or NIS+, please make sure that either nsswitch.conf allows for group resolution from the group file, or that the group btcats gets created in NIS/NIS+ prior to installing ClusterCATS.
• Using an ODBC driver, CFUPDATE does not update datetime fields correctly for SQL Server 6.5 or Sybase System 11. It inputs a time portion of 00:00:00 no matter what time you provide. This does not happen with CFQUERY or CFGRIDUPDATE. (7162)
• Netscape does not certify Enterprise Server 3.0 or FastTrack Server 3.01 to work on Solaris 2.6. These servers are certified by Netscape to work on Solaris 2.5 or 2.5.1. ColdFusion requires Solaris 2.5.1 or higher.

  Netscape Enterprise 3.51 is certified for Solaris 2.6. The NSAPI functions, which didn't work with ColdFusion in earlier releases of Netscape Enterprise server, have been fixed in Enterprise 3.51.

  Allaire has successfully tested Enterprise/FastTrack 2.01 and 3.51 on Solaris 2.6 with ColdFusion.

Changing the way Tokens are generated

Current behavior in ColdFusion is as follows:

• CFID is assigned sequentially per machine. The entire value must consist of all decimal digits (0-9).
• CFTOKEN - by default assigned as a random long integer. The value range is 0 < x < 2,147,483,647. ColdFusion no longer validates any part of this token, allowing users to re-assign this to any value they choose.

However, by setting the registry key HKEY_LOCAL_MACHINE\Software\Allaire\ColdFusion\CurrentVersion\Clients\ UuidToken to be the string value "1", ColdFusion assigns CFTOKENS using the same random number concatenated with a UUID, which is guaranteed to be globally unique.

We use the random number to avoid simple guessing of the uuids, since only a small portion of a uuid changes with each assignment, and to make database lookups more efficient.

A typical CFTOKEN using this method looks like this: 57c6419-f0c43bb2-9e8d-11d3-8b87-00c04fa35ba5

If you turn on the UuidToken switch and you are storing client variable information in a database, you will need to increase the column width of the 'cfid' column in the CDATA and CGLOBAL tables. You should change the current width of 20 characters to at least 50 characters, due to the increased length of CFTOKEN.

You may also have to change other applications if they are storing the CFTOKEN value in a fixed length field.

Migrating a ColdFusion UNIX registry to ColdFusion 4.5

PLEASE NOTE: You only need to use this utility if you want to preserve your registry from a previous version of ColdFusion. If you do not, a simple pkgrm of the previous installation prior to installing 4.5 is all that is required.

The CFREGUP utility package consisting of cfregup.sh and this README file is being provided to migrate the ColdFusion registry (formerly maintained by WindU) to the native format used in ColdFusion Application Server 4.5.

The cfregup.sh script must be run as root on a machine with a running ColdFusion 3.x or 4.x installation. You should run this script prior to doing a pkgrm of the cfusion package.

Run the shell script using the following command:

  ./cfregup.sh

This shell script will locate the existing ColdFusion installation and export the WindU registry from it, creating the new ColdFusion 4.5 registry. Please note that since the new registry is created in a different place than the old one, this script will not damage, or even write to the existing WindU registry. The script will also preserve your start script and your odbc.ini files so they can be upgraded.

Once the script has completed, you are free to do a package remove of the existing ColdFusion installation.

During the installation, ColdFusion 4.5 will access the migrated registry and complete the initialization process so it can be used. It will also restore the saved start script and odbc.ini file, making the necessary changes to them so they are version 4.5 compliant.

All intermediate files are saved into a directory called migration, in the ColdFusion installation directory for reference.

Redirecting processing to a Custom Error Page for specific errors

In certain cases, when the communication between the stub (residing in the webserver process space), and the ColdFusion Application Server is disrupted or broken, the following error page is rendered:

"Server busy or unable to fulfill request. The server is unable to 
fulfill your request due to extremely high traffic or an unexpected 
internal error. Please attempt your request again (if you are repeatedly 
unsuccessful you should notify the site administrator)."

In ColdFusion Server 4.5, processing can be redirected to a user-specified location when this error condition occurs in the stub program. Please edit the cfremote.ini file located in your <ColdFusion Installation Directory>, and add a key/value pair specifying the error condition and the redirection location. In this release only the ERROR_PIPE key is supported.

The follwing is an example where the error processing is redirected to nopipe.htm

ERROR_PIPE = "http://127.0.0.1/ErrorPages/nopipe.htm"

NOTE: Please note the ColdFusion Administrator cannot be used to specify these settings. Furthermore every attempt should be made not to change the other settings in this file. Please see Advanced CF documentation for details about the use of the other settings in this file.

Load Balancing and Failover with ClusterCATS

ClusterCATS consists of two components, the ClusterCATS Server and the ClusterCATS Explorer. ClusterCATS Server provides fail-over support, load balancing, and other features to help you guarantee the availability of your ColdFusion applications.

For more information about configuring Web server clusters, refer to Administering ColdFusion Server.

• When creating a cluster using ClusterCats for ColdFusion, enter the license key "GoColdFusion"
• ClusterCats for ColdFusion, which provides load balancing support for clustered servers, is not supported on Windows NT 3.51.
• ClusterCATS is now integrated into the ColdFusion Server Linux installation.

Configuring ClusterCATS on Windows NT:

• Windows NT Service Pack 4 must be installed on each member.
• The Streams Environment must be added to Network Protocols.
  1. Right mouse on the network neighborhood
  2. Select Properties
  3. Select Protocols
  4. Click Add
  5. Select Streams Environment, and click OK

ClusterCATS and secure Web servers

Secure Web Servers, such as the Netscape Enterprise Server in secure mode, and secure Apache servers, require a keyfile password to be started. The Allaire ClusterCATS installation script will not restart the Netscape Enterprise Server or Apache server during installation, if the web server is running with security enabled. You may start the web server after the installation using your preferred method. The ClusterCATS web server monitor will not be able to restart a web server with keyfile passwords on startup.

Support for multiple web servers on a single platform

ClusterCATS does not support being configured to run with different types of web servers on the same system. For example, if an NT system is configured to run both the Netscape Enterprise Server and IIS, you can choose to configure ClusterCATS with only one of these web servers.

ClusterCATS Cluster Members must have a unique IP address

ClusterCATS Cluster members must have unique IP address. The name used to cluster a web server, or virtual server must not be either Round Robin or the name of a software virtual server. It should be the name that maps to the IP address of the web server that is being clustered.

Virtual Host Headers on IIS and Software Virtual Servers on Apache are not Supported

Virtual Host Headers on IIS and Software Virtual Servers on Apache allow you to run many Web sites on a single computer. In technical terms, this allows you to support multiple host names with a single IP address. ClusterCATS currently requires a different IP addresses for each virtual server.

Minimum version of Cisco Local Director Software required is 3.1.4

Prior to enabling ClusterCATS Load Balancing with Cisco Local Director, the Local Director software version must be at version 3.1.4 or greater.

Configuring ClusterCats IP Failover With Cisco Local Director

When a Cisco Local Director is being used for load balancing and failover do not configure ClusterCats to perform IP Failover (IP Aliasing). If ClusterCats does IP aliasing, the Cisco Local Director will not be able to reconnect to the system after it has become available again and recovered the failed-over IP address.

Configuring Cisco Local Director Update Frequency

Set the Cisco Local Director load balancing update frequency to a value between 5 and 30 seconds. Set a longer time as greater numbers of web servers become configured in clusters doing Cisco Local Director load balancing so as to not create too much overhead traffic to the Local Director. The dyamic-feedback timeout value should be set to a value larger then the update frequency. We recommend you set the value to at least two times the update frequency.

Configuring ClusterCats DFP Agent Listen Port with Cisco Local Director

If two or more web servers on the same system are in clusters using Cisco Local Director load balancing, than each cluster must have the same DFP Agent Listen Port number configured. The Clustercats DFP Agent can only listen on one port.

Configuring the Cisco Local Director dynamic-feedback retry value

The dynamic-feedback retry value should be set to zero (0) to insure that the Cisco Local Director will continue connection attempts to the ClusterCats DFP Agent in the event of a lengthy period of system unavailability.

Cisco Local Director dynamic-feedback security not supported

Do not enable the dynamic-feedback-pw. Clustercats does not support secure DFP host.

Gradual redirection load management and Session State Management

When session aware load management is enabled (the default) then gradual redirection load management does not apply. You can still set a gradual redirection load threshold value, but it will have no effect when session aware load management is enabled.

Configuring a ColdFusion Application Probe

The ColdFusion Application Probe dialog box creates a default probe for that web server to determine if ColdFusion Server is functioning. The default action is set to NORESTART, this will not restart the ColdFusion server if the probe fails, the web server will however be automatically set to the restricted state. See the online help available from the ColdFusion Application Probe dialog box for more information.

Configuring ClusterCATS Explorer Web Addition with Apache

For security reasons we recommend that if you wish to run the Web Addition of the ClusterCATS Explorer you create a separate instance of the Apache server to do so. We also recommend that you password protect access to this server. Below are the configuration changes required to configure the btweb for Apache.

Make the following additions to httpd.conf to get btweb working and to require user/password authentication:

# - make btweb a virtual doc root directory 
Alias /btweb/ "/usr/lib/btcats/btweb/"
# - allow execute in btweb directory and protect it with authentication
<Directory "/usr/lib/btcats/btweb/">
Options ExecCGI 
AllowOverride None
Order allow,deny
Allow from all
AuthName "btcats admin tools"
AuthType Basic
AuthUserFile /usr/local/apache/conf/users
require user admin
</Directory>
# -added .exe file type so that btcluadm.exe will work
AddHandler cgi-script .cgi .exe

You use the Apache 'htpasswd' utility to create/manage the Authentication list file: (create file and add user 'admin')

htpasswd –c /usr/local/apache/conf/users admin

Improving Responsiveness When Integrating with Cisco Local Director

By default the frequency at which the ColdFusion load and availability information is sent to Cisco Local Director is every 30 seconds. Users may set Update Frequency to a lower value for better response to change in the server load condition. To update the load frequency refer to ColdFusion documentation.

ColdFusion Application Probe and Application.cfm files

If other than the default URL to query (http://<myserver>/btauxdir/cfprobe.cfm) is used, than you must insure that no Application.cfm files are in the path of the ColdFusion page to be tested.

Configuring ClusterCATS on UNIX platforms:

ClusterCATS requires that the group btcats exist. It will attempt create this group during the ColdFusion installation using groupadd. If you are using NIS or NIS+, please make sure that either nsswitch.conf allows for group resolution from the group file, or that the group btcats gets created in NIS/NIS+ prior to installing ClusterCATS.

UNIX support

In order to run the ClusterCATS the management command, btadmin, on Red Hat the ksh shell must be installed.

Adding appmgr to inittab

It may be desirable to add appmgr to your inittab file, to ensure it always running.

Apache Web server

ClusterCATS and Apache Web Servers

Cluster members can appear to be available when the associated web server managing is actually down. In such cases the ClusterCATS server will display a load of 100%. Also, if the ColdFusion probe is enabled, the server will also be restricted.

Apache Loadable's Support

ClusterCats and ColdFusion Apache support requires that mod_so.c module be compiled into Apache (httpd or httpsd). You can verify this with the -l option to httpd (or httpsd): For example:

# /usr/local/apache/bin/httpd -l
Compiled-in modules:
  http_core.c
  mod_so.c

Windows NT support

Multiple instances support and Windows NT

Only a single Netscape Enterprise Server instance per system can be configured run with Allaire ClusterCATS on NT.

ClusterCATS virtual directory btauxdir is not always being created on system running IIS

ClusterCATS requires that the virtual directory btauxdir exists, under each virtual server which will be clustered and that it points to the <install-directory>/brighttiger/btauxdir. ClusterCATS will attempt to create the directory when a cluster member is added. If there is no IP address bound to the site, ClusterCATS will be unable to add the virtual directory to the web. Use the MMC to add the specific IP address to the web site, then stop and restart the ClusterCATS Service. The btauxdir virtual directory should get created automatically.

Known problems

Adding or Creating a Cluster under heavy load

When creating a cluster or adding a web server to a cluster with the ClusterCats Explorer and that web server is under heavy load you may get a popup message indicating that the "session aware bit could not be set". The ClusterCats Explorer will display the web server with the 'unreachable or unknown' icon. In this case, click OK to dismiss the popup message, hide the cluster ('Hide Cluster' in the View menu), then show the cluster again ('Show Cluster' in the View menu).

Netscape Enterprise Administrator Server

After installing Allaire ClusterCATS, you will see a warning from the Netscape Administrative Server the next time you attempt to manage your Server via the Netscape Administrator. The warning will inform you that the Netscape configuration files have been modified by "hand". Once you've clicked OK to accept this warning, you must choose to Apply the manual updates. If you do not apply the manual updates, Allaire ClusterCATS may be removed from the Netscape plugin list. If this should happen, re-install Allaire ClusterCATS.

Failover problems when routers are not configured to timeout their ARP cache

When ClusterCATS appears to be ARPing correctly but there are persistent connectivity problems after Failover as occurred, there may be problem with one of the adjacent router's ARP cache timeout settings. If the ARP cache timeout is off then set it to some value, which is not too large, such as 2-30 seconds. Accessing the router configuration settings will be vendor specific; please refer to associated h/w and s/w documentation for router box.

ClusterCATS IP Failover subsystem for NT IIS creates and removes the "Aliased IP addresses" Web Site

The ClusterCATS IP failover subsystem creates an IIS Web Site named "Aliased IP addresses" when at least one IP address is 'aliased' on the local system. This Web Site is removed when the local system is no longer 'aliasing' any IP addresses. This Web Site must not be managed with the Microsoft Management Console (MMC). If this Web Site is selected or has its properties enumerated after the IP failover subsystem has deleted it, but while the MMC still has it displayed, various MMC error messages will be displayed. An MMC refresh operation can be performed to update the list of Web Sites and eliminate the stale view of the IP failover Web Site.

Uninstall Netscape NT (ONLY)

Uninstall may encounter difficulties removing the ClusterCATS entries from the obj.conf file. It will inform you that you must remove these entries by hand. To remove these entries, edit your Netscape Enterprise Server obj.conf file and remove the following files from your obj.conf file:

Init fn=load-modules shlib="<install-dir>/program/teserver_nes.dll" funcs="btcats_server_init,btcats_nsapi_AuthTrans,btcats_nsapi_NameTrans,btcats_ErrorFixup" 
Init fnInit fn="btcats_server_init"

NameTrans fn=btcats_nsapi_NameTrans

AuthTrans fn=btcats_nsapi_AuthTrans

Error fn=btcats_ErrorFixup reason="BrightTiger"

You will need to recycle you Netscape Enterprise Server for these Changes to take effect.

Multiple ClusterCATS Explorers viewing the same SmartClusters

Multiple ClusterCATS Explorers viewing one or more clusters simultaneously do not correctly handle displaying cluster deletions. Only the ClusterCATS Explorer where the delete requests were performed will see that the cluster has been deleted (cluster is removed from view). All other ClusterCATS Explorers will show the last cluster member as unreachable. To work around this problem, hide the deleted cluster from view.

Configuring the Apache Web Server

For information on Linux and Solaris, see Configuring Apache on Linux and Configuring Apache on Solaris.

Apache 1.3.6 and 1.3.9 are supported with the current module on all platforms. The current ColdFusion Apache 1.3.6 module will work without change with Apache 1.3.9.

Configuring Apache on Windows NT

The ColdFusion Module can be found in the installation directory (usually c:\cfusion\bin).

We assume below that your Apache installation is found in c:\Apache .

1. Copy the module (ApacheModuleColdFusion.dll) to your modules directory under the Apache source directory.

   ex. c:\Apache\modules\ApacheModuleColdFusion.dll

2. Edit the "httpd.conf" configuration file to contain the following line, this can be found in c:\Apache\conf:
   

   LoadModule coldfusion_module modules/ApacheModuleColdFusion.dll

Configuring Apache on Linux

For detailed instructions on installing and configuring Apache Web Server on Linux, refer to the /opt/coldfusion/webserver/apache/README file installed with ColdFusion.

Other issues:

• The precompiled Apache 1.3 module for ColdFusion 4.5 will only work with Apache 1.3.6 and 1.3.9. During the installation, you have the option of using the 'apxs' script shipped with Apache to build and install a module specifically for your installed version of Apache 1.3.
• In order to rebuild the ColdFusion Apache module, you will need to install the Red Hat 'apache-devel' package to get the header files and the 'apxs' script needed to build modules.

Configuring Apache on Solaris

For detailed instructions on installing and configuring Apache Web Server on Solaris, refer to the /opt/coldfusion/webserver/apache/README file installed with ColdFusion.

The ColdFusion Server installation process can optionally autoconfigure the Apache web server for you.

Running Allaire Forums under ColdFusion 4.5

If you are running Allaire Forums with ColdFusion Server 4.5 you should be running with Allaire Forums 2.0.5. You should download Allaire Forums 2.0.5 from our product page if you are running an earlier version.

Allaire Forums is not supported on Linux.

Back to top