ColdFusion Server 4.5.1
Release Notes -- Updated March 23, 2000

Contents

• System Requirements
• Before installing ColdFusion on Linux
• Issues fixed in ColdFusion 4.5.1
• Upgrading to ColdFusion 4.5.1
• Known issues: All platforms
• Known issues: Windows NT
• Known issues: Linux
• Known issues: Solaris
• Configuring MySQL data sources on ColdFusion Server for Linux
• Configuring PostgreSQL data sources on ColdFusion Server for Linux
• Changing the way Tokens are generated
• Migrating a ColdFusion Solaris registry to ColdFusion 4.5.1
• 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.1. As in ColdFusion 4.5, this release is comprised of a 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 configuration. On this page, you'll also find details about known problems or behaviors in this release.

This release builds upon the many new features and enhancements that made ColdFusion 4.5 a significant upgrade. For information about new features and enhancements, see the New Features page.

ColdFusion Server System Requirements

ColdFusion Server 4.5.1 Enterprise Edition for Windows

System

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

Windows 2000 issues:

• You may have to add your LDAP server to the hosts file on the Windows 2000 server that hosts the CF Application Server.

Web servers

• Microsoft Internet Information Server (IIS) 4.0
• Netscape Enterprise Server (NSAPI) 3.51, 3.6, and V4.0 (iPlanet)
• All Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12)
• WebSite Server API (WSAPI)
• Common Gateway Interface (CGI)

NOTE: ClusterCATS is supported on IIS, Netscape Enterprise Server, and Apache Web Server.

ColdFusion Server 4.5.1 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, 3.6 and V4.0 (iPlanet)
• All Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12)
• Microsoft Personal Web Server (PWS)
• WebSite Server API (WSAPI)
• Common Gateway Interface (CGI)

ColdFusion Server 4.5.1 Enterprise Edition for Linux

System

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

Web servers

• All Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12)
• Netscape/iPlanet Enterprise Web server 4.1

ColdFusion Server 4.5.1 Professional Edition for Linux

System

• Red Hat Linux 6.0 or greater, on Intel processors only
• 64 MB RAM (128 MB recommended)
• 70 MB hard disk space

Web servers

• All Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12)
• Netscape/iPlanet Enterprise Web server 4.1

ColdFusion Server 4.5.1 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 higher
• All Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12)

NOTE: Load balancing and failover support is available only on Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12) and Netscape Web servers.

Before installing ColdFusion on Linux

Before installing ColdFusion on Linux, 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 failover 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".

Issues fixed in ColdFusion 4.5.1

Following are behaviors in ColdFusion that have been fixed or enhanced in ColdFusion 4.5.1 since the release of ColdFusion 4.5:

Administration

• On Windows NT (SP5), the following problem using CFCACHE has been fixed: When using CFCACHE
  and only basic authentication is enabled in IIS, you are unable to access any cached pages, and an "Access Denied" error is generated. Two new attributes have been added to CFCACHE. They are USERNAME and PASSWORD. [14910]
• When you go to the Debugging page in the ColdFusion Administrator and check Show SQL and data source name, and uncheck Show query information, database errors do not display the SQL statement. This behavior has been fixed in this release. [14531]
• On UNIX platforms, group permissions for the ColdFusion processes are now set correctly.
• On Linux, the ColdFusion user is now set correctly during installation.
• On Linux, the cfremove script now removes the ColdFusion system startup files in /etc/rc.d.
• An enhancement has been added to the Sybase native driver which allows user-defined errors to be trapped. To activate this feature, check the Enable RAISERROR checkbox in the Sybase native driver page of the Administrator. [13485]
• When using OLEDB data sources in a stored procedure, a C++ runtime error was thrown. This behaviro has been fixed in this release. [14939]
• NT Challenge/Response authentication requests no longer generate a log message. (Formerly a message was generated in the application.log.) [15082]
• NT Windows 2000 Only: In the NT Performance Monitor, one of ColdFusion's counters, "Cache Pops /Sec", may not display correctly and a junk counter displayed with the name "3610", may appear instead. Aside from the fact that Cache Pops counter is missing, all other aspects of ColdFusion in the Performance Monitor work normally. [15124]
• In order to run smconsole, type ./smconsole from the shell. example: /opt/coldfusion/siteminder/bin)-->./smconsole The same applies for smtest and smdstest [14969]
• On Solaris, you can use the smexec utility to execute any SiteMinder utility, except smconsole, smdstest, and smtest, which already have wrapper scripts around them to simplify their execution. To run smobjexport for example you should type smexec smobjexport with the appropriate arguments. You must be root in order for this to work. [15513]
• Advanced Security note: Coldfusion supports Netscape LDAP Server version 3.x and 4.11. [15714]
• In version 4.5, the "request timeout" condition became a catchable error (catchable by <CFCATCH TYPE=""COM.Allaire.ColdFusion.Request.Timeout""> or by <CFCATCH TYPE="ANY">). In Version 4.5.1, the request timeout exception subsystem has undergone reliability enhancements. Because of this, the "Date/Time," "Browser" and "Remote Address" diagnostic displays will be shown on the default request timeout browser screen. [15983]

