Administering
ColdFusion Server
ColdFusion 4.5
Allaire Corporation
Copyright Notice
© 1999 Allaire Corporation. All rights reserved.
This manual, as well as the software described in it, is furnished under license and may
be used or copied only in accordance with the terms of such license. The content of
this manual is furnished for informational use only, is subject to change without
notice, and should not be construed as a commitment by Allaire Corporation. Allaire
Corporation assumes no responsibility or liability for any errors or inaccuracies that
may appear in this book.
Except as permitted by such license, no part of this publication may be reproduced,
stored in a retrieval system, or transmitted in any form or by any means, electronic,
mechanical, recording, or otherwise, without the prior written permission of Allaire
Corporation.
ColdFusion and HomeSite are federally registered trademarks of Allaire Corporation,
HomeSite, the ColdFusion logo and the Allaire logo are trademarks of Allaire
Corporation in the USA and other countries. Microsoft, Windows, Windows NT,
Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft
Corporation. All other products or name brands are the trademarks of their respective
holders. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The
Open Group. PostScript is a trademark of Adobe Systems Inc.
Part number: AA-45ADM-RK
Contents
Preface: Welcome to ColdFusion ...................................................................xi
Intended Audience......................................................................................................................... xii
Welcome to the ColdFusion 4.5 Web Application Server........................................................... xii
Products and System Requirements ............................................................................................ xii
New features in ColdFusion 4.5 ....................................................................................................xiv
New visual tools......................................................................................................................xiv
Enhancements to CFML ........................................................................................................xiv
Better reliability .......................................................................................................................xv
Improved performance...........................................................................................................xv
Enterprise connectivity features ...........................................................................................xvi
Security enhancements..........................................................................................................xvi
Developer Resources ....................................................................................................................xvii
About ColdFusion Documentation........................................................................................... xviii
Documentation updates..................................................................................................... xviii
ColdFusion manuals ........................................................................................................... xviii
ColdFusion Server online documentation...........................................................................xix
Printing ColdFusion documentation....................................................................................xix
Documentation conventions..................................................................................................xx
Getting Answers ..............................................................................................................................xx
Contacting Allaire....................................................................................................................xx
Chapter 1: Installing and Configuring ColdFusion........................................1
ColdFusion System Requirements ................................................................................................. 2
Windows (NT, 98, or 95)........................................................................................................... 2
Solaris (Enterprise edition only).............................................................................................. 4
Linux.......................................................................................................................................... 5
Installing ColdFusion on Windows ................................................................................................5
Verifying that a Web server is running.................................................................................... 5
Installing ColdFusion............................................................................................................... 6
Uninstalling ColdFusion........................................................................................................ 11
Performing Windows-specific configurations ..................................................................... 11
Installing ColdFusion on Solaris................................................................................................... 13
Installing ColdFusion............................................................................................................. 14
Upgrading from a previous release of ColdFuison.............................................................. 16
iv Administering ColdFusion Server
Uninstalling ColdFusion.........................................................................................................16
Configuring Web servers for Solaris.......................................................................................16
Using scripts to start and stop ColdFusion manually..........................................................22
Installing ColdFusion on Linux .....................................................................................................23
Installing ColdFusion..............................................................................................................23
Uninstalling ColdFusion.........................................................................................................25
Chapter 2: Introduction to ColdFusion Server.............................................27
Overview of Administering ColdFusion........................................................................................28
Accessing the Administrator...................................................................................................28
Initial ColdFusion administration tasks................................................................................29
Summary of Administrative Tasks.................................................................................................29
The ColdFusion Administrator......................................................................................................30
ColdFusion Services on Windows NT ...........................................................................................32
ColdFusion Processes on Solaris...................................................................................................33
Starting and Stopping ColdFusion ................................................................................................33
Windows NT ............................................................................................................................34
Solaris.......................................................................................................................................34
Windows 95 and Windows 98.................................................................................................34
Stopping ColdFusion ..............................................................................................................35
Chapter 3: Configuring ColdFusion Server ..................................................37
The ColdFusion Administrator......................................................................................................39
Accessing the Administrator remotely ..................................................................................39
Starting and Stopping ColdFusion ................................................................................................41
Using batch files to start and stop ColdFusion (Windows)..................................................41
Using scripts to start and stop ColdFusion (Solaris)............................................................42
The Server Settings Page ................................................................................................................42
Caching Settings .............................................................................................................................44
Configuring Administrator Security..............................................................................................44
Managing Client Variables.............................................................................................................45
Planning client state management........................................................................................45
State Management and Server Clustering....................................................................................48
Configuring a data source in a clustering environment ......................................................48
Enabling External Client State Management................................................................................48
Client variable storage options ..............................................................................................49
Purge client variables..............................................................................................................49
Disable global client variable updates...................................................................................49
Create client variable data source tables...............................................................................50
Migrating Client Variable Data......................................................................................................50
Creating client variable tables................................................................................................50
Sample table creation page ....................................................................................................51
Enabling Application and Session Variables ................................................................................51
Specifying timeouts.................................................................................................................51
Monitoring ColdFusion Performance...........................................................................................52
ColdFusion counters available...............................................................................................52
Locking Variables............................................................................................................................53
Contents v
ColdFusion Java Settings................................................................................................................54
ColdFusion Version Information...................................................................................................55
Solaris version information....................................................................................................55
The ColdFusion Logging Page .......................................................................................................56
Administrator email address..................................................................................................56
Log directory............................................................................................................................56
Log slow pages.........................................................................................................................57
Logging email messages .........................................................................................................57
Log files created by ColdFusion ............................................................................................57
Log file format..........................................................................................................................58
Mapping Directories.......................................................................................................................58
Using the Extensions Pages............................................................................................................59
Managing CFX tags..................................................................................................................59
CFX tag samples ......................................................................................................................59
Registering a Java applet.........................................................................................................60
Debug Settings in the ColdFusion Administrator........................................................................62
Configuring Administrator Mail....................................................................................................63
Indexing Data with Verity...............................................................................................................64
Using the Verity Collections page..........................................................................................64
Creating a collection ...............................................................................................................64
Populating a collection ...........................................................................................................65
Verity Supported File Types...........................................................................................................65
Repairing, Optimizing, Purging, and Deleting Collections.........................................................66
Configuring Server-Side Source Control.......................................................................................67
Requirements ..........................................................................................................................67
Using ColdFusion in a Distributed Configuration.......................................................................68
Distributed ColdFusion and clustering.................................................................................68
Changes in the 4.5 version......................................................................................................68
Configuring Distributed ColdFusion ............................................................................................69
Using the modified plug-in ....................................................................................................69
The Network Listener Module (NLM) ...................................................................................71
Installing the module on UNIX..............................................................................................72
Listener Module Command Line Options....................................................................................73
Using the INI file to specify startup options .........................................................................74
Chapter 4: Managing Data Sources ..............................................................77
About ColdFusion Data Sources....................................................................................................78
Supported Databases .....................................................................................................................79
Where to go from here ............................................................................................................80
Choosing the Right Drivers............................................................................................................80
ODBC Drivers ..........................................................................................................................80
Native Drivers..........................................................................................................................81
OLE DB Drivers........................................................................................................................82
Adding Data Sources for ColdFusion ............................................................................................82
ColdFusion Settings................................................................................................................84
Verifying ColdFusion Data Sources...............................................................................................85
Connecting to Microsoft SQL Server Databases ..........................................................................87
Configuring Microsoft SQL Server Options (Windows).......................................................87
vi Administering ColdFusion Server
Configuring Microsoft SQL Server Options (UNIX) .............................................................88
Connecting to Visual FoxPro Databases.......................................................................................89
Configuring Visual FoxPro Options (Windows)....................................................................89
Connecting to OpenIngress Databases.........................................................................................90
Configuring OpenIngress Options (UNIX)............................................................................90
Connecting to dBase Databases....................................................................................................92
Configuring dBase Options (Windows).................................................................................92
Configuring Inprise dBase Options (UNIX) ..........................................................................93
Connecting to Microsoft Access Databases..................................................................................94
Configuring Microsoft Access Options (Windows) ..............................................................94
Access Connectivity Tips (Windows).....................................................................................95
Connecting to Microsoft Excel Databases ....................................................................................96
Configuring Microsoft Excel Options (Windows).................................................................96
Connecting to ASCII Text Databases.............................................................................................97
Configuring Microsoft Text options (Windows)...................................................................97
Configuring Microsoft Text ODBC options (UNIX)..............................................................97
Connecting to Oracle 7.3/8.0 Databases.......................................................................................98
Configuring Oracle 7.3/8.0 Options (Windows) ...................................................................98
Configuring Oracle 7.3/8.0 Options (UNIX)..........................................................................98
Connecting to Oracle 7 and 8.0 Databases (UNIX)...............................................................99
Connecting to Oracle 8.0.x through ODBC (UNIX)............................................................101
Troubleshooting the Oracle 7.3 Native Driver (Windows).................................................102
Configuring the Oracle 8 Client (Windows, UNIX).............................................................103
Connecting to DB2 Data Sources................................................................................................105
Configuring DB2 Options (Windows)..................................................................................105
Configuring DB2 Options (UNIX)........................................................................................105
Configuring System and Services Files (UNIX)...................................................................106
Installing and Configuring DB2 Client Enabler (UNIX).....................................................107
Data source and start script settings for DB2 (UNIX).........................................................108
DB2 Binding and Privileges for ODBC (UNIX)....................................................................109
Executing a DB2 Stored Procedure (Windows, UNIX).......................................................109
Connecting to Informix data sources..........................................................................................111
Configuring Informix Options (Windows) ..........................................................................111
Configuring Informix Options (UNIX).................................................................................112
Connecting to Informix Data Sources (UNIX) ....................................................................113
Connecting to Informix through ODBC/CLI (Windows, UNIX) .......................................114
Connecting to Sybase System 11 data sources...........................................................................117
Configuring Sybase System 11 Options (Windows) ...........................................................117
Configuring Sybase System 11 Options (UNIX)..................................................................118
Tips for Connecting to Sybase System 11 (UNIX)...............................................................119
Using ColdFusion to Create a Data Source.................................................................................120
Chapter 5: Scheduling and Static Page Generation ..................................123
About Scheduling ColdFusion Pages ..........................................................................................124
Scheduling a ColdFusion Page ....................................................................................................124
Specifying the Interval for a Scheduled Task..............................................................................125
Specifying the Page to Execute ....................................................................................................126
Saving Scheduled Output to a File ..............................................................................................126
Contents vii
Defining the Scheduler Refresh Interval.....................................................................................126
Logging Scheduled Events ...........................................................................................................127
Chapter 6: Creating Scalable and Highly Available Web Sites.................129
What is Scalability? .......................................................................................................................130
Performance ..........................................................................................................................130
Load management ................................................................................................................132
Issues Affecting Successful Scalability Implementations..........................................................132
Designing and coding scalable applications.......................................................................133
Avoiding common bottlenecks ............................................................................................137
DNS effects on Web site performance and availability......................................................138
Load testing your Web applications....................................................................................142
What is Web Site Availability?......................................................................................................144
Availability & reliability.........................................................................................................145
Common failures...................................................................................................................146
A Web site availability scenario............................................................................................146
Failover considerations.........................................................................................................147
Techniques for Creating Scalable & Highly Available Sites.......................................................149
What is clustering?.................................................................................................................149
Hardware-based clustering solutions..................................................................................150
Software-based clustering solutions....................................................................................152
Combining hardware and software clustering solutions...................................................154
Introducing ClusterCATS for ColdFusion...................................................................................155
ClusterCATS for ColdFusion Features.................................................................................155
ClusterCATS for ColdFusion Components.................................................................................158
ClusterCATS Server ...............................................................................................................158
ClusterCATS Explorer ...........................................................................................................159
ClusterCATS Server Administrator ......................................................................................160
Before You Install..........................................................................................................................161
Review the release notes.......................................................................................................161
Verify system requirements..................................................................................................161
Configure your primary DNS server....................................................................................163
Configure your Web server’s network settings ...................................................................171
Configure ClusterCATS for use across firewalls..................................................................184
Installing ClusterCATS .................................................................................................................185
Creating Clusters...........................................................................................................................192
Creating clusters with the Cluster Setup Wizard................................................................192
Creating clusters manually...................................................................................................199
Configuring Load Balancing & High Availability Features........................................................203
Configuring server load thresholds......................................................................................203
Configuring session-aware load balancing.........................................................................207
Configuring ColdFusion probes...........................................................................................208
Integrating ClusterCATS with load balancing devices.......................................................211
Configuring administrator alarm notifications ..................................................................215
Configuring administration e-mail support .......................................................................217
Configuring cluster administration security.......................................................................218
Performing Common Cluster Administration Tasks.................................................................223
Changing a server’s state......................................................................................................224
viii Administering ColdFusion Server
Restricting a server from participating in a cluster ............................................................224
Putting a cluster member in maintenance mode...............................................................225
Updating software or content on an existing cluster .........................................................228
Resetting a server’s configuration to its pre-clustered state..............................................230
Administering UNIX-based Clusters...........................................................................................231
Using the ClusterCATS Web Explorer..................................................................................231
Using the ClusterCATS server utilities.................................................................................261
Troubleshooting............................................................................................................................267
Other Informational Resources...................................................................................................267
White papers..........................................................................................................................267
Web sites ................................................................................................................................268
Books......................................................................................................................................268
Chapter 7: Using CGI with ColdFusion........................................................269
CGI vs. Web Server APIs ...............................................................................................................270
Limitations of CGI.........................................................................................................................270
Referencing Application Pages with CGI ....................................................................................271
URLs and the cfml.exe script................................................................................................271
Application page references.................................................................................................272
Chapter 8: ColdFusion Security...................................................................273
Why Is ColdFusion Security Important? 274
Types of ColdFusion Security...............................................................................................275
Choosing a Level of ColdFusion Security ...................................................................................276
Developing Applications ......................................................................................................277
Deploying Applications ........................................................................................................278
Securing the ColdFusion Administrator..............................................................................280
To Learn More About Security.....................................................................................................281
Chapter 9: Configuring Basic Security........................................................283
About Basic Security.....................................................................................................................284
Installation defaults ..............................................................................................................284
Configuring Basic Remote Development Security.....................................................................284
Securing data sources ...........................................................................................................285
ColdFusion Remote Development Services (RDS) ....................................................................285
Basic Security Limitations ....................................................................................................285
Securing ColdFusion file resources .....................................................................................286
Securing ColdFusion data sources.......................................................................................286
Using a Password to Restrict Access to RDS...............................................................................287
ColdFusion Studio Password................................................................................................287
Removing password-based access control: Windows........................................................287
Removing password-based access control: Solaris............................................................287
Configuring Basic Runtime Security...........................................................................................288
Chapter 10: Configuring Advanced Security .............................................289
What is Advanced Security? .........................................................................................................290
Contents ix
Advanced Security Basics.............................................................................................................290
User Directories.....................................................................................................................291
Resources...............................................................................................................................291
Policies ...................................................................................................................................292
Security Contexts...................................................................................................................293
Advanced Security Implementations..........................................................................................294
Securing Applications with User Security...........................................................................294
Securing Resources with RDS Security................................................................................295
Securing Applications with a Security Sandbox .................................................................295
Securing the ColdFusion Administrator..............................................................................296
Creating an Advanced Security Framework ...............................................................................297
Implementation summary ...................................................................................................297
Installing Advanced Security .......................................................................................................298
Setting Up a Security Server.........................................................................................................299
Caching Advanced Security Information....................................................................................300
Defining User Directories ............................................................................................................301
Defining a Security Context .........................................................................................................304
Specifying Resources to Protect...................................................................................................305
Implementing ColdFusion RDS Security....................................................................................307
Implementing User Security........................................................................................................308
Implementing Server Sandbox Security .....................................................................................308
Securing the ColdFusion Administrator .....................................................................................310
Viewing a Map of your Security Framework...............................................................................311
An Example of ColdFusion Studio Security................................................................................311
Enabling Advanced Security.................................................................................................312
Specifying a User Directory..................................................................................................312
Defining a security context...................................................................................................312
Specifying resources to protect............................................................................................313
Adding policies......................................................................................................................314
Granting access privileges....................................................................................................314
Assigning users/groups to policies ......................................................................................315
Enable ColdFusion Studio Security.....................................................................................316
Undocumented Tags and Functions...........................................................................................317
Administrative Functions.....................................................................................................318
Administrative Tags ..............................................................................................................318
Index ..............................................................................................................319
x Administering ColdFusion Server
Preface Welcome to ColdFusion
Administering ColdFusion Server is intended for anyone who needs to install,
configure, and maintain ColdFusion Server.
Contents
• Intended Audience...........................................................................................xii
• Welcome to the ColdFusion 4.5 Web Application Server..............................xii
• Products and System Requirements...............................................................xii
• New features in ColdFusion 4.5 ..................................................................... xiv
• Developer Resources...................................................................................... xvii
• About ColdFusion Documentation ............................................................. xviii
• Getting Answers ................................................................................................xx
xii Administering ColdFusion Server
Intended Audience
Administering ColdFusion Server is meant for anyone who needs to install, configure,
and maintain one or more ColdFusion Server installations.
Welcome to the ColdFusion 4.5 Web Application Server
The ColdFusion 4.5 release focuses on fundamentals — the fundamentals of delivering
your e-business: faster development, better reliability, enhanced scalability, expanded
integration, and stronger security.
At the center of the ColdFusion 4.5 release is an application server platform that's been
highly optimized with new functionality and native support for UNIX. As a result, your
e-business systems will run better and do more. With this release we're launching a
new edition of ColdFusion Server for Linux so you can take advantage of the reliability
and performance of the hottest new Internet server operating system.
While optimizing the core server, we also enhanced fundamental features including
email integration, server-side FTP and HTTP, advanced security, scheduling, and
database connectivity — again giving you more reliability and new functionality.
The focus on fundamentals extends to new features. As part of a broad new
commitment to Java, ColdFusion 4.5 has a range of new Java integration options from
Java CFXs to Java Servlet support to Java object and EJB connectivity. In ColdFusion
Studio 4.5, we added new tools to make you more productive including a flexible new
project architecture that makes managing and deploying complex Web applications a
snap. On the server, we focused on reliability, performance and security with features
such as service-level fail-over, Cisco Local Director integration, and OS security
integration.
Whether you're revolutionizing your company's HR operations, building the next
generation of your firm's global intranet, or launching the next killer .COM company,
you'll find the speed, scalability, connectivity, and security you need in ColdFusion 4.5.
Products and System Requirements
ColdFusion has been fully tested on the following platforms and with the following
configurations.
ColdFusion Server 4.5 Enterprise Edition for Windows
• Windows NT 4.0 SP4+
• Intel Pentium or above
• 150 MB hard disk space
• 128 MB RAM (256 MB recommended for clustering)
Preface xiii
ColdFusion Server 4.5 Enterprise Edition for Solaris
• SPARC Solaris 2.5.1, 2.6, or 7 (patch 103582-1B or higher)
• 128 MB RAM (256 MB recommended for clustering)
• 200 MB hard disk space
ColdFusion Server 4.5 Enterprise Edition for Linux
• Red Hat Linux 6.0 or 6.1
• Intel Pentium or above
• 128 MB RAM (256 MB recommended for clustering)
• 150 MB hard disk space
ColdFusion Server 4.5 Professional Edition for Windows
• Windows 95/98 or Windows NT 4.0
• Intel Pentium or above
• 50 MB hard disk space
• 32 MB RAM (128 MB recommended)
ColdFusion Server 4.5 Professional Edition for Linux
• Red Hat Linux 6.0 or 6.1
• Intel Pentium or above
• 64 MB RAM (128 MB recommended)
• 100 MB hard disk space
ColdFusion Studio 4.5
• Windows 95/98/NT4
• Intel Pentium or above
• 35 MB hard disk space
• 32 MB RAM (64 MB recommended)
xiv Administering ColdFusion Server
New features in ColdFusion 4.5
A wide range of new features are available in ColdFusion 4.5.
New visual tools
Universal File Browser — Access all your files from a single explorer that integrates
access to the Windows file system, ColdFusion RDS servers, and FTP servers. Dragand-drop between any of these services all in an integrated file browser.
Advanced Project Management — Manage your complex Web application
development projects with a new project architecture that gives you more flexibility
and control using physical, virtual, and auto-inclusive project folders as well as project
resource browsing.
Scriptable Deployment — Deploy applications to complex server configurations with
FTP or ColdFusion Remote Development Services (RDS). Use VBScript or Java Script to
fully script deployment of projects with granular control over how files uploaded.
Setup deployment scripts using a powerful wizard and save scripts for re-use.
Collapsible Code — Work with large, complex scripts and pages more easily by
collapsing sections of the code in the editor so you can build sophisticated
applications more quickly.
Function Insight — Find the parameters and format for functions instantly and inline
as you code.
Image Map Editor — Create image maps right in ColdFusion Studio with a new easyto-use visual tool.
Configuration Wizard — Setup your work environment so it meets all your needs
using any of more than dozen common configurations.
TopStyle CSS Editor — Create and edit standards-compliant cascading style sheets to
easily control the look and feel of your web applications.
WML Support — Build wireless Web applications quickly and easily with the complete
set of Wireless Markup Language (WML) visual tools.
Enhancements to CFML
Object Scripting — Instantiate and script objects using CFML script in addition to the
CFOBJECT tag easier integration with distributed object middleware such as COM and
CORBA.
Structured Exception Handling — Exception handling now offers hierarchical
exception handling that supports both greater customization and greater access to
internal exceptions.
String Conversion Functions — Convert strings quickly and easily to be compatible
with Java Script and XML standards.
Preface xv
Better reliability
Server Probes — Guarantee high availability by automatically detecting when a
ColdFusion Server or Web server hangs or stops, failing-over to a new machine in a
ColdFusion cluster, and restarting the server with problems. (Enterprise Edition only)
Improved Automatic Server Recovery — Monitor and automatically restart server
process in case of failures or critical errors on individual servers not deployed in a
cluster.
Clustering Support for Apache — Setup ColdFusion clusters on Linux and Solaris
using the Apache Web Server. (Enterprise Edition only)
Automatic Shared Variable Locking — Lock user and session variable reads
automatically at the server level to prevent destabilizing conflicts and control thread
write contentions. Configure variable locking to meet the specific needs of your
applications.
Individual Data Source Control — Enable and disable individual data sources
individually without affecting server availability for runtime data source maintenance
without server restarts.
Improved performance
Cisco Local Director Integration — Deliver very large scale sites with Cisco Local
Director intelligently balancing load based on the load metrics provided by the
ColdFusion Servers in a cluster. (Enterprise Edition only)
Client-Side Page Caching — Leverage browser page caching to avoid unnecessary
downloads of unchanged pages and improve overall site performance.
Programmatically control refresh of client-side cache to ensure users see most up-todate output.
White Space Removal — Reduce white space left by processed code in application
pages to make the pages smaller and faster. Control white space removal
programmatically or administratively.
Scriptable Performance Metrics — Track key server metrics at run time through your
own scripts for intelligent diagnosis of performance bottlenecks of stability problems
in your applications.
Performance Debugging Data — Access detailed debugging information on the
performance of each individual page included in an application page that is being
debugged.
xvi Administering ColdFusion Server
Enterprise connectivity features
Transaction Commit and Rollback — Control database transactions with
programmable commit and rollback support for more reliable and better-managed
database interactions.
Java Object and EJB Connectivity — Connect to any Java object or Enterprise JavaBean
(EJB) hosted by any major EJB server to extend ColdFusion and access complex
business logic or third party distributed components.
Java Servlets — Call Java Servlets hosted by a Servlet Engine such as Allaire JRun from
within a ColdFusion application to access extended functionality
Java-based ColdFusion Extensions (CFX) — Extend ColdFusion with new
functionality through CFXs created with Java.
Binary Object Support — Use Character Large Binary Object (CLOB) support to
encoded binary objects, transmit them via XML, and store them in databases or files.
SQL Bind Parameters — Improve query performance, security and flexibility with
explicitly typed query parameters.
WDDX 1.0 — Exchange complex data, including encoded images, between servers and
with other programming environments even faster using the latest version of Web
Distributed Data Exchange (WDDX).
OS Command Execution — Execute OS shell scripts, services, executables and batch
files from within ColdFusion applications.
LDAP 3.0 — Use all the power of LDAP 3.0 for directory access including file filtering,
SSL encryption, and Microsoft Active Directory integration.
Enhanced Mail Integration — Develop more sophisticated and robust email
applications with new support for controlling mail headers, BCC, and multiple file
attachments.
Improved Server-Side HTTP — Use URL redirection, SSL, cookies, return headers, and
more robust server-side HTTP support for building distributed Web applications.
Security enhancements
General OS Security Integration — Secure entire Web applications and control access
to files and objects through your existing Windows NT security architecture.
Authenticated users in your applications can be limited to privileges authorized
through Windows security. (Windows NT Only)
OS Server Sandbox Security — Secure shared hosting environments more easily by
creating Server Sandboxes with Windows NT security. OS Server Sandboxes process all
requests under the privileges of a designated Windows NT user account (Enterprise
Edition for Windows only).
Enhanced Advanced Security — Secure CFML functions and enable CFML code
segments to be executed using the run-time security permissions of a designated user.
Preface xvii
New Advanced Security Interface — Manage Advanced Security configuration more
quickly and easily with a completely redesigned browser-based resource view.
Scriptable Advanced Security Administration — Configure ColdFusion Advanced
Security through your own CFML scripts for easier maintenance of ColdFusion
Servers.
Developer Resources
Allaire Corporation is committed to setting the standard for customer support in
developer education, technical support, and professional services. Our Web site is
designed to give you quick access to the entire range of online resources.
Allaire Developer Services
Resource Description
Allaire Web site
www.allaire.com
Technical Support
www.allaire.com/support
Training and Consulting
www.allaire.com/services
Developer Community
www.allaire.com/developer
Allaire Partners
www.allaire.com/partners
General information about Allaire products and
services.
Allaire offers a wide range of professional support
programs. This page explains all of the available
options.
Information about training classes, online
courses, and consulting services offered by
Allaire.
All of the resources you need to stay on the
cutting edge of ColdFusion development,
including online discussion groups, Knowledge
Base, Component Exchange, Resource Library,
technical papers and more.
The Allaire Alliance is a network of solution
providers, application developers, resellers, and
hosting services creating solutions with
ColdFusion.
xviii Administering ColdFusion Server
About ColdFusion Documentation
ColdFusion documentation is designed to provide support for all components of the
ColdFusion development system. Both the print and online versions are organized to
allow you to quickly locate the information you need.
In addition to the book set, the documentation is provided in two other formats:
• HTML — Browser-based Help references.
• Adobe Acrobat (PDF) — Available from the root level on the product CD-ROM
and from the Developer area of Allaire’s Web site at http://www.allaire.com/
developer
Documentation updates
Late additions and corrections to ColdFusion printed documentation are listed in the
Documentation Updates page. To reach this page, open the Welcome to ColdFusion
page installed with ColdFusion, where you’ll find links to the update page as well as
links to other pages containing useful information about ColdFusion, Allaire support
options, and Allaire products and services.
For ColdFusion Studio users, you can access the documentation update page by
clicking on the Help resource tab and browsing your way through the online help tree
to the Allaire Support folder.
.
ColdFusion manuals
The core ColdFusion documentation set consists of the following titles.
Administering ColdFusion Server
Includes instructions for installing ColdFusion Server. Describes configuration options
for maximizing performance, managing data sources, setting security levels, and a
range of development and site management tasks. If you are administering a
ColdFusion site, you’ll need this book to help plan and implement ColdFusion
security, load balancing, and for details about tuning the ColdFusion application
server.
Developing Web Applications with ColdFusion
Presents the fundamentals of ColdFusion application development and deployment.
Also includes detailed information about ColdFusion data sources, user interfaces,
and Web technologies.
CFML Language Reference
Provides the complete syntax, with example code, of all CFML tags and functions.
Preface xix
Using ColdFusion Studio
Documents everything you need to know about using ColdFusion Studio, including
features like projects, source control integration, as well as the Studio workspace and
interface.
Quick Reference to CFML
A valuable quick reference to CFML tags, functions, and variables.
ColdFusion Server online documentation
To view the HTML documentation, open the following URL: http://127.0.0.1/
cfdocs/dochome.htm
Note that because the Verity search libraries are not available on Linux for this release,
the online documentation search facility is not functional on Linux. If you try to open
the search page, a message box opens to explain why the facility is not available.
Acrobat versions of all ColdFusion documentation are available from the root level on
the product CD. If you don’t have a product CD, you can download ColdFusion
documentation from the Allaire web site by visiting
developer
and clicking the Documentation link.
.
http://www.allaire.com/
ColdFusion Studio online documentation
Click the Help resource tab in ColdFusion Studio to view online Help pages. The help
tree contains ColdFusion documentation and a number of additional developer
resources. Studio online documentation is searchable and individual pages can be
bookmarked.
Printing ColdFusion documentation
If you are working with an evaluation version of ColdFusion and would like printed
documentation, access the Adobe Acrobat files found from the root level on the
product CD. If you do not have access to a product CD, you can download the Acrobat
files from the Allaire web site:
Documentation link.
The Acrobat files offer excellent print output. You can print an entire manual,
individual sections, or page ranges of your choice. To get the Acrobat reader, visit:
http://www.acrobat.com.
http://www.allaire.com/developer, click the
xx Administering ColdFusion Server
Documentation conventions
When reading, please be aware of these formatting cues:
• Code samples, filenames, and URLs are set in a
• Notes and tips are identified by bold type
• Bulleted lists present options and features
• Numbered steps indicate procedures
• Tool button icons are generally shown with procedure steps
• Menu levels are separated by the greater than (>) sign
• Text for you to type in is set in italics
monospaced font
Getting Answers
One of the best ways to solve particular programming problems is to tap into the vast
expertise of the ColdFusion developer community on the Allaire Forums. Other
ColdFusion developers on the forum can help you figure out how to do just about
anything with ColdFusion. The search facility can also help you search messages going
back 12 months, allowing you to learn how others have solved a problem you may be
facing. The Forums is a great resource for learning ColdFusion, but it’s also a great
place to see the ColdFusion developer community in action.
Contacting Allaire
Corporate headquarters
Allaire Corporation
One Alewife Center
Cambridge, MA 02140
Tel: 617.761.2000
Fax: 617.761.2001
http://www.allaire.com
Technical support
Telephone support is available Monday through Friday 8 A.M. to 8 P.M. Eastern time
(except holidays)
Toll Free: 888.939.2545 (U.S. and Canada)
Tel: 617.761.2100 (outside U.S. and Canada)
For complete details about Allaire Product Support options, please refer to the Allaire
Support pages on the Allaire web site:
http://www.allaire.com/support.
Preface xxi
Postings to the ColdFusion Support Forum (http://forums.allaire.com) can be
made any time.
Sales
Toll Free: 888.939.2545
Tel: 617.761.2100
Fax: 617.761.2101
Email: sales@allaire.com
Web:
http://www.allaire.com/store
xxii Administering ColdFusion Server
C HAPTER 1
Chapter 1 Installing and Configuring
ColdFusion
This chapter describes ColdFusion’s system requirements and how to install and
configure ColdFusion on your platform.
Contents
• ColdFusion System Requirements.................................................................... 2
• Installing ColdFusion on Windows................................................................... 5
• Installing ColdFusion on Solaris ..................................................................... 13
• Installing ColdFusion on Linux....................................................................... 23
2 Administering ColdFusion Server
ColdFusion System Requirements
ColdFusion v4.5 runs on the following platforms:
• “Windows (NT, 98, or 95)” on page 2
• “Solaris (Enterprise edition only)” on page 4
• “Linux” on page 5
This section describes system requirements for each platform.
Windows (NT, 98, or 95)
The minimum requirements needed to install and run ColdFusion Server on Windows
depend on which edition you install, Enterprise, Professional, or Express.
Note If you plan to use the ClusterCATS software that is included with
ColdFusion to cluster your NT servers, see “Windows NT system
requirements for ClusterCATS Server” on page 162. The ClusterCATS
system requirements may impact your overall environment
requirements.
ColdFusion Server 4.5 Enterprise Edition for Windows
To install and use ColdFusion Server 4.5 Enterprise edition on Windows, your system
must meet the following minimum requirements:
• Windows NT Server v 4.0 with Service Pack 4
• Intel Pentium or higher
• 64 MB of RAM (128 recommended)
•60 MB of free disk space
• A World Wide Web server that supports the NSAPI, ISAPI, or WSAPI application
programming interfaces (APIs). Specific Web servers that work with ColdFusion
on the Windows platform include:
• Internet Information Server v4.0 or greater
• Netscape Enterprise Server v3.51 or greater
• Apache Web Server v1.3.6 or greater
• Common Gateway Interface (CGI)
• A CD-ROM drive
Chapter 1: Installing and Configuring ColdFusion 3
ColdFusion Server 4.5 Professional Edition for Windows
To install and use ColdFusion Server 4.5 Professional edition on Windows, your system
must meet the following minimum requirements:
• Windows 95/98 or Windows NT Server v 4.0 with Service Pack 4
• Intel Pentium or higher
• 32 MB of RAM (128 recommended)
•50 MB of free disk space
• A World Wide Web server that supports the NSAPI, ISAPI, or WSAPI application
programming interfaces (APIs). Specific Web servers that work with ColdFusion
on the Windows platform include:
• Internet Information Server v4.0 or greater
• Netscape Enterprise Server v3.51 or greater
• Apache Web Server v1.3.6 or greater
• Microsoft Personal Web Server (PWS)
• WebSite Server API ( WSAPI)
• Common Gateway Interface (CGI)
• A CD-ROM drive
4 Administering ColdFusion Server
ColdFusion Server 4.5 Express Edition for Windows
To install and use ColdFusion Server 4.5 Express edition on Windows, your system
must meet the following minimum requirements:
• Windows 95/98 or Windows NT Server v 4.0 with Service Pack 4
• Intel Pentium or higher
• 32 MB of RAM (64 recommended)
•25 MB of free disk space
• A World Wide Web server that supports the NSAPI, ISAPI, or WSAPI application
programming interfaces (APIs). Specific Web servers that work with ColdFusion
on the Windows platform include:
• Internet Information Server v4.0 or greater
• Netscape Enterprise Server v3.51 or greater
• Apache Web Server v1.3.6 or greater
• Microsoft Personal Web Server (PWS)
• WebSite Server API ( WSAPI)
• Common Gateway Interface (CGI)
• A CD-ROM drive
Solaris (Enterprise edition only)
To install and use ColdFusion on Solaris, your system must meet the following
minimum requirements:
• Solaris v2.5.1 or greater running on a SPARC workstation
• 128 MB or RAM
• 120 MB of free disk space for a full install
• Specific Web servers that work with ColdFusion on the Solaris platform include:
• Netscape Fast Track/Enterprise Server versions 2.01 or 3.0, 3.51
• Apache Web Server versions v1.3.6 or greater
• Common Gateway Interface (CGI)
• A CD-ROM drive
Note If you plan to use the ClusterCATS software that is included with
ColdFusion to cluster your Solaris servers, see “Sun Solaris system
requirements for ClusterCATS Server” on page 162. The ClusterCATS
system requirements may impact your overall environment
requirements.
Chapter 1: Installing and Configuring ColdFusion 5
Linux
To install and use ColdFusion Server 4.5 Express, Professional, or Enterprise edition on
Linux, your system must meet the following minimum requirements:
• RedHat operating system v6.0 or 6.1
(with glibc v2.1, gcc/egcs libstdc++ v2.9, and v2.2 kernel)
• Intel Pentium 200 Mhz or greater
• 64 MB of RAM (128 MB recommended)
• 50 MB of free disk space
• Specific Web servers that work with ColdFusion on the Linux platform include:
• Apache Web Server versions v1.3.6 or greater
• A CD-ROM drive
Note If you plan to use the ClusterCATS software that is included with
ColdFusion to cluster your Linux servers, see “Linux system requirements
for ClusterCATS Server” on page 162. The ClusterCATS system
requirements may impact your overall environment requirements.
Installing ColdFusion on Windows
This section addresses the following topics about installing ColdFusion on Windows:
• “Verifying that a Web server is running” on page 5
• “Installing ColdFusion” on page 6
• “Uninstalling ColdFusion” on page 11
• “Performing Windows-specific configurations” on page 11
Verifying that a Web server is running
Before installing ColdFusion, check that your Web server is installed and running. You
can do this by loading a page in your Web browser using the HTTP protocol.
To check that your Web server is running:
Do one of the following actions:
• Enter the URL for a Web page or site in your browser’s Address field and press
Enter.
For example, if the file myindex.htm is in your Web document root directory, load
the page in your browser using the localhost URL:
http://127.0.0.1/myindex.htm
If your Web server is not running, you’ll receive an error message.
6 Administering ColdFusion Server
• You can also check the Services icon in the Windows Control Panel or open your
Web server administration utility to determine if your Web server is started or
stopped.
Installing ColdFusion
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. Then follow the install procedure below, skipping step 2.
We recommend that you close all open applications before running the Setup
program. This will ensure proper installation of the ODBC 3.0 drivers.
Note Because of a problem in the way Verity handles indexing, ColdFusion
must be installed to a directory path that contains no spaces in the path
name. This restriction is necessary so that ColdFusion can properly
access Verity collections.
To install ColdFusion on Windows:
1. Log in to your system using the administrator’s account or an account that is part
of the Administrator’s group.
2. Insert the ColdFusion Server v4.5 CD into your CD drive or access it from your
network jukebox (Enterprise users).
3. Click Start>Run to display the Run dialog box.
4. Enter the path where the ColdFusion Setup.exe resides or click Browse to drill
down to it.
5. Click OK.
The ColdFusion v4.5 Setup program starts and displays the ColdFusion Setup
Welcome page.
Chapter 1: Installing and Configuring ColdFusion 7
6. Click Next in the Welcome and Software License Agreement dialog boxes.
The User Information dialog box appears after the Software License Agreement
dialog box.
7. Enter your name, company, and ColdFusion serial number in the User
Information dialog box and click Next.
Note You’ll find your ColdFusion serial number on the product box.
The Choose Destination Directory dialog box appears next.
8 Administering ColdFusion Server
8. Accept or change the default destination folder and click Next.
The Select Web Server dialog box appears.
If your Web server is already installed, the ColdFusion Setup program will
automatically detect it.
9. If your Web server is not one of the ones listed, select the Other option and click
Next. Otherwise, just click Next.
The Select Web Server Document Directory dialog box appears next.
Chapter 1: Installing and Configuring ColdFusion 9
10. Either accept the Web server’s default document directory or enter a different
location for the default directory and click Next.
Note ColdFusion documentation and example code are installed in a
subdirectory below the Web server’s document directory.
The Select Install Options dialog box appears.
11. Accept the default install options or select those that you want and click Next.
Note By default, Load Balancing and High Availability and Advanced
Security Services are not installed. However, you can install either of
them later by re-running the Setup program. For explicit instructions
about installing the Load Balancing and High Availability services,
10 Administering ColdFusion Server
see “Installing ClusterCATS” on page 185. To install Advanced
Security, see “Installing Advanced Security” on page 298.
The Select Administrator Password dialog box appears next.
12. Enter a password you will use to access the ColdFusion Administrator in the
Password and Confirm fields and press Next.
The Select ColdFusion Studio Password dialog box appears.
13. Enter a password in the Password and Confirm fields that you will use to access
the ColdFusion Server when developing applications with ColdFusion Studio and
press Next.
Chapter 1: Installing and Configuring ColdFusion 11
14. Click Next or OK in the remaining dialog boxes to begin copying the ColdFusion
files to the server.
If your system has a previous version of ColdFusion, the setup wizard replaces
ColdFusion program files but does not remove or change any existing application
pages (template files) that may be present.
ColdFusion updates the Windows registry and the ColdFusion services start. If you
chose to install the ODBC Desktop Drivers, a warning screen appears. Close all
open applications before installing the drivers.
15. Click Finish to complete the installation.
16. To verify your installation, click Start>Programs>ColdFusion Server
4.5>ColdFusion Administrator to open the ColdFusion Administrator.
Alternatively, you can enter the following URL into your browser:
http://
where hostname is the name of the server hosting ColdFusion.
If ColdFusion is not properly installed after following the steps above, please call
Allaire Customer Service for assistance.
hostname
/CFIDE/Administrator/index.cfm
Uninstalling ColdFusion
If you need to remove an installed version of ColdFusion, run the ColdFusion Uninstall
Utility to make sure all of the program files and registry settings are removed
completely from your system.
To uninstall ColdFuison:
1. Click Start>Programs>ColdFusion Server>Uninstall ColdFusion.
The InstallShield Uninstall program starts and displays the following confirmation
dialog box.
2. Click Yes to delete all ColdFusion program files and components from your
system. Otherwise, click No to abort the uninstall.
If you clicked Yes, the InstallShield Uninstall program automatically removes
ColdFusion program files and registry settings from your system.
Performing Windows-specific configurations
After installing ColdFusion, you may need to perform the following configurations:
12 Administering ColdFusion Server
• “Configuring the Apache Web server for ColdFusion” on page 12
• “Changing the ColdFusion user account” on page 12
Configuring the Apache Web server for ColdFusion
To configure the Apache Web Server v1.3.6 for use with ColdFusion, you need to:
• Get a copy of the Apache Web server from the Apache HTTP Server Project Web
site at http://www.apache.org/.
• Read the Apache documentation on support for Win32 platforms: http://
www.apache.org/docs/windows.html.
• Copy an Apache module to your Apache modules directory.
• Add a line to a configuration file.
The following procedure assumes that your Apache Web server is installed in
c:\Apache.
To configure Apache for ColdFusion:
1. If a version of the Apache Web server is running, shut down the Web server.
2. Copy the
modules directory.
For example: c:\Apache\modules\ApacheModuleColdFusion.dll.
3. Edit the Apache configuration file (
following line:
LoadModule coldfusion_module
4. Restart the Apache Web server.
cfusion\bin\ApacheModuleColdFusion.dll module to your Apache
c:\Apache\conf\httpd.conf) to contain the
modules/ApacheModuleColdFusion.dll
Changing the ColdFusion user account
By default, ColdFusion runs under the host System account. However, ColdFusion
application pages may not have the access rights needed to interact with remote data
sources, other application pages, COM objects, and so on when running under this
account. Therefore, you may need to run ColdFusion under a specific account that
provides the necessary access rights.
To change the ColdFusion user account:
1. Click Start>Settings>Control Panel>Services.
The Services dialog box appears.
Chapter 1: Installing and Configuring ColdFusion 13
2. Select the ColdFusion Application Server service and click Startup.
The Service Properties dialog box appears.
Use this dialog to set startup options for the ColdFusion Application Server
service.
3. In the Log On As section, click the This Account radio button and enter the
appropriate account information.
Installing ColdFusion on Solaris
ColdFusion is distributed as a Solaris package. You can use a number of Solaris
package utilities, such as
package file, as well as any other package files on your system.
This section addresses the following topics related to installing ColdFusion on Solaris:
pkgadd, pkgrm, and pkginfo to manage the ColdFusion
14 Administering ColdFusion Server
• “Installing ColdFusion” on page 14
• “Upgrading from a previous release of ColdFuison” on page 16
• “Uninstalling ColdFusion” on page 16
• “Configuring Web servers for Solaris” on page 16
• “Using scripts to start and stop ColdFusion manually” on page 22
Installing ColdFusion
Before installing ColdFusion please note the following considerations:
• 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 location you downloaded ColdFusion to for references
to the CD.
• ColdFusion requires Solaris 2.5.1 or higher.
• You must be logged in as root to run the
• There are three versions of the Netscape NSAPI plug-in. The installation script
will ask you which version of Netscape you are running if you choose to
automatically configure a Netscape server.
• By default the package file installs ColdFusion into the /opt directory. If you
want to install ColdFusion into a different directory, you must create that
directory before running the pkgadd utility.
• Note the location and version number of your installed Web server. The
utility prompts you for this information.
pkgadd utility.
pkgadd
To install ColdFusion on Solaris:
1. Log in as root.
2. Load the ColdFusion CD-ROM into your CD drive.
3. Mount the CD-ROM on
If the Solaris Volume Manager is active, you won’t need to mount the CD.
4. Type pkgadd -d /cdrom/cdrom0 to start the installation process.
5. Enter
cfusion at the prompt and press Enter to select the ColdFusion package.
Alternatively, you can just press Enter to accept the default (
the only package available.
6. Enter the ColdFusion registration ID (serial number) when prompted.
You’ll find your ColdFusion registration ID on the product box.
7. Enter the name of the directory in which you want to install ColdFusion or accept
the default directory.
/opt is the default installation directory.
/cdrom/cdrom0 if necessary.
All), as ColdFusion is
Chapter 1: Installing and Configuring ColdFusion 15
Note If you specified a directory other than the default, the installation
script will create a symbolic link from
you installed ColdFusion.
8. Enter the name of the Web server you are running and press Enter or just press
Enter if you are running the default Web server (Netscape Enterprise Server).
9. Press Enter to have the installation program automatically configure the Web
server.
The program loads the necessary plug-in for Netscape or module for Apache 1.3.x
Web se rvers.
10. When prompted with whether to install ClusterCATS, press Enter to do so.
11. If you want the server on which you are installing ClusterCATS to be able to
assume the IP address and HTTP traffic of a failed server in the cluster, press Enter
to configure this server with failover services. Otherwise, enter
Typically, you want all of the servers in your cluster to be configured for failover,
particularly if all of the servers have the same processing capacity. However, if you
have a mixed server environment with some high capacity servers and several
lower capacity servers, you may not want the less powerful machines to accept the
additional load of unavailable servers in the cluster.
12. Enter your Web server’s document root directory and press Enter.
The default document root directory is determined by the Web server you are
using.
13. When asked if you want to install Advanced Security, enter
You can install Advanced Security at a later time by re-running the pkgadd utility.
14. Enter the password you want to use to access the ColdFusion Administrator,
which allows you to configure and modify settings for the ColdFusion Server.
You’ll be asked to re-enter the password for verification purposes.
15. Enter the password you want to use to connect to ColdFusion Server when
developing applications with ColdFusion Studio.
You’ll be asked to re-enter the password for verification purposes.
16. Press Enter to install the ColdFusion documentation.
The documentation is installed in the /
cfdocs directory, which resides under the
Web root directory.
17. Enter the user name under which ColdFusion will run or press Enter to run under
the default user name (
nobody).
18. Press Enter to begin the installation.
When the installation is complete, a shell script restarts the Web server and starts
ColdFusion services. If the ColdFusion services are not started automatically, you can
start them manually using the ColdFusion start-up script, which is found in the /etc/
directory. See “Using scripts to start and stop ColdFusion manually” on
inet.d
page 22.
/opt/coldfusion to wherever
n and press Enter.
n and press Enter.
16 Administering ColdFusion Server
Upgrading from a previous release of ColdFuison
When upgrading from an earlier release of ColdFusion on Solaris, you may need to edit
the package installation defaults file before running the pkgadd utility. The package
installation defaults file is located in the following location:
/var/sadm/install/admin/default
This file controls the behavior of the Solaris packaging commands. The value of the
instance setting may need to be changed from
the value of the instance to
overwritten by the new version.
After modifying the package installation defaults file, install your new release of
ColdFusion following the steps in “Installing ColdFusion” on page 14.
overwrite allows the existing version of ColdFusion to be
quit or unique to overwrite. Setting
Uninstalling ColdFusion
Use the pkgrm utility to remove an installed version of ColdFusion.
Note The uninstall script removes your odbc.ini file and all Verity collections.
Therefore, you may want to preserve these items by saving them to a new
location before uninstalling ColdFusion.
To uninstall ColdFusion:
1. Log in as root.
2. Enter the following command at the prompt:
pkgrm cfusion
ColdFusion is deleted from your server.
Configuring Web servers for Solaris
If you run Netscape or Apache Web servers in conjunction with ColdFusion on Solaris,
you must perform several Web server configurations for ColdFusion to work properly.
This section addresses the following topics:
• “Configuring the Netscape Web server” on page 16
• “Configuring the Apache Web Server” on page 20
Configuring the Netscape Web server
The ColdFusion NSAPI plug-in has been tested with Netscape Enterprise Server
versions 2.01, 3.0, and 3.5.1, and the Netscape FastTrack Web Server 2.01. The
installation script prompts you to automatically configure either of these servers. If
you do not want the script to configure the Netscape plug-in, you can configure it
manually. See “To configure the Netscape plugin:” on page 17.
Chapter 1: Installing and Configuring ColdFusion 17
Choosing the right plug-in version
Netscape plug-ins for ColdFusion are installed in the <installdir>/coldfusion/
webserver/nsapi
directory. Use the following table to select the proper plug-in file.
ColdFusion Plugins for Netscape
Use this Plugin With this Netscape Server Product With this Version
of Solaris
coldfusion2x.so Netscape Enterprise Server 2.01
Netscape FastTrack 2.01
coldfusion3x.so Netscape SuiteSpot Enterprise Server 3.0
2.51 or higher
2.6
2.51
Netscape FastTrack Server 3.0
Netscape Enterprise Server 3.51
coldfusion35.so Netscape Enterprise Server 3.51 2.6 or higher
Note The Netscape 3.0 servers will not work on Solaris 2.6 with ColdFusion.
You should use version 3.51, which Netscape certifies for use on Solaris
2.6.
The following procedure assumes you have the Enterprise 3.0 server installed in /usr/
netscape/suitespot
To configure the Netscape plugin:
1. Copy the appropriate plugin (see table above) to a directory in your server
directories. Name it
mkdir /usr/netscape/suitespot/plugins/coldfusion
cp /opt/coldfusion/webserver/nsapi/coldfusion3x.so \
/usr/netscape/suitespot/plugins/coldfusion/coldfusion.so
2. Edit the /usr/netscape/suitespot/https-smurf/config/mime.types file to add
a new ColdFusion type. Add the line:
type=magnus-internal/cold-fusion exts=cfm,dbm
3. Edit the /usr/netscape/suitespot/https-surf/config/obj.conf file to add
new service and init directives. Add all of the following syntax on one line:
Init fn="load-modules" shlib="/usr/netscape/suitespot/
plugins/coldfusion/coldfusion.so" funcs="DoCFRequest"
4. Add the following line in the default Object:
Service fn="DoCFRequest" method="(GET|POST)"
type="magnus-internal/cold-fusion"
5. Stop and restart the Web server.
on the machine named smurf.
coldfusion.so.
18 Administering ColdFusion Server
If you run the Netscape Server Manager, Netscape’s browser-based administrator,
you may get a warning about edits to the Netscape configuration files. This is
normal. Follow the instructions and click on the Apply button to reload the new
configuration files.
6. Test the setup by accessing the ColdFusion Administrator by entering the
following URL in your browser:
http://localhost/CFIDE/administrator/index.cfm
If your server does not restart, check to make sure the pathname for the plug-in
you specified in the
obj.conf file is correct for your installation and that it is on a
single line.
Updates made to Netscape configuration files after installing ClusterCATS
If you select the ClusterCATS load balancing and high availability installation option
when installing ColdFusion, the ClusterCATS installation process updates the
Netscape magnus.conf and obj.conf configuration files.
Note The sections that the ClusterCATS installation script modifies are
enclosed by Start BT and End BT comment blocks.
obj.conf
# Netscape Communications Corporation - obj.conf
# You can edit this file, but comments and formatting changes
# might be lost when the admin server makes changes.
#Start BT: Add Init routines and Entry points
Init fn=load-modules shlib="<ClusterCATS Install Dir>/btcats/
teserver.so"
funcs="btcats_server_init,btcats_nsapi_AuthTrans,btcats_nsapi_NameTrans,
btcats_ErrorFixup"
Init fnInit fn="btcats_server_init"
#End BT:
Init fn="flex-init" access="/local1/netscape/https-skagway/logs/access"
format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
\"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req>srvhdrs.content-length%"
Init fn="load-types" mime-types="mime.types"
<Object name="default">
#Start BT: Entry Points
NameTrans fn=btcats_nsapi_NameTrans
AuthTrans fn=btcats_nsapi_AuthTrans
Error fn=btcats_ErrorFixup reason="BrightTiger"
#End BT:
NameTrans fn="pfx2dir" from="/ns-icons" dir="/local1/netscape/ns-icons"
NameTrans fn="pfx2dir" from="/mc-icons" dir="/local1/netscape/ns-icons"
NameTrans fn="document-root" address="192.168.0.220" root="/local1/
netscape/root-wrangle"
NameTrans fn="document-root" address="192.168.0.173" root="/local1/
netscape/root-kodiak"
Chapter 1: Installing and Configuring ColdFusion 19
NameTrans fn="document-root" root="/local1/netscape/root-skagway"
PathCheck fn="unix-uri-clean"
PathCheck fn="check-acl" acl="default"
PathCheck fn="find-pathinfo"
PathCheck fn="find-index" index-names="index.html,home.html"
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
Service method="(GET|HEAD)" type="magnus-internal/imagemap"
fn="imagemap"
Service method="(GET|HEAD)" type="magnus-internal/directory" fn="indexcommon"
Service method="(GET|HEAD)" type="*~magnus-internal/*" fn="send-file"
AddLog fn="flex-log" name="access"
</Object>
<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>
magnus.conf
ServerRoot /local1/netscape/https-skagway
ServerID https-skagway
ServerName skagway.brighttiger.com
#Start BT: Remove Address line from magnus.conf. This will cause
#the Netscape Server to listen on INADDR_ANY
#Address 192.168.0.24
#End BT:
Port 80
LoadObjects obj.conf
RootObject default
ErrorLog /local1/netscape/https-skagway/logs/errors
PidLog /local1/netscape/https-skagway/logs/pid
User root
MtaHost localhost
NntpHost name-of-news-server
DNS off
Security off
Ciphers +rc4,+rc4export,+rc2,+rc2export,+des,+desede3
SSL3Ciphers
+rsa_rc4_128_md5,+rsa_3des_sha,+rsa_des_sha,+rsa_rc4_40_md5,+rsa_rc2_40_
md5,-rsa_null_md5
ACLFile /local1/netscape/httpacl/generated.https-skagway.acl
ClientLanguage en
AdminLanguage en
DefaultLanguage en
AcceptLanguage off
RqThrottle 128
20 Administering ColdFusion Server
Configuring the Apache Web Server
ColdFusion has been tested with Apache version 1.2.x and 1.3. To obtain Apache free of
charge, go to the Apache Web site at
You can build the ColdFusion module into your Apache Web server binary. This
method is efficient because the server does not have to start a new process for every
ColdFusion request. This section describes:
• “Adding the ColdFusion module to Apache 1.2.x” on page 20
• “Adding the ColdFusion module to Apache 1.3.x” on page 21
Note If necessary, consult the Apache ReadMe file for additional information
(README.Apache)
Adding the ColdFusion module to Apache 1.2.x
The ColdFusion module can be found in the installation directory (usually /opt) under
coldfusion/webserver/apache directory.
the
The following procedure assumes that your Apache Web server is installed in
/usr/local/etc/httpd and you installed ColdFusion in /opt.
To add the ColdFusion module:
1. Copy the module (mod_coldfusion.a) to your Apache source directory.
cp /opt/coldfusion/webserver/apache/mod_coldfusion.a \
/usr/local/etc/httpd/src/mod_coldfusion.a
2. Edit the /usr/local/etc/httpd/src/Configuration file to contain the following
line:
Module coldfusion_module mod_coldfusion.a
3. If you are using the Sun C compiler, edit the EXTRA_LIBS= line to include the C++
library:
EXTRA_LIBS=-lC
If you are using the gcc compiler, you should add the absolute path of the C++
library to this line. You should include the version number of the library and use
the highest one available.
For example:
EXTRA_LIBS=/usr/lib/libC.run.so.1
4. Run the Configure script to regenerate the configuration.
./Configure
5. Run make to build a new Apache httpd executable.
6. Install the new httpd executable in your installation directory and restart httpd.
You should now be able to access the ColdFusion Administrator with the following
URL:
http://localhost/CFIDE/administrator/index.cfm
http://www.apache.org.
Chapter 1: Installing and Configuring ColdFusion 21
Adding the ColdFusion module to Apache 1.3.x
You can find the ColdFusion module in the installation directory (usually /opt) under
the
coldfusion/webserver/apache directory. The pre-built module shipped with
ColdFusion 4.5 is built with Apache 1.3.6. This module will not work with earlier
versions of Apache 1.3.x, and it may not work with later versions if the Apache Group
changes the MODULE_MAGIC_NUMBER_MAJOR (src src/include/ap_mmn.h in the
Apache source).
Note The module has been tested with Apache 1.3.9.
If you have a C compiler (gcc or SUN cc) available, you can build a version of
mod_coldfusion.so which should work with any versionof Apache 1.3.
To configure and add the ColdFusion module:
In order for the Apache httpd to load the ColdFusion module at startup time, you must
have configured the
necessary, consult the Apache documentation for details (README.DSO).
Configure this module into the Apache build by running the following command:
$ ./configure --enable-module=so <other apache options>
$ make
$ make install
If you are using gcc to compile Apache, you should include the following environment
variables for configure:
$ env LIBS=/usr/lib/libC.so.5 CFLAGS=-fPIC \
./configure --enable-module=so <other apache options>
Once you have mod_so configured in to your Apache binary, the simplest way to
configure the ColdFusion module is to use the apxs program that is included in the
Apache distribution. It is installed by default in <apachedir>/apache/bin. This is a
perl script, so you must have perl installed on your system. Perl is freely available at
http://www.perl.com.
mod_so module. This module is not built into Apache by default. If
To use the apxs program:
1. Ensure that perl is available in /usr/local/bin/perl.
Also, make sure a C compiler is in your PATH.
2. Add the
csh:
set path=($path /usr/ccs/bin /usr/local/apache/bin)
sh/ksh:
PATH=$PATH:/usr/ccs/bin:/usr/local/apache/bin
export PATH
3. Change to the apache/src directory in the ColdFusion installation.
cd /opt/coldfusion/webserver/apache/src
apache/bin directory to your path:
22 Administering ColdFusion Server
4. Run the apxs command to build mod_coldfusion.so by entering the following
command:
make
5. Run the apxs command to add the module to the Apache configuration by
entering the following command:
make install
6. Restart your Apache server by entering the following command:
apachectl restart
To configure the Apache module that Allaire provides:
1. Copy the ColdFusion module to the Apache modules directory:
cp /opt/coldfusion/webserver/apache/mod_coldfusion.so \ /usr/local/
apache/libexec
2. Edit your httpd.conf file to include the following directive:
LoadModule coldfusion_module libexec/mod_coldfusion.so
Note If you have a ClearModuleList directive in httpd.conf, you will need
to add the following directive to the AddModule list as stated by the
comments in the httpd.conf file: AddModule mod_coldfusion.c
3. Restart apache.
You should now be able to access the ColdFusion Administrator with the following
URL:
http://localhost/CFIDE/administrator/index.cfm
Using scripts to start and stop ColdFusion manually
ColdFusion provides two scripts for starting and stopping ColdFusion processes
manually:
<installdir>/colfusion/bin/start
<installdir>/colfusion/bin/stop
Note You must be logged in with root privileges to run these scripts.
The ColdFusion installation scripts also installs the following scripts to start and stop
ColdFusion during system boot and shutdown:
/etc/init.d/coldfusion
/etc/rc1.d/K19coldfusion
/etc/rc3.d/S25coldfusion
Chapter 1: Installing and Configuring ColdFusion 23
ColdFusion runs the following processes on the system:
•
cfexec — Starts/stops the other processes and manages page scheduling
cfserver — The application server process
•
•
cfrdsservice — Provides system support for the Administrator as well as
security and debugging services for ColdFusion Studio
The following processes also run if you’ve installed the ClusterCATS for ColdFusion
option:
• ipaliasd — Provides IP failover capability for ColdFusion Server
•
reqmgr — Processes ClusterCATS operations as root
Installing ColdFusion on Linux
Allaire is pleased to offer ColdFusion on the popular Linux platform. This section
addresses the following topics about installing ColdFusion on Linux:
• “Installing ColdFusion” on page 23
• “Uninstalling ColdFusion” on page 25
Installing ColdFusion
Before installing ColdFusion on Linux, please note the following considerations:
• 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 as root.
• By default the installation script installs ColdFusion into the
you want to install ColdFusion into a different directory, you must create that
directory before running the installation
create a symbolic link from
ColdFusion.
/opt/coldfusion to wherever you installed
script. The installation script will
/opt directory. If
24 Administering ColdFusion Server
To install ColdFusion on Linux:
1. Log in as root.
2. Load the ColdFusion CD-ROM into your CD drive.
3. Mount the CD-ROM on
4. Change directories to the
/mnt/cdrom if necessary.
cf/linux directory on the CD.
5. Run the ColdFusion installation script by entering the following command:
./cfinstall
The ColdFusion installation script starts.
6. Enter your ColdFusion registration ID and press Enter.
You can find the registration ID on the product box.
7. Enter the name of the directory in which you want to install ColdFusion or accept
the default directory.
/opt is the default installation directory.
Note If you specified a directory other than the default, the installation
script will create a symbolic link from
you installed ColdFusion.
8. Enter the name of the Web server you are running and press Enter or just press
Enter if you are running the default Web server (Apache).
9. Press Enter to let the installation script automatically configure your Web server
for ColdFusion.
The program loads the necessary plug-in for Netscape or module for Apache 1.3.x
Web se rvers.
10. Enter the path of your Web server’s document root directory and press Enter.
The default document root directory is home/httpd/html.
11. Press enter to install the ColdFusion documentation below your Web server’s
document root directory.
The documentation is installed in the /
cfdocs directory, which resides under the
Web root directory.
12. Enter the password you want to use to access the ColdFusion Administrator,
which allows you to configure and modify settings for the ColdFusion Server.
You’ll be asked to re-enter the password for verification purposes.
13. Enter the password you want to use to connect to ColdFusion Server when
developing applications with ColdFusion Studio.
You’ll be asked to re-enter the password for verification purposes.
/opt/coldfusion to wherever
Chapter 1: Installing and Configuring ColdFusion 25
14. Enter the user name under which ColdFusion will run or press Enter to run under
the default user name (
nobody).
Note This user account must be a valid, existing account.
15. If you want to install ClusterCATS at this time, press Enter. Otherwise, enter
press Enter to continue.
If you do not install ClusterCATS now, you can do so later by running the
ClusterCATS installation script on its own. See “Installing ClusterCATS” on
page 185.
16. Press Enter to have the installation script begin copying program files to your
server and making the configurations you specified.
Note If you elected to install ClusterCATS, the ColdFusion installation script
runs first, followed by the ClusterCATS installation script. The
ClusterCATS installation script will prompt you with additional questions
about your Web server configuration.
When the installation is complete, a shell script restarts the Web server and starts
ColdFusion services.
Uninstalling ColdFusion
Use the remove utility to delete an installed version of ColdFusion by doing the
following:
1. Log in as root.
2. Change to the following directory on your server:
/opt/coldfusion/uninstall/cfremove
Note Step 2 assumes you originally installed ColdFusion to the default
installation directory (
directory other than the default directory, substitute its name in step
2 accordingly.
/opt). If you installed ColdFusion to a
n and
3. Enter the following command at the prompt:
./cfremove
ColdFusion is deleted from your server.
26 Administering ColdFusion Server
C HAPTER 2
Chapter 2 Introduction to ColdFusion
Server
This chapter provides an overview of ColdFusion Server and describes how to access
the ColdFusion Administrator pages.
Contents
• Overview of Administering ColdFusion ......................................................... 28
• Summary of Administrative Tasks .................................................................. 29
• The ColdFusion Administrator ....................................................................... 30
• ColdFusion Services on Windows NT............................................................. 32
• ColdFusion Processes on Solaris..................................................................... 33
• Starting and Stopping ColdFusion.................................................................. 33
28 Administering ColdFusion Server
Overview of Administering ColdFusion
The ColdFusion Administrator is the administrative interface of the ColdFusion Server.
ColdFusion Server is the component of the overall ColdFusion Web application
development system that processes ColdFusion application pages and returns HTML
pages to Web clients.
The Administrator provides a browser-based interface allowing you to manage server
performance, add and configure ColdFusion data sources, schedule pages, manage log
files, and so on. For any ColdFusion development project, some level of administration
is generally necessary to set up ColdFusion Server for your application.
Accessing the Administrator
All administrative operations are performed using the ColdFusion Administrator,
which you can launch from the ColdFusion 4.0 program group in Windows, or by
opening the Administrator URL in your browser. If ColdFusion Server is installed
locally, you can open the following URL:
http://127.0.0.1/CFIDE/Administrator/index.cfm
To access the Administrator remotely, you open the following URL:
http://
Where hostname is the name of the system on which ColdFusion Server is installed. If
you are using ColdFusion Administrator security, you will be prompted for a password.
If your Web server is providing security, access to the Administrator pages is governed
by the permissions defined in your Web server.
hostname
/CFIDE/Administrator/index.cfm
Note The Administrator’s URL is case sensitive on Solaris and should be used
as shown.
Chapter 2: Introduction to ColdFusion Server 29
Initial ColdFusion administration tasks
Immediately after installing ColdFusion Server, you’ll probably want to perform some
of the following configuration tasks:
Initial Adminitration Tasks
If necessary, configure your Web server for ColdFusion
If you are using Netscape or Apache Web ser vers on Solaris, you’ll need to perform some
initial configuration tasks for ColdFusion.
For more information, see Chapter 1, “Installing and Configuring ColdFusion,” on page 1.
Add, configure, and verify ColdFusion data sources
You use the Administrator to create ColdFusion data sources for your applications. You
can configure ODBC data sources or employ a native database driver to access your
Oracle or Sybase databases (Enterprise Edition only).
For more information about data sources, see Chapter 4, “Managing Data Sources,” on
page 77.
Configure Admininstrator email
ColdFusion error pages include an email address link to the ColdFusion administrator.
You’ll also need to define a default mail server hostname. Defining the email address of
the administrator allows users of your ColdFusion applications to report errors they may
encounter. You could, for example, use a messaging service to receive email by pager
alerting you to any errors encountered in a ColdFusion application.
For more information, see Chapter 3, “Configuring ColdFusion Server,” on page 37.
Configure ColdFusion log file options
ColdFusion produces a number of different log files you can use to monitor server errors
and activity. In addition, you can log all email messages sent by ColdFusion to a log file.
For more information, see Chapter 3, “Configuring ColdFusion Server,” on page 37.
Summary of Administrative Tasks
The things you may need to do to set up and run the ColdFusion Server fall into several
categories:
• Installing and configuring ColdFusion
• Managing data sources
• Managing server performance and resources
• Managing security for users, applications, and server resources
30 Administering ColdFusion Server
You can learn more about each of these areas of ColdFusion administration by
referring to the information in the following table:
Information about ColdFusion Administration
Subject Where to find it
Installing ColdFusion See Chapter 1, “Installing and Configuring
ColdFusion,” on page 1.
Configuring ColdFusion data sources Chapter 4, “Managing Data Sources,” on
Native database drivers for Oracle and
Sybase databases
Configuring OLE-DB data sources
Setting debugging options Chapter 3, “Configuring ColdFusion Server,”
Configuring Administrator email
Managing log files
Clustering and load-balancing Chapter 6, “Creating Scalable and Highly
page 77.
on page 37.
Available Web Sites,” on page 129.
Using CGI with ColdFusion Chapter 7, “Using CGI with ColdFusion,” on
Configuring basic security for remote
development and administration
Configuring Advanced security for
ColdFusion resources
The ColdFusion Administrator
The Administrator is a Web application you use to configure the ColdFusion Server
and to set various server options. The Administrator includes options for managing a
wide range of server settings.
You can open the Administrator by selecting the ColdFusion Administrator icon in the
ColdFusion 4.0 program group (Windows) or by opening the following URL:
http://
Where hostname is the name of the server where ColdFusion is installed.
hostname
/CFIDE/Administrator/index.cfm
page 269.
Chapter 9, “Configuring Basic Security,” on
page 283.
Chapter 10, “Configuring Advanced
Security,” on page 289.
Chapter 2: Introduction to ColdFusion Server 31
The following table describes the purpose of each category in the Administrator.
ColdFusion Administrator Options
Category Description
Server Includes options for tuning server performance, as well as:
• Configuring Administrator and ColdFusion Studio passwords
and security options
• Enabling and configuring ColdFusion application, session, and
client variables
• Mapping directories
• ColdFusion version information
Data Sources Use to configure ColdFusion data sources, including:
• Native database drivers for Oracle and Sybase databases
• ODBC data sources
• Verifying a ColdFusion data source
Extensions Includes options for registering Java applets and CFX tags: custom
tags written in C++.
Logging You use the Logging pages to configure a ColdFusion Administrator
email address, and to:
• Specify a directory for ColdFusion log files
• Set mail logging options
• View ColdFusion log files
Automated
tasks
Miscellaneous Use the Mail page to specify a default mail server hostname as well as
The Automated tasks pages provide options for:
• Adding new scheduled tasks
• Specifying how often ColdFusion checks for new scheduled
tasks to execute
other mail-related configuration options.
The debugging page alows you to enable and configure error
message output for ColdFusion pages.
The Verity page is for managing Verity search indexes.
The Source Control page allows you to setup and configure server-
side source control options.
32 Administering ColdFusion Server
ColdFusion Services on Windows NT
By default, ColdFusion employs four separate services under Windows NT. The
following table explains the purpose of each one.
ColdFusion Services on Windows NT
Service Purpose
Bright Tiger Service Manages ColdFusion Server load-balancing and failover.
For more information about clustering, which enables loadbalancing and failover in ColdFusion, see Chapter 6,
“Creating Scalable and Highly Available Web Sites,” on page
129.
ColdFusion Application
Server
ColdFusion Executive Polls the ColdFusion Application Server service and
ColdFusion RDS The ColdFusion Remote Development Service provides
SiteMinder
Authentication Service
SiteMinder Authorization
Service
You can use the Windows NT Services Control Panel to view and manage these and
other Windows NT services.
The main ColdFusion Server service. ColdFusion pages
cannot be processed if this service is not running.
automatically restarts the ColdFusion Application Server if it
is not running.
security, directory and file browsing, and debugging
services for ColdFusion Studio.
Only present if you chose the advanced security option
during ColdFusion setup. Provides user authentication
services for advanced security.
Only present if you chose the advanced security option
during ColdFusion setup. Provides access authorization
services for advanced security.
Chapter 2: Introduction to ColdFusion Server 33
ColdFusion Processes on Solaris
ColdFusion runs these processes on the system:
cfexec - Starts/stops the other processes and manages page scheduling
•
•
cfserver - The application server process
•
cfrdsservice - Provides system support for the Administrator
ipaliasd - Provides IP failover capability for ColdFusion Server
•
In addition, the
registry database. This process must be running (as the root user) in order for
ColdFusion to function. The start script will start this process if it isn’t running (such as
during system startup). The stop script does not stop the registry process.
windu_registryd40 process provides an emulation of the Windows
Starting and Stopping ColdFusion
Normally, ColdFusion services are started during ColdFusion setup and configured to
run whenever you start your system. However, if you need to start ColdFusion services,
click the Start-Stop icon in the ColdFusion program group. If a password is configured
for the Administrator, you will be prompted to enter a password before you can start or
stop ColdFusion services.
34 Administering ColdFusion Server
Windows NT
During setup, ColdFusion is installed as a series of system services in Windows NT.
Ordinarily, ColdFusion is launched at startup time. To manage how the services are
run, use the Services Control Panel in Windows NT.
To prevent ColdFusion from running at startup:
1. Open the Services Control Panel.
2. Select the ColdFusion Application Server service.
3. Click Stop to halt the service immediately, click Startup to configure startup
options for ColdFusion.
Solaris
Two scripts are provided to start and stop the ColdFusion processes:
<installdir>/coldfusion/bin/start
<installdir>/coldfusion/bin/stop
These scripts can only be run as root. In addition, the ColdFusion installation also
installs the following scripts to start and stop ColdFusion during system boot and
shutdown:
/etc/init.d/coldfusion
/etc/rc1.d/K19coldfusion
/etc/rc3.d/S25coldfusion
Windows 95 and Windows 98
Since Windows 95 and Windows 98 do not have a services architecture, ColdFusion
must be run as an ordinary executable.
Chapter 2: Introduction to ColdFusion Server 35
When ColdFusion is running in Windows 95 or 98, two icons appear in the system tray:
To halt the ColdFusion service or to access the ColdFusion Administrator, right mouse
click the IDE service icon.
To run ColdFusion at startup, place a shortcut for the ColdFusion icon in the Startup
program group.
Stopping ColdFusion
Stopping ColdFusion services may be necessary in the following instances:
• To install a new ODBC driver package
• To replace or upgrade your Web server software
• To upgrade or reinstall your ColdFusion program files
• To update or replace database files
The Stop/Start Services page can also be used to restart the ColdFusion Server after a
critical failure or error. The Start-Stop page is available only from the local
workstation. You can move the Start-Stop page to a directory in your Web server
document directory. If you do so, you need to make sure the file is secured using your
native Web server security.
36 Administering ColdFusion Server
C HAPTER 3
Chapter 3 Configuring ColdFusion Server
This section explains basic ColdFusion administration tasks.
Contents
• The ColdFusion Administrator ....................................................................... 39
• Starting and Stopping ColdFusion.................................................................. 41
• The Server Settings Page.................................................................................. 42
• Configuring Administrator Security ............................................................... 44
• Managing Client Variables .............................................................................. 45
• State Management and Server Clustering...................................................... 48
• Enabling External Client State Management................................................. 48
• Migrating Client Variable Data........................................................................ 50
• Enabling Application and Session Variables.................................................. 51
• Locking Variables .............................................................................................53
• ColdFusion Java Settings ................................................................................. 54
• ColdFusion Version Information .................................................................... 55
• The ColdFusion Logging Page......................................................................... 56
• Mapping Directories........................................................................................ 58
• Managing CFX tags ..........................................................................................59
• Debug Settings in the ColdFusion Administrator .........................................62
• Configuring Administrator Mail...................................................................... 63
• Indexing Data with Verity................................................................................64
• Verity Supported File Types............................................................................. 65
• Repairing, Optimizing, Purging, and Deleting Collections........................... 66
• Configuring Server-Side Source Control ........................................................ 67
38 Administering ColdFusion Server
• Using ColdFusion in a Distributed Configuration......................................... 68
Chapter 3: Configuring ColdFusion Server 39
The ColdFusion Administrator
You use the Administrator to perform a variety of administrative tasks for the
ColdFusion Server, such as adding and configuring a data source, or scheduling
application page execution, configuring security settings, and so on. During the
ColdFusion installation process, you specify an Administrator password that is used to
prevent unauthorized access to the Administrator pages.
To open the ColdFusion Administrator:
1. Double-click the ColdFusion Administrator icon in the ColdFusion program
group
or
2. Open the administrator by loading the following URL in a browser:
http://
where hostname is the name of the server hosting ColdFusion.
hostname
/CFIDE/administrator/index.cfm
Note The URL path is case-sensitive on UNIX.
Accessing the Administrator remotely
To access ColdFusion Administrator pages remotely, you load the following URL:
http://
where hostname is the name of the system on which ColdFusion is installed. If you are
using ColdFusion Administrator security, you will be prompted to enter a password. If
your Web server provides security, access to the Administrator pages is governed by the
Web server’s permissions.
hostname
/CFIDE/administrator/index.cfm
40 Administering ColdFusion Server
Once the Administrator page loads, click one of the Administrator links to work with a
specific area of the Administrator.
ColdFusion Administrator Options
Category Description
Server Includes options for tuning server performance, as well as:
• Configuring Administrator and ColdFusion Studio passwords
and security options
• Configuring cache settings
• Configuring settings that enable ColdFusion to work with Java
• Locking shared data to control simultaneous access
• Enabling and configuring ColdFusion application, session, and
client variables
• Mapping directories
• ColdFusion version information
Data Sources Configures ColdFusion data sources, including:
• Native database drivers for Oracle, Informix, DB2, and Sybase
databases
• ODBC data sources
• OLE DB data sources (Windows only)
• Verifying a ColdFusion data source
Extensions Includes options for registering Java applets and CFX tags: custom
tags written in C++.
Logging You use the Logging pages to configure a ColdFusion Administrator
email address, and to:
• Specify a directory for ColdFusion log files
• Set mail logging options
• View ColdFusion log files
Chapter 3: Configuring ColdFusion Server 41
ColdFusion Administrator Options (Continued)
Category Description
Automated
tasks
Miscellaneous • Use the Mail page to specify a default mail server hostname as
The Automated tasks pages provide options for:
• Adding new scheduled tasks
• Specifying how often ColdFusion checks for new scheduled
tasks to execute
well as other mail-related configuration options.
• The debugging page allows you to enable and configure error
message output for ColdFusion pages.
• The Verity page is for managing Verity search indexes.
• The Source Control page allows you to setup and configure
server-side source control options.
Starting and Stopping ColdFusion
Generally speaking, you should always stop and restart ColdFusion Server after
making any changes that affect a data source, connection parameter such as caching,
thread count, and so on. Specifically, you stop and restart ColdFusion services after
making any of the following changes in the Administrator:
• After changing any server settings on the Server Settings page.
• After changing the scheduled task refresh interval. This setting in the
ColdFusion Administrator determines how often ColdFusion checks for newly
scheduled tasks.
• Enabling the performance monitoring options in the ColdFusion
Administrator. This feature allows you to use the native Windows NT
performance monitor to track ColdFusion performance-related data. For more
information, see “Monitoring ColdFusion Performance” on page 52.
• Changing the user account under which ColdFusion runs.
• Changing an existing data source setting, such as Page timeout, Buffer size, or
Maintaining database connections.
Using batch files to start and stop ColdFusion (Windows)
You can use batch files in Windows NT to stop and restart ColdFusion services. The
Windows NT NET START and NET STOP commands can be used in batch files to start
and stop ColdFusion services, as in the following excerpt:
NET STOP "Cold Fusion Application Server"
NET START "Cold Fusion Application Server"
42 Administering ColdFusion Server
Batch files, as well as other executables, can be scheduled in Windows NT. Refer to
your Windows NT documentation for more information about scheduling, and
stopping and starting NT services.
Note You must be logged in with Administrator rights to execute these batch
commands.
Using scripts to start and stop ColdFusion (Solaris)
Two scripts are provided to start and stop the ColdFusion processes:
<installdir>/coldfusion/bin/start
<installdir>/coldfusion/bin/stop
Note You must be logged in with root privileges to run these scripts.
In addition, the ColdFusion installation installs the following scripts to start and stop
ColdFusion during system boot and shutdown:
/etc/init.d/coldfusion
/etc/rc1.d/K19coldfusion
/etc/rc3.d/S25coldfusion
ColdFusion runs the following processes on the system:
cfexec - Starts/stops the other processes and manages page scheduling
•
•
cfserver - The application server process
•
cfideservice - Provides system support for the Administrator
ipaliasd - Provides IP failover capability for ColdFusion Server
•
In addition, the
registry database. This process must be running (as the root user) in order for
ColdFusion to function. The start script will start this process if it isn’t running (such as
during system start-up). However, the stop script does not stop the registry process.
windu_registryd42 process provides an emulation of the Windows
The Server Settings Page
The Administrator Server Settings page contains several configuration options you can
set or enable to manage the ColdFusion server. Many of these options can significantly
Chapter 3: Configuring ColdFusion Server 43
affect server performance. Use the following table to find out about options on the
Server Settings Administrator page.
Server Settings Options
Option Description
Limit
simultaneous
requests
Timeout
requests
Restart
unresponsive
server
Enforce strict
attribute
validation
Suppress
whitespace by
default
Fast Date/Time
parsing
Use this value to limit the number of simultaneous requests for the
ColdFusion server. Once ColdFusion reaches this limit, requests are
queued up and handled in the order received.
Set a value to limit the amount of time ColdFusion waits before
terminating a request.
This option allows you to restart the ColdFusion Server service
(daemon) in the event some ColdFusion component does not
respond within the specified amount of time.
Enables strict attribute validation rules. ColdFusion tag attributes that
are not relevant to the execution of a tag will not be allowed. When
disabled, irrelevant attributes may be passed to CFML tags without
effect. Strict attribute validation improves template execution time
and can help prevent many CFML coding errors.
When checked, the engine will compress runs of spaces, tabs, and
carriage return/linefeeds into a single space. This can significantly
compact the output of a CFML template. Developers can locally
override this setting for a template (for example, to emit
preformatted data) by using the CFPROCESSINGDIRECTIVE tag.
(Solaris only) When checked, ColdFusion uses a simpler, faster Date/
Time parsing routine when evaluating expressions. Enabling this
option improves performance, but may affect backward
compatibility. This does not affect the ParseDateTime function.
Missing
Template
Handler
Site-wide Error
Handler
When changing values on this page, be sure to stop and restart ColdFusion for these
options to take affect. For more information on stopping and starting ColdFusion, see
“Starting and Stopping ColdFusion” on page 41
Lets you specify a default template to execute any time the
ColdFusion Application Server cannot find a requested template.
Lets you specify a template to execute any time the ColdFusion
Application Server encounters errors while processing a request.
44 Administering ColdFusion Server
Caching Settings
The Administrator Caching Settings page contains several configuration options you
can set or enable to cache templates, queries, and data sources.
Caching Options
Option Description
Template cache
size
Trusted cache Allows ColdFusion to use cached application pages (templates)
Limit database
connection
inactive time
Limit maximum
number of
cached queries
Use this option to specify how much memory you want to reserve for
caching ColdFusion pages. For best performance, assuming your
server has enough memory, you should set this value to the total
number of kilobytes of all your active ColdFusion pages.
without first checking to see if they’ve been changed.
Use this option to limit the amount of time ColdFusion allows a
cached dtabse connection to remain inactive. This option is ignored if
the option to maintain database connections has not been enabled
for an individual data source.
Limits the maximum number of cached queries that the server will
maintain. Cached queries allow for retrieval of result sets from
memory rather than through a database transaction. The maximum
number of cached queries allowed at any given time is 100. When this
value is reached, the oldest query is dropped from the cache and
replaced with the specified query.
Configuring Administrator Security
ColdFusion security options include two levels of security you can implement: Basic
and Advanced. With Basic Security, separate passwords secure access to the
ColdFusion Administrator, and to files, directories, and data sources from ColdFusion
Studio. Knowing these passwords gives you complete access to all resources and all
ColdFusion Administrator pages.
Advanced Security allows you to authenticate individual users and associate specific
access rights based on user login or group association. ColdFusion Advanced Security
gives you the ability to enforce security at a very granular level. For example, you can
define security domains and policies that allow you to secure specific areas of the
ColdFusion Administrator or specific ColdFusion resources, including the execution of
specific ColdFusion tags. This security framework allows you to authenticate
individual users, and, once authenticated, control access to a wide range of operations,
such as adding or deleting data sources, setting server performance options and so on.
For detailed information about configuring security options in the ColdFusion
Administrator, see the following chapters:
Chapter 3: Configuring ColdFusion Server 45
• Chapter 8, “ColdFusion Security,” on page 273 — Explains the differences
between Basic and Advanced security so you can determine which features best
suit your needs.
• Chapter 9, “Configuring Basic Security,” on page 283 — Describes how to
configure Basic security options for developing and deploying coldFusion
applications.
• Chapter 10, “Configuring Advanced Security,” on page 289 — Describes how to
configure Advanced security options for developing and deploying ColdFusion
applications.
For more information about implementing runtime security measures, refer to
Developing Web Applications with ColdFusion.
Managing Client Variables
ColdFusion includes a number of options designed to give you a great deal of flexibility
in managing client variables. Client variables in ColdFusion give you the ability to
determine the identity of a client visiting your site. Identifying clients and customizing
page content for users requires the ability to manage client state.
ColdFusion allows the following ways of managing client variables:
• Using the system Registry to store client variables
• Using browser cookies
• Using an external data source of your choice
Planning client state management
The method you choose to store client variables will depend on a number of factors.
Among the most important factors is whether your site is currently using, or will be
using server clustering to provide load balancing and fail-over support. In addition,
there are a number of other factors to consider:
Client Variable Storage
Storage Type Advantages Disadvantages
System registry • Simple implementation
• Good performance
• Registry can be exported
easily to other systems
• Server-side control
• Need to be aware of the
registry’s maximum size
limit as defined in the
System Control Panel
(Windows NT only)
• Tied to the host system:
Not practical for clustered
servers or a round-robin
DNS configuration
46 Administering ColdFusion Server
Client Variable Storage (Continued)
Storage Type Advantages Disadvantages
Browser cookies • Simple implementation
• Good performance
• Can be set to
automatically expire
• Client-side control
External
repository
• Can use existing data
source
• Portability: Not tied to a
single server
• OS portability in a mixed
environment
• Users can configure
browsers to disallow
cookies
• ColdFusion limits
individual cookie data to
4 KB
• Netscape Navigator
allows only 20 cookies
from any one host;
ColdFusion uses three
cookies to store read-only
data, leaving only 17
additional cookies
available for use
• Requires database
transaction to read/write
variables
• Somewhat more involved
to implement
Increasing maximum registry size (Windows NT)
Windows NT notifies you if your registry data is approaching the limit defined for
registry size in the System Properties dialog. If you receive this message, you can open
the System Properties dialog and increase the size of your system registry.
Chapter 3: Configuring ColdFusion Server 47
To increase maximum registry size:
1. Open the System Control Panel and click the Performance tab.
2. In the Virtual Memory group box, click the Change button to open the Virtual
Memory dialog.
3. At the bottom of the dialog, the current registry size is reported. Specify a new
maximum registry size in MB.
Checking registry size (UNIX)
Unlike Windows NT, ColdFusion for UNIX does not impose limits on the size of the
registry. However, it’s still a good idea to be aware of the size of your registry. Registry
data is stored in the following file:
<
installdir
>/coldfusion/.windu.
hostname
/windu_reg.dat
48 Administering ColdFusion Server
State Management and Server Clustering
When using ClusterCATS for ColdFusion to cluster Web servers, and you want to use
client variables, you must use an external repository to store client variables, since the
system registry, which is bound to an individual system, can’t be dynamically accessed
by any other system.
Configuring a data source in a clustering environment
Like any other ColdFusion data source, the data source you specify to store your client
variables can live anywhere on your network that is accessible to ColdFusion. When
you add a new data source to ColdFusion for storing client variables (we recommend
dedicating a data source for this purpose rather than using an existing data source) you
can enable an option for ColdFusion to automatically create the tables necessary for
storing client variables.
However, in a cluster of servers all accessing the same data source for client variables,
ColdFusion only needs to create the necessary tables once. As you add the client
variables data source to each ColdFusion Server in the cluster, you do not need to
choose the option to have ColdFusion create the tables necessary to support client
variables, since they have already been created when you added the data source for the
first server in the cluster. If you inadvertently enable the option to automatically create
client variable database tables, ColdFusion generates a SQL error.
Enabling External Client State Management
You enable client state management in the ColdFusion Server using the Administrator
to specify a data source repository where you want to store client variables.
Although you can select and use an existing data source to store client variables, Allaire
recommends creating a new data source specifically for the purpose of storing client
variables. By separating data sources, you can more easily define security options for
the data sources used in your ColdFusion environment.
When creating a new data source for client variables, you do not need to create any
tables in the data source. ColdFusion automatically creates the tables necessary to
store client variables.
To create a client variable data source:
1. Open the ColdFusion Administrator to the Data Sources page.
2. Enter a data source name in the text entry box and click Add.
3. In the Create Data Source page, enter information about the new data source
location (path) as well as other options.
Excel and Text data sources do not appear as valid data sources for use in
configuring an external client data source repository. Neither data source type
Chapter 3: Configuring ColdFusion Server 49
supports the SQL required for the client variable repository. In addition, OLE DB
data sources are not supported for use as a client data source repository.
4. Click Create to create the new data source.
To enable your client variable data source:
1. Open the ColdFusion Administrator to the Variables page, which is in the Server
group.
2. Select the name of the data source you want to use for storing client variables in
the drop down list box, and click Add.
3. On the Create Client Variable Storage page, select the options you want.
Client variable storage options
When you configure a data source for client variable storage, you have several options
for configuring the data source:
• Purging variables older than a specified number of days
• Configuring global client variable updates
• Automatically creating tables in the client variable data source
Purge client variables
Ordinarily, you don’t want to have client variables preserved indefinitely. ColdFusion
allows you to set a limit to the length of time a client variable remains active. You can
configure your client variable data source to expire client variables after some number
of days you specify.
As an example of how this can be useful, take the case of an online store. A user adds
items to his or her shopping basket, the details of which are stored as client variables in
a ColdFusion data source, but never completes the transaction, instead, choosing to
end the session. You want to be able to easily clear the contents of the shopping cart
after some number of days. Enabling ColdFusion to purge clients can help keep your
client variables data source from getting cluttered with data you don’t need.
Disable global client variable updates
By default ColdFusion updates client variables for every page request. Use this option
if you don’t want ColdFusion to perform these updates. When updates are disabled,
ColdFusion only updates global client variables when they are first created and when
they are updated. Since updating global client variables for every page request requires
a trip to the data source and back, disabling updates helps to improve the performance
of your application pages.
50 Administering ColdFusion Server
Create client variable data source tables
Use this option to allow ColdFusion to create the tables necessary for client variables
when you first configure the data source for this purpose. As you configure other
servers in your cluster to use this client variables data source, be sure to disable the
option for ColdFusion to create the necessary tables. If you inadvertently enable
automatic table generation, ColdFusion generates a SQL error because it tries to create
tables that already exist.
Migrating Client Variable Data
If you need to migrate your client variable data to another data source, you need to
know the structure of the database tables used to store this information. Client
variables stored externally use two small database tables with the following simple
structure. Data types shown in these tables are those used for a Microsoft Access
database. Your database may require different data types.
CDATA
Column Data Type
cfid char(20)
app char(64)
data memo
CGLOBAL
Column Data Type
cfid char(20)
data memo
lvisit date
Creating client variable tables
You can use the following example ColdFusion page as a model for creating client
variable database tables in your own database. Not all databases support the same
column data type names, so you may have to alter some data types for your database.
Refer to your database documentation for the proper data type.
Chapter 3: Configuring ColdFusion Server 51
Sample table creation page
<!---- Create the Client variable storage
tables in a datasource. This example applies
to Microsoft Access databases --->
<CFQUERY NAME="data1" DATASOURCE="#DSN#">
CREATE TABLE CDATA
(
cfid char(20),
app char(64),
data memo
)
</CFQUERY>
<CFQUERY NAME="data2" DATASOURCE="#DSN#">
CREATE UNIQUE INDEX id1
ON CDATA (cfid,app)
</CFQUERY>
<CFQUERY NAME="global1" DATASOURCE="#DSN#">
CREATE TABLE CGLOBAL
(
cfid char(20),
data memo,
lvisit date
)
</CFQUERY>
<CFQUERY NAME="global2" DATASOURCE="#DSN#">
CREATE INDEX id2
ON CGLOBAL (cfid)
</CFQUERY>
<CFQUERY NAME="global2" DATASOURCE="#DSN#">
CREATE INDEX id3
ON CGLOBAL (lvisit)
</CFQUERY>
Enabling Application and Session Variables
Session and application variables are enabled with this option. These options override
any individual use of the CFAPPLICATION tag to enabled application or session
variables. If these variables are disabled in the Administrator, they cannot be used in
any ColdFusion application.
Specifying timeouts
Use the Application Variables and Session Variables Maximum Timeout and Default
Timeout settings to specify the lifespan for these variable types. The default timeout
52 Administering ColdFusion Server
for application variables is two days. The default timeout for session variables is 20
minutes.
Monitoring ColdFusion Performance
ColdFusion provides a set of counters for monitoring the performance of the
ColdFusion Server. This allows you to use the Windows NT Performance Monitor
administration utility to monitor ColdFusion performance. This enhancement to NT
Performance Monitor is installed automatically by the ColdFusion setup.
A Windows NT Performance Monitor configuration file has been added to ColdFusion
for Windows systems that is pre-configured to monitor ColdFusion Server activity. The
Performance Monitor configuration file, ColdFusionServer.pmc is installed in
cfusion\bin.
To monitor ColdFusion Server activity, click on the ColdFusion Performance Monitor
icon in the ColdFusion Server Program group. You can also open the Performance
Monitor utility and then open the
ColdFusion counters available
ColdFusion supports 11 different counters you can enable in the Windows
Performance Monitor:
• Average database transaction time
• Average queue time
• Average request time
• Bytes incoming per second
• Bytes outgoing per second
• Database hits per second
• Page hits per second
• Cache pops per second
• Number of queued requests
• Number of running requests
• Number of timed out requests
cfusion/bin/ColdFusionServer.pmc file.
To enable the Performance Monitor for ColdFusion:
1. Open the ColdFusion Administrator to the Miscellaneous Debugging page.
2. Click the Enable performance monitoring option. The default is off.
3. Click Apply to save the new setting.
Chapter 3: Configuring ColdFusion Server 53
To configure the Performance Monitor:
1. From the Windows Start menu, select Programs > Administrative Tools >
Performance Monitor.
2. In the Performance Monitor, select Edit > Add to Chart or File > Open to open an
existing chart.
In the Add to Chart dialog, select ColdFusion Server from the Object drop-down
list. You can change any of the display options (Color, Scale, Width, Style) for a
counter before adding it.
3. Click one or more selections in the Counters list, then click the Add button. The
counters are listed at the bottom of the Chart View.
4. Click the Explain button to display embedded help for the selected counter.
Locking Variables
Data stored in Server, Application and Session scopes ("shared data scopes") is
persistent across browser requests and multiple requests can access the data.
Unlocked access to data by multiple requests at the same time can corrupt the data.
While you can still use the CFLOCK tag introduced in ColdFusion 4.0 to control
simultaneous access to shared data in these scopes, ColdFusion 4.5 provides more
automatic means to protect shared data from incorrect access.
For each of the Server, Application and Session scopes, the Variable Locking
Administrator page provides three choices for control - none, full checking, and
automatic locking of read accesses:
• Choosing "None" retains current ColdFusion behavior. All reads and writes of
data must be protected by a CFLOCK tag. No automatic protection is provided
and unprotected accesses may cause corruption of data.
• Choosing "Full checking" will cause ColdFusion to raise an error if any read or
write of data in one of the scopes occurs outside of the scope of a CFLOCK. This
includes accesses to any data that is aliased by being assigned to a variable
outside of the shared data scopes and the data is not copied; this can occur for
struct and query variables. For example:
<CFLOCK type="EXCLUSIVE" scope="Session" timeout="10">
<CFSet Session.var = StructNew() >
<CFSet myvar = Session.myvar>
</CFLOCK>
<CFSet myvar2 = myvar> <!--- unprotected access to alias --->
• Choosing "Automatic read locking" will cause ColdFusion to raise errors for
unprotected writes, but unprotected reads will be automatically locked.
• For Session scope, you can also choose to single thread session requests. This
means that all requests from the same session will occur sequentially, each
request waiting for all previous requests to finish before proceeding, preventing
multiple requests from simultaneously accessing shared data.
54 Administering ColdFusion Server
ColdFusion Java Settings
The Java Settings Administrator page lets you specify a number of settings that let
ColdFusion work with Java.
Java Settings
Setting Description
Java Virtual Machine Path Specifies the location of the Java virtual
machine (JVM). By default, ColdFusion
installs the JDK 1.2 JVM in the ColdFusion
directory structure.
Class Path
Initial Heap Size
Max Heap Size
System Options
Implementation Options
CFX Jar Path
Specifies the directories for classes used by
ColdFus ion.
Specifies the JVM initial heap memory size.
Specifies the JVM maximum heap memory
size.
Specifies standard JVM initialization
options as name-value pairs separated by
semi-colons. For example,
OPT1=option1;OPT2=option2
Specifies implementation specific JVM
initialization options as name-value pairs
separated by semi-colons. For example,
OPT1=option1;OPT2=option2
Specifies the location of the ColdFusion
"cfx.jar" file which contains interfaces used
by Java CFX’s.
Chapter 3: Configuring ColdFusion Server 55
ColdFusion Version Information
The Version Info Administrator page provides ColdFusion Server profile information.
The values shown correspond to several ColdFusion server variables as follows:
Windows NT Server Information Variables
Varia ble Description
Server.ColdFusion.ProductName Stores the ColdFusion product name, for
example, ColdFusion Engine.
Server.ColdFusion.ProductVersion
Server.ColdFusion.ProductLevel
Server.ColdFusion.SerialNumber
Server.OS.Name
Server.OS.Version
Server.OS.AdditionalInformation
Server.OS.BuildNumber
Stores ColdFusion product release
information, for example, 4,0,1,0.
Stores ColdFusion product level
information, for example, Professional.
Stores ColdFusion serial number
information.
Stores the server operating system name,
for example, Windows NT.
Stores the operating system version, for
example, 4.5.
Stores additional information about the
operating system, for example, Service
Pack 4.
Stores the build number of the host
operating system, for example, 1381.
Solaris version information
On Solaris, these server variables store slightly different information:
Solaris Server Information Variables
Varia ble Description
Server.ColdFusion.ProductName Stores the ColdFusion product name, for
example, ColdFusion Engine.
Server.ColdFusion.ProductVersion
Stores ColdFusion product release
information, for example, 4, 0, 1, 0.
56 Administering ColdFusion Server
Solaris Server Information Variables (Continued)
Varia ble Description
Server.ColdFusion.ProductLevel
Server.ColdFusion.SerialNumber
Server.OS.Name
Server.OS.Version
Server.OS.AdditionalInformation
Server.OS.BuildNumber
The ColdFusion Logging Page
ColdFusion generates log files you can use to help monitor ColdFusion server activity
as well as activity in your ColdFusion applications. ColdFusion generates several
different log files, most of which are written to
/opt/coldfusion/log directory on Solaris. The Administrator mail error log is written
\cfusion\Mail\Log (Windows) and /opt/coldfusion/mail/log (Solaris). All log
to
files are written in comma delimited format.
In addition to logging options, the Logging page contains a few other administrative
options.
Stores ColdFusion product level
information, for example, Enterprise.
Stores ColdFusion serial number
information.
Stores the server operating system name,
for example, UNIX.
Stores the operating system version, for
example, 5.5.1.
Stores additional information about the
operating system, for example, SunOS.
Stores the build number of the host
operating system, for example,
Generic_103640-19.
\Cfusion\Log on Windows and
Administrator email address
When you enter an administrator’s e-mail address in the Administrator Logging page,
this e-mail address appears with any error messages generated by ColdFusion. This
facility can help users report errors. Note that this e-mail address can be overridden in
the application framework page,
Application.cfm.
Log directory
The default location for ColdFusion log files in Windows is cfusion\log. For Solaris,
the default location is
ColdFusion log files by entering a new value in the Log Directory list box.
opt/coldfusion/log. You can specify a new location for
Chapter 3: Configuring ColdFusion Server 57
Log slow pages
ColdFusion allows you to track pages in your applications that take longer than a
specified length of time to process. You can specify the amount of time ColdFusion
allows before writing an entry to the server.log file.
Logging email messages
In addition to system logs, ColdFusion writes a log of errors generated by SMTP mail
server used to post mail from ColdFusion applications. You can choose to log warning
messages, information messages, or error messages.
In Windows, the mail log file is stored by default in
mail log file is stored by default in
/opt/coldfusion/mail/log.
To enable email logging:
1. Open the ColdFusion Administrator to the Mail Logging page.
2. Select the error severity you want and click to enable the Log all email messages
checkbox.
3. Click Apply to complete the operation.
cfusion\mail\log. On Solaris, the
Log files created by ColdFusion
ColdFusion creates nine different log files.
ColdFusion Log Files
Log Filename Description
exec.log
rdseservice.log
application.log
webserver.log
Logs problems with the ColdFusion Server service. If the
ColdFusion service hangs or if the service was unable to access
the system registry, that information is written to
cfexec.log.
Logs errors occurring in the ColdFusion RDS service, which
provides file, debugging, directory, and database browsing
services for ColdFusion Studio.
Logs every ColdFusion error reported back to a user. All
application page errors, including ColdFusion syntax errors,
ODBC errors, and SQL errors, are written to this log file. Every
error message that is displayed on a user’s browser is logged
here, along with the visitor’s IP address and browser
information, if possible.
Logs errors occurring in the Web server and the ColdFusion
stub.
58 Administering ColdFusion Server
ColdFusion Log Files (Continued)
Log Filename Description
schedule.log
server.log
customtag.log
remote.log
errors.log
Logs scheduled events that have been submitted for
execution. Indicates whether the task submission was initiated
and if it succeeded. Provides the scheduled page URL, the date
and time executed, and a task ID.
Logs errors that occurred in the communication between
ColdFusion and your Web server. This file is meant primarily to
help Allaire Technical Support personnel.
Logs errors generated in custom tag processing.
The Network Listener Module (NLM) writes various messages
to the
remote.log file relating to a distributed ColdFusion
configuration.
Logs errors generated in attempts to send mail from
ColdFusion applications. Stored in
(Windows) or
/opt/coldfusion/mail/log (Solaris).
cfusion\mail\log
Log file format
All ColdFusion log files share the same comma-delimited format consisting of five
separate fields as follows:
ColdFusion Log File Format
Field Field Description
1Severity“Information,” “Warning,” or “Error.”
2 Thread ID Service Thread ID. This information is only useful to Allaire
3 Date Date that the error occurred.
4 Time Time that the error occurred.
5 Details Description of the error (with error number, if appropriate).
Mapping Directories
The Mappings page in the ColdFusion Administrator allows you to create logical
aliases for physical directories on your server. Mapping directories is only necessary if
Technical Support personnel.
Chapter 3: Configuring ColdFusion Server 59
you want to use ColdFusion with CGI or if you want to use absolute references to
ColdFusion pages with the CFINCLUDE tag.
For information about using ColdFusion with CGI instead of one of the standard Web
server APIs (NSAPI, ISAPI, Apache API, or WSAPI), see Chapter 7, “Using CGI with
ColdFusion,” on page 269.
The Web server APIs supported by ColdFusion (NSAPI, ISAPI, Apache API, and WSAPI)
perform document type mapping, which makes directory mapping in ColdFusion
unnecessary. When a browser loads a file with the
recognizes that file type as a ColdFusion application page.
.cfm extension, the Web server
Using the Extensions Pages
Use the ColdFusion Administrator Extensions pages to register Java applets and CFX
tags, custom tags built with C++.
Managing CFX tags
The CFX Tags page in the ColdFusion Administrator is used to Register and manage
ColdFusion custom tags built with C++.
ColdFusion allows you to build extensions or custom tags in two ways:
• Using C++ to code DLLs (Windows) or shared objects (Solaris) that provide a
custom tag you can use in your application pages.
• Using CFML to create custom tags you invoke in your application pages.
To use a CFX tag you must first register it with ColdFusion. This process simply tells
ColdFusion where to find the required DLL when it attempts to process the CFX tag in
an application page.
Note A wide variety of custom tags of both types is available from the
ColdFusion Tag Gallery.
CFX tag samples
Source code and compiled versions of two sample CFX tags are installed with
ColdFusion (you can register and use them in your application pages). You must first
compile this code before registering the DLLs or shared objects in the ColdFusion
Administrator. These examples can be found in
(Solaris) and
The two CFX tag examples installed with ColdFusion are as follows:
• directorylist — Returns a directory listing.
•
cfusion\cfx\examples (Windows).
ntuser_db — (Windows NT only) Allows you to modify Windows NT user
permissions.
opt/coldfusion/cfx/examples
60 Administering ColdFusion Server
To register a CFX tag:
1. Open the CFX Tags page in the ColdFusion Administrator.
2. Enter a name for the CFX tag you are adding. Tag names must be prefixed with
CFX_.
3. Click Add to open the New CFX Tag page.
4. Enter the path to the library you want to use or browse your system to locate the
library you want to use.
5. Enter the procedure that implements the tag. The procedure name must
correspond with an existing procedure in the DLL or shared object you’ve
specified. Procedure names are case-sensitive.
6. Click Keep library loaded to prevent reloading the library into memory each time a
referenced page is accessed.
7. Enter a description and click Add to finish.
Registering a Java applet
The Applets page in ColdFusion allows you to register Java applets for use in
ColdFusion forms with the CFAPPLET tag. Registering the applet before using it in
ColdFusion applications allows you to encapsulate the applet in a simple, easy-to-use
interface. The CFAPPLET tag you use to place the applet can be used to override any
parameters you define in the Administrator Registered Applets page.
Before you can use CFAPPLET to place a Java applet in your CFFORM, you must
register the applet in the ColdFusion Administrator.
Applets Administrator page
You can use the CFAPPLET tag to place Java applets in a CFFORM. However, before you
can use the tag you need to register your applet using the ColdFusion Administrator.
Once your applet is registered with ColdFusion, using the CFAPPLET tag in your code
is very simple since all parameters are predefined in the Administrator. Since
parameters are predefined in the Administrator, you only need to specify parameter
values you want to override for a particular instance. With CFAPPLET, you could enter
just the applet source and the form variable name you want to use:
<CFAPPLET APPLETSOURCE="Calculator"
NAME="calc_value">
You can define all other parameters when you register the applet in the Administrator.
Using the HTML APPLET tag, you'd have to invoke all the applet's parameters every
time you wanted to use it in an page.
The new Registered Applets page in the ColdFusion Administrator allows you to
register Java applets you want to place in your ColdFusion pages with the CFAPPLET
tag.
Chapter 3: Configuring ColdFusion Server 61
To register a Java applet:
1. Install the Java class files and any other files required for the class. You’ll need to
specify the codebase argument when registering the applet, so take note of the
installed path.
2. In the ColdFusion Administrator, open the Register New Applet page by clicking
the Applets button.
3. Enter the necessary information. Each field corresponds to values you would
enter in the HTML APPLET tag.
4. Enter the parameter name and value pairs required for your applet. If necessary,
you may need to refer to whatever documentation exists for your applet.
5. When you’re done, click Create.
Applet registration fields are explained in the following table.
Java Applet Registration Fields
Field Description
Codebase Enter the base URL of the applet: the directory that
contains the applet components. The applet class files
must be located within the Web browser root
directory. Example:
http://
servername
/classes
Code This is the name of the file that contains the applet
subclass. The filename is relative to the codebase URL.
The *.class file extension is not required.
Method Enter the method name in the applet that returns a
string value. You use this method name in the NAME
attribute of the CFAPPLET tag to populate a form
variable with the method’s value. If the applet has no
method, leave this field blank.
Height Enter a measurement in pixels for the vertical space
for the applet.
Width Enter a measurement in pixels for the horizontal
space for the applet.
Vspace Enter a measurement in pixels for the space above
and below the applet.
Hspace Enter a measurement in pixels for the space on each
side of the applet.
Align Choose the alignment you want.
62 Administering ColdFusion Server
Java Applet Registration Fields (Continued)
Field Description
Java Not Supported
Message
Parameter Name Enter a name for a required applet parameter. Your
Value For every parameter you enter, define a default value.
This message is displayed by browsers that do not
support Java applets. If you want to override this
message, you specify a different message in the
CFAPPLET tag NOTSUPPORTED attribute.
Java applet will typically provide the parameter name
needed to use the applet. Enter each parameter in a
separate parameter field.
Your applet documentation will provide guidelines on
valid entries.
Debug Settings in the ColdFusion Administrator
ColdFusion can provide important debugging information for every application page
requested by a browser. When enabled, debugging output is shown in a block following
normal page output.
Note By default, when you enable any of these options, debug output becomes
visible to all users. You can, however, restrict debug output by using the
Restrict debug output to selected IP address form at the bottom of the
Debug Settings page.
The Debugging page of the ColdFusion Administrator provides these output options:
Debug Settings in ColdFusion Administrator
Setting Description
Enable performance monitoring Allow the NT Performance Monitor application to
display information about the current ColdFusion
Server. On platforms that do not support the NT
Performance Monitor, a command line utility, CFSTAT,
is provided to display the same information.
Enable CFML stack trace Generate information in CFCATCH.TAGCONTEXT
about the tags that were executing when ColdFusion
detected a CFML structured exception.
Show variables Display the names and values of all CGI, URL, form,
and cookie variables.
Chapter 3: Configuring ColdFusion Server 63
Debug Settings in ColdFusion Administrator (Continued)
Setting Description
Show processing time Display the time, in milliseconds, it took the
ColdFusion Server to process the page request. The
detail view shows the time it takes to process each
page used to compose the final page.
Show SQL and data source name Display the data source name and the SQL statement
in database query errors messages.
Show query information Display the number of records, processing time, and
SQL statement for each query executed.
Display the template path in error
messages
Display the template’s file name. The template’s file
name is useful for debugging, but may be a security
hazard because it displays information about a
server’s file structure.
Note By default, when you enable any of these options, debug output becomes
visible to all users. You can, however, restrict debug output to a selected
IP address.
To restric t debug ou tput to a specific IP number:
1. Enter the IP number you want to receive debug output, and click Add. Debug
output will be visible only to the specified IP address.
2. To disable debug output to a specific IP address, select the address and click
Remove.
If debugging output options have been selected and no IP address specified, debug
output will be displayed to all users.
Note There are also important runtime debugging options available in
ColdFusion Studio. For more information about these options, such as
setting breakpoints, see Developing Web Applications with ColdFusion.
Configuring Administrator Mail
You use the ColdFusion Administrator Mail page to specify a mail server to handle
sending automated mail messages from the server.
Enter a valid mail server (either a mail server name or IP address) as well as a server
port number and connection timeout.
To verify that your mail server connection works, you can send a test message.
64 Administering ColdFusion Server
Indexing Data with Verity
The Verity Search’97 indexing and searching technology, which has been incorporated
into ColdFusion, provides a means for creating collections of indexed data optimized
for fast retrieval.
To use Verity searching and indexing technology you:
1. Create a Verity collection using the ColdFusion Administrator Verity page or using
the CFCOLLECTION tag at runtime.
2. Populate a collection with data using options on the ColdFusion Administrator
Verity page to index specific directories, or using the CFINDEX tag at runtime.
3. Build searching and indexing capability using the CFINDEX and CFSEARCH tags
into your application.
For more information about populating and searching Verity collections using the
CFINDEX and CFSEARCH tags, see Developing Web Applications with ColdFusion.
Using the Verity Collections page
The Verity Collections page in the Administrator provides a means for creating
collections. Collections can also be created and populated externally using native
Verity tools. See your Verity documentation for more information about using native
Veri t y tools.
Use the Verity Collections page to:
• Create and name collections
• Populate a collection with text file data from a specified directory.
• Purge, repair, optimize, delete, or update a collection.
Creating a collection
Before you can search collections using the CFSEARCH tag in your ColdFusion
application, you must first create the collection and then populate it with data.
To create a collection, follow these steps:
1. Open the Administrator Verity page.
2. Enter a name for your collection.
3. If necessary, specify a path for the collection.
4. Select a language from the drop down list box.
5. Click Create.
Now, you can populate the collection with data.
Chapter 3: Configuring ColdFusion Server 65
Populating a collection
Once you’ve created a collection, you can populate it with data from text and binary
files in a directory you specify. Data from a ColdFusion query can only be indexed
using the ColdFusion CFINDEX tag in a ColdFusion application page.
Verity Supported File Types
The ColdFusion Verity implementation supports a wide array of document types. This
means you can index Web pages, ColdFusion applications, and many binary
document types and produce search results that include summaries of these
documents.
The following table lists the supported document types.
Supported Document Types
Documents Ve rs io ns
Text files
HTML, CFML, DBM, SGML, XML, N/A
ANSI, ASCII, Plain Text N/A
Word processors
Adobe Acrobat (PDF)
Adobe FrameMaker (MIF)
Aplix Words
Corel WordPerfect for Windows
Corel WordPerfect for Macintosh
Lotus AMI Pro
Lotus AMI Pro Write Plus
Lotus Word Pro
Microsoft Office
MS Rich Text Format (RTF)
MS Word for Windows
MS Word for DOS
MS Word for Macintosh
MS Notepad, WordPad
MS Write, MS Works
XYWrite
All
All
4.2
5.x 6, 7, 8
2, 3
2, 3
all
96, 97
95, 97
1.x, 2.0
2, 6, 95, 97
4, 5, 6
4.0, 5.0, 6.0
all
all
4.12
66 Administering ColdFusion Server
Supported Document Types (Continued)
Documents Ve rs io ns
Spreadsheets
Corel QuattroPro
Lotus 1-2-3 for DOS/Windows
Lotus 1-2-3 for OS/2
MS Excel
MS Works
7, 8
2.0, 3.0, 4.0, 5.0, ’96, ’97
2
3, 4, 5, ’95, ’97
all
Presentation
Corel Presentations
Lotus Freelance
MS PowerPoint
7.0, 8.0
96, 97
4.0, 95, 97
To create an index of data from a directory:
1. Create a collection in the Administrator.
2. If not already selected in the list of collections, select the collection you want to
populate and click Index.
3. Edit the list of file extensions, if necessary.
4. Enter a directory path you want to index in the form:
5. Enter a URL to return for documents returned in a search operation against this
collection. For example, if you are indexing the ColdFusion documentation
directory and subdirectories, the directory you index could be
c:\inetpub\wwwroot\cfdocs. You would enter the return URL as:
http://
6. Click Index. ColdFusion populates the collection with data from the specified
directory.
Note that Verity collections, including those that index query data, can be created
using the CFCOLLECTION tag, and can be populated using the CFINDEX tag in your
ColdFusion application pages.
my_server
/cfdocs/
Repairing, Optimizing, Purging, and Deleting Collections
Verity collections that return erroneous data or have other problems can often be
repaired using the Repair and Optimize feature in the Verity page of the ColdFusion
Administrator.
Chapter 3: Configuring ColdFusion Server 67
When you need to clear a collection of data, use the Purge feature to delete the
contents of the collection without deleting the collection itself.
Caution! 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
data.
The safest approach is this: During a repair, NO OTHER ACTION should be taken.
Configuring Server-Side Source Control
On Windows systems, you can configure ColdFusion Server to use Microsoft Visual
SourceSafe for source code management. This allows ColdFusion Studio users to
access source files through a ColdFusion RDS server. Please review your SourceSafe
licensing agreement for guidelines on this configuration.
Requirements
You need the following software configuration for server-side source control with
ColdFusion:
• SourceSafe client software installed on the same server as ColdFusion Server.
• The account under which ColdFusion runs must have permission to access the
SourceSafe server executables and files. Since the SourceSafe server may well be
hosted on a remote (non-local) system, be sure that ColdFusion has been
configured to run under an account other than the default system account.
In the ColdFusion Administrator, you enable server-side source control by entering
values in two form fields:
• Path to SrcSafe.ini — Enter the path to the local srcsafe.ini file. This is the file
the local SourceSafe client uses for configuration.
• Working directory — This is the directory the SourceSafe server uses when files
are checked in and out.
In addition, you can set an Operation Timeout option that allows you to set the
amount of time in seconds before a source control operation times out. Ordinarily, you
won’t have to change the default value.
Once you have the ColdFusion Server configured for server-side source control, Studio
users can create a remote RDS server in Studio, and go about checking files in and out.
For more information about source control configuration in ColdFusion Studio, please
refer to Studio online documentation.
68 Administering ColdFusion Server
Using ColdFusion in a Distributed Configuration
ColdFusion 4.5 can be configured in a distributed manner where the ColdFusion
engine is running on a separate computer from the Web server. Running ColdFusion in
this way might be called distributed or remote ColdFusion.
To run distributed ColdFusion, you must make the following changes to a standard
installation:
• On the Web server side, you must notify the ColdFusion Web server plug-in that
you want it to talk to a ColdFusion engine on another machine. You do this
simply by making appropriate entries in an INI file.
• On the ColdFusion engine side, you must run an additional piece of software,
known as the Network Listener Module, that listens for incoming ColdFusion
requests and forwards them to the ColdFusion engine running on that
machine. The ColdFusion engine itself is a standard release version of the
engine with no special modifications to accommodate remoting.
In addition to allowing the ColdFusion engine to be located on a separate machine
from the Web server, distributed ColdFusion provides the following unique
capabilities:
• It allows the machine hosting the Web server to potentially be of a different
architecture from the machine hosting the ColdFusion engine.
• It allows more than one Web server to be served by the same ColdFusion
engine.
To provide some degree of security for the data being transferred between the Web
server and the ColdFusion engine, that conversation is encrypted using a standard, 56bit DES encryption algorithm.
Although it’s possible for a ColdFusion engine to simultaneously service both local and
remote requests, it is not possible for a single Web server to simultaneously dispatch
both local and remote ColdFusion requests. When starting up, the ColdFusion Web
server plug-in determines if it’s to run in local or remote mode and remains in that
mode until it’s shutdown.
Distributed ColdFusion and clustering
The distributed ColdFusion configuration is not supported when ColdFusion is also
configured for clustering. The reason is that the clustering component in ColdFusion,
which runs as part of the Web server, needs to be able to communicate with the
ColdFusion engine. This arrangement assumes that the ColdFusion engine and the
Web server are on the same machine, which is not necessarily the case in a clustered
environment.
Changes in the 4.5 version
Remoting capabilities similar to what are now available in ColdFusion 4.0 were first
provided as a special, add-on feature of ColdFusion 3.1.1. It was not possible to run the
Chapter 3: Configuring ColdFusion Server 69
standard, release version of ColdFusion 3.1.1 in this manner. To do so, it was necessary
to purchase and install special versions of the ColdFusion Web server plug-in modules
on the Web server side and a separate listener module on the ColdFusion engine side.
In ColdFusion 4.0 all the necessary pieces are provided as part of the standard
distribution. All the supported Web server plug-ins have been enhanced to include the
capability to send and receive ColdFusion data via TCP/IP, and the engine-side listener
module is available as part of the standard release.
Configuring Distributed ColdFusion
Before trying to run ColdFusion in a distributed configuration, you must perform a
standard installation of ColdFusion on all the machines involved. On the computer
running the Web server, this guarantees that the ColdFusion server plug-ins are
correctly loaded by the Web server. On the computer running the ColdFusion engine,
this guarantees that the engine is set up and operating correctly.
Having complete, standard installations of ColdFusion available on all machines also
provides a useful baseline environment so that validation can be done in the absence
of the remote extensions. Should problems arise using ColdFusion in remote mode, it‘s
possible to run ColdFusion locally to determine whether or not the problems are
related to the distributed configuration.
If, after successfully testing your remote configuration, you wish, for security reasons,
to disable the ColdFusion engine installed on the computer hosting the Web server,
you can do this easily by renaming the following executable files in the
(Windows)
This prevents any ColdFusion server-side process from running while generally
preserving your ColdFusion configuration.
coldfusion/bin (Solaris) directory:
•
cfserver
• cfrdsservice
• cfexec
cfusion/bin
Using the modified plug-in
In ColdFusion 4.5 all the Web server plug-ins are remote-capable so no special
installation is required. All you need to do is let the plug-in know that you want to run
in remote mode. You do this by putting the following information in an INI file and
putting that file in the root directory of your ColdFusion installation on the machine
running the Web server. That INI file must be named
security, this INI file may be optionally set to be automatically deleted after being read
at startup.
cfremote.ini. To enhance
70 Administering ColdFusion Server
Here is a sample of the INI file with comments explaining what the various fields do.
This sample may be cut and pasted and used as a template to get started.
;------------------------------------------------------------------;
; Sample INI file for ColdFusion Remoting.
;
; Place this file in the root directory of your ColdFusion installation.
; It must be named "cfremote.ini".
;
; !IMPORTANT! * All values (the strings on the right hand side of
; the equals sign) must be quoted using double
; quotes.
; * All info is case insensitive..
; * Lines beginning with a semicolon are treated as
; comments and are ignored.
;
; Use REMOTEPATH and LOCALPATH to map filenames from one host to another.
; For example, if you are running Apache webserver on Solaris and you
; want to connect to a ColdFusion server running on Windows NT, you might
; set these values as:
;
; LOCALPATH = “/usr/local/apache/htdocs”
; REMOTEPATH = “C:\Inetpub\wwwroot\”
;
; This would map any ColdFusion pages in /usr/local/apache/htdocs/fcml/
; to C:\Inetpub\wwwroot\cfml\
; Use this to turn on/off the remoting capability.
; Valid values: Yes, No.
;
REMOTING = "YES"
; Use this to specify the IP address of the remote computer running
; the ColdFusion Server.
;
; Valid values: a valid IP address, e.g.: 139.56.205.102.
;
IP = "205.181.21.61"
; Use this to specify the port on that computer on which the remote
; ColdFusion Network Listener Module is listening.
;
; Valid values: a valid port number (integer).
;
PORT = "1234"
; Use this to specify that the data sent between the machine running
; the Web server and the machine running the ColdFusion Application
; Server be encrypted.
;
; Valid values: Yes, No.
;
Chapter 3: Configuring ColdFusion Server 71
ENCRYPTION = "YES"
; Use this to specify the key used to encrypt the data.
;
; Valid values: any string of up to 127 ASCII chars.
;
KEY = "doglips"
; Use this to have this INI file be deleted after it is read at
; startup. (This is a security feature as it keeps your key from
; being read by others.)
;
; Valid values: Yes, No.
;
DELETE = "NO"
; Use this to write a message to the ColdFusion "webserver.log"
confirming that
; remoting is active and what startup parameters (except the encryption
; key) were used.
;
; Valid values: Yes, No.
;
MESSAGE = "YES"
;
;--------------------------------------------------------------------
As with all warning and error messages from any of the ColdFusion Web server plugins, such text is written to the ColdFusion log file
webserver.log in the log
subdirectory of the directory into which you installed ColdFusion (on the machine
hosting the Web server.) This file should be the first place you look if you encounter
problems running ColdFusion in a distributed configuration since, for a variety of
practical and security reasons, ColdFusion will not run in distributed mode if any
information in the INI file is missing or incomplete.
The Network Listener Module (NLM)
The NLM is a stand-alone program that acts as a network front-end for the standard
ColdFusion Server. It runs on the same computer on which the ColdFusion Server is
running. It listens for incoming requests via TCP/IP and forwards them on to the local
ColdFusion Server. The ColdFusion Server then processes those requests, returning
the results to the listener module which, in turn, returns them via the original TCP/IP
connection. It is a silent, background process with no user interaction. On NT, it runs
as an NT service. On UNIX, it runs as a daemon. For debugging or other special
purposes, it may also be run as a command line program by specifying the appropriate
command line option (-i) at startup.
Installing the module on Windows NT
On NT, the module consists of a single executable file, cfdist.exe. Before you can run
the listener as an NT service, you must perform the following installation step.
72 Administering ColdFusion Server
To install the network listener module as a service:
1. Run the listener with the following special command line argument:
cfdist.exe -sINSTALL
2. If installation was successful, it should now appear on your Services list under the
name ColdFusion NetListener. If it doesn’t show up, look in the module’s log file,
distributed.log in the log subdirectory of your ColdFusion installation, for
information about why the install failed.
Note Once you’ve installed the module as an NT service you cannot move the
executable file unless you uninstall and reinstall it in its new location.
Once installed as a service, you can start, stop, pause or continue the listener’s
operation as you would any NT service. You can start or stop the listener independent
of any of the other ColdFusion services although, of course, the listener must be
running to receive remote network requests. Note that when starting the service (from
the NT Services Control Panel applet), you will need to specify -p switch and possibly
the -k switch in the Startup Parameters box in the Services applet.
Please refer to the list of command line options below.
To uninstall the listener
Invoke cfdist.exe with the -sREMOVE command line option. Notice of successful
removal will be written to the listener log.
Installing the module on UNIX
On UNIX, the listener module consists of a single executable file, in this case named
simply
cfdist. It is not necessary to perform any special installation step on UNIX.
To start the listener as a daemon:
Type the executable’s name (without the -i switch) and the process will start. Because
it’s running as a daemon, the command will return immediately having launched the
process in the background. You will probably use at least the -p switch when starting
the daemon.
Please refer to the list of command line options below.
To stop the daemon process:
You need to kill it by its process ID. Use the ps command to get the PID and then kill
the process as demonstrated below.
ps -deaf | grep cfdist | grep -v grep
It returns the PID in a string something like:
ckintzin 980 1 0 15:48:12 ? 0:00 cfdist
The first number is the PID. Use it in the kill command to stop the process:
kill -INT 980
Chapter 3: Configuring ColdFusion Server 73
Repeating the ps command should now return nothing, indicating the process is now
dead.
Listener Module Command Line Options
The Network Listener Module (NLM) executable, cfdist (cfdist.exe on Windows
NT) takes the following command line options at startup. Of these options, you’ll
probably only use the -p option on a regular basis.
Listener Module Command Line Options
Option Description
-v Verbose. This option prints out confirmation of the command line
options in use, and on what port the program is running. It also prints
information about each connection that comes in. This can be useful
to confirm that requests are, indeed, reaching the remote computer.
-pnnnn Port number where nnnn is the port number. If no port number is
specified, the program automatically selects an unused port on
which to run. In most cases, you use this option to guarantee that
you’re using the same port as the remote Web server.
-i Interactive. Run from a command line not as a daemon/service. In
order for verbose commentary to appear on the terminal, you must
be running in interactive mode. Aside from the display of debugging
output, however, there is no difference in operation between running
the program from a command line or running it as a daemon/service.
-r Reuse. (UNIX Only) If the specified port appears to be in use, try to use
it anyway. Sometimes TCP/IP connections don’t get closed down
immediately. In those cases the connections can take a few minutes
to timeout and close down. Unfortunately, these lingering
connections will prevent the program from restarting on the same
port because it thinks that port is in use. To overcome this and allow
you to restart without waiting or switching to another port, you can
use this option. Be careful, however, not to use this option
indiscriminately as it could result in multiple versions of the listener
running at the same time.
-kxxxx Key for encryption. (where xxxx is the string used as the key) The key
may be any string of printable ASCII chars up to 127 characters long.
-sINSTALL Setup, install-mode. (NT Only) Install the process as an NT service. Its
service name will be ColdFusion NetListener.
-sREMOVE Setup, remove-mode. (NT Only) Uninstall the service.
74 Administering ColdFusion Server
The program will print out a list of available options along with a brief description of
their purpose anytime you enter an unknown option at the command line.
Using the INI file to specify startup options
It is also possible to specify startup options for the listener in an INI file. This INI file is
similar to the INI file required on the Web server side, but is available on the
ColdFusion engine side as a convenience (since all the required information may be
supplied as command line options at startup time.) Below is a template for this INI file.
If used, it must be placed in the root directory of your ColdFusion installation (on the
machine hosting the ColdFusion engine), and it must be named
enhance security, this INI file may be optionally set to be automatically deleted after
being read at startup.
;-----------------------------------------------------------------;
; Sample INI file for CFDist (AKA the "ColdFusion Listener Module").
;
; Place this file in the root directory of your ColdFusion installation.
; It must be named "cfdist.ini"
;
; !IMPORTANT! * All values (the strings on the right hand side of
; the equals sign) must be quoted using double
; quotes.
; * All info is case insensitive..
; * Lines beginning with a semicolon are treated as
; comments and are ignored.
;
cfdist.ini. To
; Use this to specify the port at which to listen for incoming ColdFusion
; requests
;
; Valid values: a valid port number (integer).
;
PORT = "1234"
; Use this to specify that the data sent between the machine running
; the Web server and the machine running this program be encrypted.
;
; Valid values: Yes, No.
;
ENCRYPTION = "YES"
; Use this to specify the key used to encrypt the data.
;
; Valid values: any string of up to 127 ASCII chars.
;
KEY = "doglips"
; Use this to have this INI file be deleted after it is read at
; startup. (This is a security feature as it keeps your key from
; being read by others.)
Chapter 3: Configuring ColdFusion Server 75
;
; Valid values: Yes, No.
;
DELETE = "NO"
; Use this to write a message to the ColdFusion "remote.log" confirming
that
; remoting is active and what startup parameters (except the encryption
; key) were used.
;
; Valid values: Yes, No.
;
MESSAGE = "YES"
;
;--------------------------------------------------------------------
The listener also writes various informative messages to the remote.log file in the log
subdirectory of your ColdFusion installation (on the machine hosting the ColdFusion
engine.)
76 Administering ColdFusion Server
C HAPTER 4
Chapter 4 Managing Data Sources
ColdFusion facilitates the delivery of dynamic database content to the Web in a very
short time-frame Before you can use a database in a ColdFusion application, you
must register data source in the ColdFusion Administrator. This chapter is organized
by database type and connection type.
Contents
• About ColdFusion Data Sources ..................................................................... 78
• Choosing the Right Drivers .............................................................................80
• Adding Data Sources for ColdFusion.............................................................. 82
• Verifying ColdFusion Data Sources ................................................................ 85
• Connecting to Microsoft SQL Server Databases............................................87
• Connecting to OpenIngress Databases .......................................................... 90
• Connecting to dBase Databases...................................................................... 92
• Connecting to Microsoft Access Databases...................................................94
• Connecting to Microsoft Excel Databases......................................................96
• Connecting to ASCII Text Databases .............................................................. 97
• Connecting to Oracle 7.3/8.0 Databases........................................................ 98
• Connecting to DB2 Data Sources.................................................................. 105
• Connecting to Informix data sources...........................................................111
• Connecting to Sybase System 11 data sources ............................................ 117
• Using ColdFusion to Create a Data Source.................................................. 120
78 Administering ColdFusion Server
About ColdFusion Data Sources
For ColdFusion developers, the term "data source" can refer to a number of different
types of structured content accessible locally or across a network. You can query Web
sites, LDAP servers, POP mail servers, and documents in a variety of formats.
Most commonly though, a database will drive your applications and for this discussion
a data source is defined as the entry point for database operations.
Before you can access a database with a ColdFusion application, you must configure
the database as a ColdFusion data source. You do this using the ColdFusion
Administrator, Data Sources page. The specific databases you can configure for
ColdFusion depend on the platform on which ColdFusion Server is installed and the
edition of ColdFusion you’re running, Express, Professional, or Enterprise.
When you first open the ColdFusion Administrator, you’ll see two ODBC data sources
already configured for use by ColdFusion:
• cfexamples — A data source used by the example applications optionally
installed with ColdFusion Server.
• cfsnippets — A data source used by the runnable code examples accessed
through pages in the CFML Language Reference and through the Snippets
Launcher, which is accessible from the ColdFusion welcome page.
Loading...