Database

• The underlying DB2 client libraries only allow 1 connection to be open at a time, so mixing ODBC and native connections to DB2 could be problematic. It works if you establish the ODBC connection first, and then use the native drivers, or if you exclusively use ODBC or native only. [13587]
• A bug in the ODBC.INI file on Solaris caused the ExtensionsList for a text datasource to always default to txt,TXT. This has been fixed. [11989]

Clustering and load balancing

• There are now new load balancing options that can improve the utilization of Web servers clustered with Allaire ClusterCATS software. For detailed information, see Load Balancing and Failover with ClusterCATS.

Tags

• When using a CFFORM tag, the subsequent SCRIPT tag that ColdFusion generated was missing the type="text/javascript" attribute. This behavior has been fixed in this release. [13822]
• CFHTTP did not render XML properly. This behavior has been fixed in this release. [14372]
• When you used the CFHTTP RESOLVEURL attribute, it appended link information to mailto links. This behavior has been fixed in this release. [11421]
• CFEXECUTE was not protected by basic security. After disabling CFEXECUTE with the administrator, CFEXECUTE still worked. This behavior has been fixed in this release.
• Because Verity is not available for Linux, the CFSEARCH tag was not implemented. When you used the CFSEARCH tag (or other unimplemented tags) within a CFTRY CFCATCH TYPE="any" block, the ColdFusion server crashed. This behavior has been fixed in this release. [14620]
• The whitespace suppression algorithm sometimes incorrectly emitted a space at the beginning of a tag such as CFIF, instead of at the end. This behavior has been fixed in this release. [14567]
• On Solaris, using the ListDir action of the CFFTP tag no longer generates an error. [14521]
• On NT, NT Challenge/Response authentication requests no longer generate a log message. (Formerly a message was generated in the application.log.)"
• In the CFEXECUTE tag, using the OUTPUTFILE option did not result in output being redirected to a file. This behavior has been fixed in this release. [13288]
• The CFLDAP tag has a new attribute, DELIMITER, which allows you to specificy an alternate separator character for use between multiple name/value pairs in the ATTRIBUTE attribute list. [14520]
• When using CFPOP, reading a blank email with an attachment resulted in behavior such as the attachment not getting written to the destination directory, and background image of the email appearing only as an attachment. This behavior has been fixed in this release [15052]
• On UNIX, you can now delete a Verity collection and recreate it using the same name. [15213]

Functions

• In ColdFusion 4.5 as opposed to CF 4.0.1, more extensive range-checking is performed to determine whether an argument is an integer. This may lead to situations where code which executes correctly on CF 4.0.1 results in an error in CF 4.5. For example, the maximum value for the 1st argument in FormatBaseN function is 2147483647 on some Windows NT machines. [13549]
• The NumberFormat function was overwriting the last digit of a negative number displayed in parenthesis with the right paren. This has been fixed. [14534]
• The NumberFormat function was ignoring a trailing mandatory decimal point if it had no decimal places following it. This caused the commas to be ignored as well. This behavior has been fixed in this release. [14527]
• NumberFormat() was displaying a 0 value as empty. This has been fixed to display a 0. [15058]
• In some beta releases of 4.5.1, the DollarFormat function accepted an optional second parameter, which was a formatting mask. This optional parameter has been removed from the final build of the product, as it sometimes crashed the ColdFusion Application Server. [14903]

Verity

• Verity Indexing operations (such as CFINDEX) were broken on UNIX. [13505]
• On Unix, A problem with the Verity registry updating is fixed. You are now able to delete a Verity collection and recreate it using the same name. [15213]

Email

• If you checked for a recordcount of zero in an empty email box, zero was not returned. This behavior has been fixed in this release. [14563]
• When you attempted to send an email that was undeliverable with the CFMAIL tag, empty email messages were created. This behavior has been fixed in this release. [14580]

CORBA

• On NT and HP-UX, CORBA support now uses the VisiBroker 3.3/C++ libraries for the orb and naming service.
• On Solaris, ColdFusion uses VisiBroker 4.0/C++ libraries for the orb and naming service. Please note that the interface repostiories created by the VisiBroker 4.0 and previous versions are incompatible. There is currently a bug in the VisiBroker libraries that prevents objects (TypeCode : tk_objref) to be passed in/out or returned as arguments on method or attribute calls. ColdFusion will report an unhandled or TypeMismatch exception if an attempt is made to call such a method.

Other

• An extra character in the HTTP header returned by CF can upset some browsers, most notably on Macintosh computers. This problem was introduced in CF 4.5 but has been fixed in 4.5.1. [14533]
• Debugging ColdFusion templates on Unix using ColdFusion Studio now works correctly. [13507]

Upgrading to ColdFusion 4.5.1

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

Whitespace handling

• ColdFusion Server version 4.5.1 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.

Error handling

• 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."
• CFCATCH selection logic in ColdFusion 4.5.1 differs slightly from ColdFusion 4.0.x In ColdFusion 4.0.x, 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.x will select the TEMPLATE block to handle a MISSINGINCLUDE exception, while ColdFusion 4.5.1 will select the MISSINGINCLUDE block. ColdFusion 4.5.1 can be reset to handle a template using ColdFusion 4.0.x rules by setting the compatibility setting, <cfsetting catchexceptionsbypattern=no>

ColumnList function

• 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.

CFHTTP tag

• CFHTTP -- If a Mime Type (or content type) is not returned when requesting a page via CFHTTP you will receive the following error message: The requested file is not ASCII text and can not be rendered. ColdFusion 4.0.1 ignored the content type and displayed the page. [14372].

cfcrypt utility

• The cfcrypt utility has been renamed cfencode.

Changes to Administrator

• 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.

Clustering

• Allaire does not recommend running a mixed-version cluster. All cluster members should be upgraded to the same version of ColdFusion.
• Cluster members on Solaris and Netscape Web servers must be deleted prior to upgrading to ColdFusion Server 4.5.1. The cluster members should be recreated once ColdFusion Server 4.5.1 has been applied.
• Session-aware load balancing is enabled by default in ColdFusion Server 4.5.1.
• Cluster members join a cluster in active mode by default.

Known Issues: All platforms

General

• In ColdFusion Server 4.5, the "request timeout" condition became a catchable error (catchable by <CFCATCH TYPE="COM.ALLAIRE.COLDFUSION.REQUESTIMEOUT"> or by <CFCATCH TYPE="ANY">). In ColdFusion 4.5.1, the request timeout exception subsystem has undergone reliability enhancements. Because of this, the "Date/Time," "Browser" and "Remote Address" diagnostic displays will be shown on the default request timeout browser screen.
• When invalid XML is encountered during WDDX packet serialization or deserialization an unknown exception condition may be generated. This will be addressed in a future release. [15773]
• Only one instance of ColdFusion can be run on any given system at a time.
• Since the ColdFusion Application Server uses 32-bit signed integers to represent "integer" numeric values, integers can only take on values in the range -2147483648 to 2147483647. When a numeric quantity exceeds these limits, it will be stored in floating-point representation, but it cannot then be used as input to functions, such as RandRange(), that require integral parameters.
• Although Allaire recommends that you specify the scope of your variables, if you should not do so when assigning structure fields. For example the following code will fail:
  <cfscript> st1=structnew(); variables.st1.key="foo",</cfscript>
• Storing client variables in the registry is not recommended by Allaire. You should store client variables in a database or in cookies. On UNIX systems in particular, the registry is implemented as a flat text file (to make editing easier) and reading and writing this file is slow. Even a small number of clients (less than 100) stored in the registry will significantly impact performance of the cfserver process.
• CFHTTP -- If a Mime Type (or content type) is not returned when requesting a page via CFHTTP you will receive the following error message: The requested file is not ASCII text and can not be rendered. ColdFusion 4.01 ignored the content type and displayed the page. [14372]

Security

• If you are hosting ColdFusion sites created from untrusted developers, a rogue developer may be able to capture Web server passwords. The information is passed in the CGI.HTTP_AUTHORIZATION variable and is decipherable by a well-known algorithm. This situation can be a security problem if you use basic Web server authentication, you host multiple Web sites, and there are untrusted developers.
• To prevent all browser clients from being able to view debug information by passing the MODE=DEBUG query parameter (for example, http://www.allaire.com/xxx.cfm?mode=debug), add the IP address 127.0.0.1 to the Restrict debug output to selected IP addresses list on the Debugging page of the ColdFusion Administrator. You should also include any additional IP addresses for which you wish to view debugging information. [13983]
• The SiteMinder service in the ColdFusion Advanced Security feature requires an IP address to work properly. If you are not on a network, you may see errors in the Advanced Security feature, such as "Security Policy Action Failed" messages. See Knowledge Base article #14378 for a workaround. [14665]
• If the ColdFusion Advanced Security feature is configured to use a database, and the database server is restarted, or the connection to it is lost, you need to restart the Advanced Security (SiteMinder) and ColdFusion services. If you do not restart these services, ColdFusion will use cached security settings until the timeout has expired, and then attempt to refresh the cache. This will result in silent security errors until the Advanced Security services and ColdFusion have been stopped, then restarted. Note that you should restart the Advanced Security services first, and then stop and start the ColdFusion services.

Data sources

• You should not use the data source name "Registry" 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.
• In order to insert or update CLOBs where the text length is greater than 4K with CF 4.5.1 while going against an Oracle database, you must use the Merant Oracle 8 ODBC driver version 3.6, available from Merant Merant. The Merant driver is shipped with ColdFusion for Linux and Solaris but not for Windows NT.

Searching

• 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]

Tags

• 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 include a CFHEADER and a CFLOCATION in the same template and run the template, you will get "Document contains no data" even though the URL in the CFLOCATION, when run by itself, results in page output. [2356]
• The CFSERVLET tag does not currently return the HTTP response headers set by the servlet. The tag is documented as returning any response headers set in the servlet code back to ColdFusion using appropriately named fields of the CFSERVLET response variable. This mechanism currently does not work and response headers set in the server are not visible in ColdFusion.

  A workaround is to use ColdFusion variables as CFSERVLETPARAMs to explicitly return any response variables you care about. Note the OUTPUT field of the CFSERVLET response variable does work correctly and is not affected by this problem.

• In order to use the CFSERVLET tag in ColdFusion, you need to make sure you have a compatible version of JRun. JRun 3.0 Beta 5 does not yet support CFSERLET. JRun upgrades are available free on the Allaire beta site. [14379]
• 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.
• On Windows 95 only, when using the CFHTTP tag, if you encounter the error "unknown error while executing a tag," you probably need to update your winsock installation. To do so, go to the Microsoft site.
• CFLOCK: If you specify a lock with the NAME attribute of the CFLOCK tag, then you should not select full-checking on the Lock page of the ColdFusion Administrator for the variable's scope.
  • If the lock is in the application scope, do not specify full checking for the application scope.
  • If the lock is in the session scope, do not specify full checking for the session scope.
  • If the lock is in the server scope, do not specify full checking for the server scope.

  If you specify the SCOPE attribute instead of the NAME attribute within each CFLOCK tag in the application, you can apply full lock checking from the ColdFusion Administrator.

Functions

• 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].
• You should avoid using CFSCRIPT keywords as variables in your code. The Evaluate function will handle some of them currently, but this behavior may be changed in a future release.
• 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 is attributable to the underlying API functions on which these ColdFusion functions are based. 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 _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 encrypt function gives different output than it did in 4.0.x version. [10446]

Known Issues: Windows NT

Installation

• If you uninstall ColdFusion 4.5 or 4.5.1, ClusterCATS Explorer and ClusterCATS Server Admin remain in the program group for ColdFusion 4.5. and 4.5.1 respectively. [13960]

Security

• NT Challenge/Response authentication requests no longer generate a log message. (Formerly a message was generated in the application.log.)
• Allaire recommends backing up your policy store data before installing ColdFusion - Advanced Security. The method to do this is use the smobjexport tool. The command is "smobjexport -o<FILENAME>" An example would be smobjexport -oFOO.DAT. In the event that something went wrong you could use this file to restore your policy store. NT users should find the executable in the cfusion\bin folder.

  NOTE: The following applies to both NT and Solaris users and is to be done ONLY if you are migrating an old policy store to a policy store that has been newly initialized with CF4.5.1 (both Solaris and NT).

  Do the following 3 steps on the LDAP server you initialized the SM policy store on during installation:

  1. Create an attribute called smDomainAdminOIDs of type StringNoCase. (Leave the OID column blank)
  2. Edit the objectclass smdomain and add smDomainAdminOIDs as an allowed attribute.
  3. Save and restart

  This will allow you to use your previously defined policy store data. [15512]

Data sources

• Allaire recommends that you install the latest version of Microsoft Data Access Components (version 2.1 SP2), available from Microsoft, to avoid problems such as memory leaks with any of the MS Desktop ODBC drivers or the MS SQL Server. [15047]
• If you install ColdFusion 4.5.1 after installing MDAC, none of the existing OLE DB data sources will verify. You should register the oledb32.dll located in Program Files\Common Files\System\ole db\
• When using MS Access, if the data source value is capitalized in the ColdFusion Administrator settings, but not in the CFQUERY tag, there is a lag time of approximately 50 milliseconds. As a result, if you use CFLOCATION to go to another template that should contain updated data, the changes may not appear in the second template. To avoid this problem, make sure to match case exactly in the Administrator and CFQUERY tags. [14769]
• Using the sqloledb ole db provider you cannot update columns of datatype int, small int, or tiny int. The workaround for this is to use msdasql or ODBC. This is a provider limitation based on our tests.

Java

• Java support 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, 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". 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.

Tags

• 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]
• 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]
• When using CFGRIDUPDATE with the Sybase native driver, you can only delete one row. If you try to delete more than one row, a Sybase DB error will occur.
• CFINSERT and CFUPDATE fail for datetime fields when you use the IBM DB2 ODBC driver. To avoid this behavior, either use the DB2 native driver, or, if you must use the IBM DB2 ODBC driver, use the CFQUERY tag to update the row.

COM and CORBA

• 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.
• ColdFusion 4.5.1 now supports calling property put methods that have arguments. For example to set the following property: [id(200), propput] HRESULT Value([in] BSTR x, [in] VARIANT y); use the following CFM syntax: <cfset foo.Value("name", "bubu")>
• 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.

• The "LOCALE" attribute can be used to set arguments for 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" 
  		..>
  		

Functions

• 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") 

Load-balancing and clustering

• Windows 2000 systems must be configured to use ClusterCATS dynamic IP addresses for Failover (High Availability installation option) to function properly. Static addresses are currently not supported on Windows 2000 systems.

Known Issues: Linux

Installation

• In rare situations, during an install on Linux, the installation fails because the server or the stub cannot bind to the socket. When this occurs, the following error message appears in the webserver.log:
  
  "Error","TID=2051","02/27/00","12:11:06","Error attempting to bind to socket for ColdFusion server."
  
  This situation usually occurs when ColdFusion is being reinstalled as a different user. To fix this problem, delete the socket (/tmp/cfserver and /tmp/cfrds) from /tmp prior to beginning the reinstallation.

Java

• You may need to be running Red Hat 6.1 in order for the JVM to function correctly. Check the system requirements of the JVM.
• In order to get Java capability (currently JDK 1.2.2) through ColdFusion for Linux using the CFOBJECT tag type=JAVA, the following components must be installed: [15538]
  • jdk1.2.2
  • libc-2.1.1.so
  • linux kernel v 2.2.12
• On the Java page of the ColdFusion Administrator, set the following:
  • Java Virtual Machine Path: for example, /usr/jdk1.2.2/jre/lib/i386/classic/libjvm.so
  • Class Path: where the Java class files reside
  • Initial Heap size: 4096K is recommended
  • Max Heap Size: 16384K
  • System Options: java.compiler=NONE
  • CFX Jar Path: /opt/coldfusion/Java/classes
• In the ColdFusion start script, edit the LD_LIBRARY_PATH to add pointers to the JDK, for example:
  LD_LIBRARY_PATH=$CFHOME/lib:/usr/jdk1.2.2/jre/lib/i386/classic:/usr/jdk1.2.2/jre/lib:/usr/jdk1.2.2/jre/lib/i386/native_threads:/usr/jdk1.2.2/jre/lib/i386
• The CFOBJECT tag is only supported for Java objects (TYPE=JAVA) in this release.
• When calling Java objects using the CFOBJECT tag, or when using Java CFXs under Linux, a segmentation violation may be reported on the first call. Depending on the JDK/JRE being used (Sun or Blackdown), it may be necessary to add the flags:
  

  		java.Compiler=NONE
  		

  in the System option field on the Java page of the ColdFusion Administrator. This indicates to the JVM that JIT is disabled. You should also refer to the documentation available with the JRE/JDK regarding the use of the appropriate threading library (native/green_threads).

Data sources

• When configuring the Informix native Database driver on Linux, there are two additional fields in the administrator template that need to be set: Driver and Translation DLL. Both are the full path to their respective shared object files.
  Driver: INFORMIXDIR/lib/cli/iclit09b.so
  TranslationDLL: INFORMIXDIR/lib/esql/igo4a304.so
  where INFORMIXDIR is what you set it to in the start script.
• When creating a data source 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.
• The Sybase Client Libraries currently available are not thread-safe.Therefore, you must limit the number of simultaneous connections to 1.
• The ODBC Microsoft SQLServer MERANT driver supports versions 6.5 and 7.0 of MS SQLServer and is threadsafe. However, because it cannot maintain connections, you should turn off the "maintain connections" switch in ColdFusion.

Tags

You cannot use SSL with the CFLDAP tag on Liniux. SSL is supported on all other platforms. [13350]

Functions

• The LSParseDateTime() function will only work in the English Locale. [12523]
• English is the only language supported by Verity in ColdFusion for Linux. [15768]

Known Issues: Solaris

Installation and system requirements

• You cannot install ColdFusion 4.5.1 directly over an existing installation of ColdFusion 3.1 or 4.0. You must first migrate the registry using the cfregup.sh utility, and then execute a package remove of the cfusion package before installing 4.5.1. For more detailed information on the migration procedure, consult the README file that accompanies this release. In addition, refer to the section Migrating a ColdFusion Solaris registry to ColdFusion 4.5.1 , below.
• 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+, 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.
• ColdFusion will not work with Netscape 3.0 on Solaris 2.6. you must use Netscape 3.5.1 or higher.
• If you encounter the error "There is already an instance of the package and you cannot install due to administration rules" while installing ColdFusion, edit the file /var/sadm/install/admin/default. Change "instance=unique" to "instance=overwrite" then install ColdFusion. [15190]
• In rare situations, during an install on Solaris, the installation fails because the server or the stub cannot bind to the socket. When this occurs, the following error message appears in the webserver.log:
  
  "Error","TID=2051","02/27/00","12:11:06","Error attempting to bind to socket for ColdFusion server."
  
  This situation usually occurs when ColdFusion is being reinstalled as a different user. To fix this problem, delete the socket (/tmp/cfserver and /tmp/cfrds) from /tmp prior to beginning the reinstallation.
• Using the store example application with Netscape may cause the browser to crash.

Security

• ColdFusion supports Netscape LDAP Server version 3.x and 4.11. Using Netscape LDAP Server version 4.1 may result in unexpected results.
• In order to run smconsole, type ./smconsole from the shell. For example:
  /opt/coldfusion/siteminder/bin)-->./smconsole
  In order to run smtest, type ./smtest from the shell. To run smdstest, type ./smdstest from the shell.
• The smexec utility allows you to execute any SiteMinder utility, except smconsole, smdstest, and smtest, which already have wrapper scripts around them to simplify their execution. For example, to run smobjexport, type:
  ./smexec ./smobjexport
  with the appropriate arguments.
  NOTE: You must be root in order for this to work.
• In order to ensure the security of your Policy Store, use the Shared Secret option that appears on the Advanced Security page of the ColdFusion Administrator.
• Allaire recommends backing up your policy store data before installing ColdFusion - Advanced Security. The method to do this is use the smobjexport tool. The command is "smobjexport -o<FILENAME>" An example would be smobjexport -oFOO.DAT. In the event that something went wrong you could use this file to restore your policy store.

  On Solaris, the command is: ./smexec ./smobjexport -o /opt/coldfusion/log/FOO.DAT

  NOTE: The following applies to both NT and Solaris users and is to be done ONLY if you are migrating an old policy store to a policy store that has been newly initialized with CF 4.5.1 (both Solaris and NT).

  Do the following 3 steps on the LDAP server you initialized the SM policy store on during installation:

  1. Create an attribute called smDomainAdminOIDs of type StringNoCase. (Leave the OID column blank)
  2. Edit the objectclass smdomain and add smDomainAdminOIDs as an allowed attribute.
  3. Save and restart

  This will allow you to use your previously defined policy store data. [15512]

Data sources

• The ODBC drivers have been upgraded to version 3.6, 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 supports versions 6.5 and 7.0 of MS SQLServer and is threadsafe. However, because it cannot maintain connections, you should turn off the "maintain connections" switch in ColdFusion.

Java

• To continue using the CFX_J custom tag, 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.

Tags

• The CFOBJECT tag is supported only for Java objects (TYPE=Java).
• 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]

Configuring MySQL data sources on ColdFusion Server for Linux

Allaire now ships a MySQL ODBC driver provided by Merant. In addition, you can use the myODBC driver provided by mySQL.

Use the following information to configure ColdFusion Server for Linux to use the myODBC driver for MySQL data sources. ColdFusion can use the myODBC driver to talk to the mySQL data base. Information on mySQL can be found at mysql.com. Allaire has verified that myODBC version 2.50.26 works with mySQL version 3.22.27 and ColdFusion for Linux. You can download myODBC at www.mysql.com/downloadmyodbc.html.

Running MySQL

Make sure that MySQL has been installed and is running. If you do a ps -eaf | grep mysqld you should see some entries. Here is an example of how you would run it:

/usr/local/bin/safe_mysqld &.

Try running /usr/local/bin/mysqlshow mysql host to view the default database. Try running a query using the /usr/local/bin/mysql program, for example: select * from host\g

On Linux, the current versions of MySQL do not support subselects. ColdFusion uses this SQL syntax to expire client variable storage. As a result, cfexec will report an error when trying to expire client variables. As a work-around, Allaire provides a CFML template in /opt/coldfusion/scripts/mysql_expire.cfm which you can run manually, or use the CF scheduler to schedule this template to run every day. You should save the template in your document root directory.

Adding a MySQL data source

ColdFusion 4.5.1 allows you to use the ColdFusion Administrator to add the MySQL data source. Before the mySQL driver will appear in the ODBC datasources drop-down list, you must build and copy the myODBC driver to /opt/coldfusion/lib/libmyodbc.so. The Merant mySQL driver will always appear in the list.

Configuring PostgreSQL data sources on ColdFusion Server for Linux

ColdFusion 4.5.1 for Linux now includes the unixODBC PostgreSQL ODBC driver. For more information on unixODBC, see www.unixODBC.com.

You must have the 'postmaster' process running on your system in order to use the PostgreSQL database. For more information on PostgreSQL, see http://www.postgresql.org/.

In order to populate your PostgreSQL database with the example application data sources, see the file /opt/coldfusion/database/PostgreSQL/README.

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 Solaris registry to ColdFusion 4.5.1

NOTE: This applies to Solaris only. 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.1 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.1.

The cfregup.sh script must be run as root on a machine with a running ColdFusion 3.x or 4.0 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.1 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.1 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.1 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 following is an example where the error processing is redirected to nopipe.htm

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

NOTE: 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 ColdFusion 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 failover 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 is now integrated into the ColdFusion Server Linux installation.
• Windows 2000 systems must be configured to use ClusterCATS dynamic IP addresses for Failover (High Availability installation option) to function properly. Static addresses are currently not supported on Windows 2000 systems.

Configuring ClusterCATS on Windows NT:

• A minimum of Windows NT Service Pack 4 must be installed on each member.
• The Streams Environment must be added to Network Protocols on NT 4.0 based systems. On Windows 2000 systems, the installation procedure will automatically configure Streams.
1. Right mouse on the Network Neighborhood.
2. Select Properties.
3. Select Protocols.
4. Click Add.
5. Select Streams Environment, and click OK.
6. Select Control Panel, select Device, and then select Enable Streams.

Customizing the Web Server's Response When No Resources are Available in a Cluster

When all web servers in a ClusterCATS cluster are busy and/or restricted, a browser's request to any member of the cluster will receive a HTTP 503 (server too busy) failure response from the server. For example, trying to browse index.html on server KITCAT in the completely busy cluster KitKatCluster will return the following error response:

index.html is not currently available in cluster KitKatCluster.
Please try again later.

To override this default 503 response with one more appropriate for your web site, you must edit the ClusterCATS server entries in the registry for your OS platform.

In the following procedure, you will add a value called "ErrorUrl" to each desired ClusterCATS server registry key. This value will specify the name of a file, relative to the server's document root, containing the text you want browsers to see when all servers in the cluster are unavailable. The procedure differs between Window NT and Solaris/Linux platforms.

For Windows NT:

1. Edit the registry and open the key:

   HKEY_LOCAL_MACHINE | SYSTEM | CurrentControlSet | Services | BrightTiger | Servers

   Under the Servers key, you should see the names of the current cluster members for this system. These are the individual "server keys" that you will modify in the next step.

2. For each cluster member that you wish to customize for the 503 error response, create the following REG_SZ value under its server key:

   ErrorUrl  NameOfErrorFile.htm

   Replace "NameOfErrorFile.htm" with the name of the file containing your selected error text, relative to this server's web document root. For example, the sample file above might be physically located in C:/Inetpub/wwwroot/NameOfErrorFile.html.

3. Close the registry editor.
4. Test the change by restricting all servers in the cluster -- a one-node cluster simplifies this -- and hitting a server with a browser. You should see your customized error text returned.

For UNIX:

NOTE: Solaris/Linux versions of ClusterCATS user a file called bt.registry to emulate aspects of NT registry features. This is an ordinary text file with stringent formatting requirements. This procedure requires hand-editing of this file. Be careful!

1. Become the super user (root).
2. Stop all ClusterCATS activity with the command:

   # /usr/lib/btcats/btadmin stop all

3. Edit the file /usr/lib/btcats/database/bt.registry with an editor.
4. Search for the string

   	hkey_local_machine\system\currentcontrolset\services\brighttiger\servers:6

   Under this key, you should see the names of the current cluster members for this system in distinct blocks for text. For example, here's the first part of an entry for a server called ME:

   	hkey_local_machine\system\currentcontrolset\services\brighttiger\servers\me.test.com:214
   	ClusterMate:          	;                     	REG_SZ
   	ClusterName:          	TestCluster;           	REG_SZ
   	InstanceName:         	https-me;	          	REG_SZ
   	.
   	.
   	.

5. For each server that you wish to customize for the 503 error response, create the following value:

      	ErrorUrl:		NameOfErrorFile.html;		REG_SZ

   Replace "NameOfErrorFile.htm" with the name of the file containing your selected error text, relative to this server's web document root. For example, the sample file above might be physically located in:

      	/usr/netscape/suitespot/https-me/docroot/NameOfErrorFile.html

   Your modified server key should look something like this:

   	hkey_local_machine\system\currentcontrolset\services\brighttiger\servers\me.test.com:214
      	ErrorUrl:				NameOfErrorFile.html;	REG_SZ
   	ClusterMate:          	;                     	REG_SZ
   	ClusterName:          	TestCluster;           	REG_SZ
   	InstanceName:         	https-me;	          	REG_SZ
   	.
   	.
   	.

6. Save the file and exit your editor.
7. Restart ClusterCATS operations with the command:

   	# /usr/lib/btcats/btadmin start all

8. Test the change by restricting all servers in the cluster -- a one-node cluster simplifies this -- and hitting a server with a browser. You should see your customized error text returned.

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 dynamic-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.

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. You 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.

Gradual Redirection Load Management and Session State Management

When session aware load management is enabled (the default), 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.

Session-Aware Load Balancing and the Gradual Redirection Threshold

When using session-aware load balancing for a cluster, it is recommended that Gradual Redirection Threshold be enabled and set explicitly to 0%. This setting allows ClusterCATS to optimize load balancing for browser requests that have not entered a session.

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.

URL for ClusterCATS Explorer Web Addition

If you are using Netscape Enterprise Server V3.x, the URL for accessing the ClusterCATS Explorer Web addition (btweb) is:
http://:/admin-serv/btweb/default.html

If you are using Netscape Enterprise Server V4.0x, the URL for accesing the ClusterCATS Explorer Web addition (btweb) is:
http://server-name>:/https-admserv/btweb/default.html

Configuring ClusterCATS Explorer Web Addition with Apache

Make the following additions to httpd.conf to enable btweb, replacing the IP address specified with one appropriate for your system. Also enable user/password authentication for the virtual directory.

Once you have configured the server in this manner, to access btweb, go to the URL http://btweb, where btweb corresponds to the IP address you selected for the VirtualHost.

##
###  BTWeb Administration
###
Listen 192.168.96.71:2222
<VirtualHost 192.168.96.71:2222>
        ServerAdmin root@localhost
        DocumentRoot /usr/lib/btcats/btweb
        DirectoryIndex default.htm
        ServerName btweb
        ErrorLog logs/btweb_error_log
        CustomLog logs/btweb_access_log combined
        ### BTWeb stuff ###
        AddHandler cgi-script .exe
        <Directory "/usr/lib/btcats/btweb/">
                Options FollowSymLinks
                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>
</VirtualHost>

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

ColdFusion Application Probe and ColdFusion Running in Distributed Mode

ClusterCATS can not restart ColdFusion Server if the server is running on a remote system. However, it will restrict access to the server and redirect traffic around the problem, if possible.

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+, 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 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 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.

Known problems

• Unpredictable Behavior Internet Explorer from iPlanet 4.0 Web Server when all Cluster Members are Busy

  Using Microsoft Internet Explorer (IE) to browse the *home page* of a completely busy ClusterCATS cluster running the iPlanet 4.0 web server can cause a confusing results for the client.

  Normally, in this case, when the all members of the cluster are busy, an HTTP 503 error response is returned to the browser along with text like the following:

  	index.html is not currently available in cluseter KitKatCluster.
  	Please try again later.

  Occasionally, when the busy web server is iPlanet 4.0, this result is not returned to IE when the home page is browsed. Instead, a dialogue box may appear prompting the client for file-download information.

  The workaround for this problem is to establish an "error URL" file for each server in the cluster. This is a file containing a customized "server busy" message for your web site. This text is reliably returned to IE when the cluster is busy.

  NOTE: Instructions on creating an error-URL message are contained in the release note "Creating an Alternate Web Server Response to 'Resource Not Available in Cluster' Message."

• Adding or Creating a Cluster under heavy load
  When you create a cluster or add a Web server to a cluster with the ClusterCATS Explorer and that Web server is under heavy load, you may get a message 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 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, Netscape Administrative Server will display a warning the next time you attempt to manage your server with the Netscape Administrator. The warning states that the Netscape configuration files have been modified "by hand." Click OK to accept the warning, then 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 happens, 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 has occurred, there may be a problem with one of the adjacent router's ARP cache timeout settings. If the ARP cache timeout is off, set it to a value that is not too large, such as between 2 and 30 seconds. Accessing the router configuration settings will be vendor specific; refer to associated hardware and software documentation for the 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. To update the list of Web sites and eliminate the stale view of the IP failover Web site, perform an MMC refresh operation.
• 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 the entries, edit the 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 restart the Netscape Enterprise Server for these changes to take effect.

• Multiple ClusterCATS Explorers viewing the same SmartClusters
  When Multiple ClusterCATS Explorers view one or more clusters simultaneously, they 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. (The 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.
• Exiting or dismissing the Server Properties box can disable gradual redirection
  If you examine a ClusterCATS server's Properties box and then dismiss the box by either clicking OK or pressing Enter, the server's Gradual Redirection Treshold can be unintentionally disabled. This can have a negative impact on the cluster if Session-Aware Load Balancing is in effect. To avoid this problem:
  
  • If you are only examing the server's properties, dismiss the Properties box by clicking Cancel.
  • If you have updated the server's properties, save the changes and dismiss the Properties box by selecting the OK options on the Load tab. (In other words, never select OK on the General or State tabs.)

ClusterCATS Virtual Directory btauxdir is not always being created on system running IIS

ClusterCATS requires that the virtual directory btauxdir exist under each virtual server which will be clustered and that it point to /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.

Configuring the Apache Web Server

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

All Apache Web servers that are binary compatible with Apache 1.3.6 and binary compatible versions (up to and including 1.3.12) are supported with the current module on all platforms. The current ColdFusion Apache 1.3.6 module will work without change with all Apache Web servers that are binary compatible with Apache 1.3.6

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.

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

Other issues:

• 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 the Apache version compatible with 1.3.6 installed.
• The precompiled Apache 1.3 module for ColdFusion 4.5.1 will only work with Apache Web servers that are binary compatible with Apache 1.3.6. 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.

Other issues:

• The precompiled Apache 1.3 module for ColdFusion 4.5.1 will only work with Apache Web servers that are binary compatible with Apache 1.3.6. 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. To use apxs you must have a C compiler and Perl installed and in your path.

Running Allaire Forums under ColdFusion 4.5.1

If you are running Allaire Forums with ColdFusion Server 4.5.1 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