Macromedia Advanced ColdFusion Administration User Manual

Advanced

ColdFusion Administration

ColdFusion® 5

Macromedia® Incorporated

be used or copied only in accordance with the terms of such license. The content of this manual is furnished for info rmatio nal us e only , is su bject to cha nge with out noti ce, an d should not be construed as a commitment by Macromedia, Inc. Macromedia Inc. 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, record ing, or otherwise , without the prior written permission of Macromedia Inc.

ColdFusion and HomeSite are U.S. registered trademarks of Macromedia Inc.macromedia inc.M ac rom edi a, the Mac r om ed ia log o, Macr om ed ia Spec tra , ColdFusion logo , a nd J Run are tr adema rks o f Ma crome dia, I nc . Java is a t radema rk of Sun Microsystems, Inc. Microsoft, Windows, Windows NT, Windows 95, Microsoft Access, and FoxPro are registered trademarks of Microsoft Corporation. PostScript is a trademark of Adobe Systems Inc. Solaris is a trademark of Sun Microsystems Inc. UNIX is a trademark of The Op en Grou p.All oth er comp any nam es, bra nd name s, and product names are trademarks of their respective holder(s).

Part number: ZCF50MADM

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Developer Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

About ColdFusion Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Getting Answers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Contacting Macromedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Part I Data Sources and Tools. . . . . . . . . . . . . . . 1

Chapter 1 Advanced Data Source Management . . . . . . 3

Printed and online documentation set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Viewing online documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

About ColdFusion database drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

About OLE DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

About native drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Using ColdFusion to Create a Data Source (UNIX only). . . . . . . . . . . . . . . . . . . . . 10

Using Connection String Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

About the connection string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Changes to the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Changes to CFML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Connecting to DB2 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Configuring DB2 options (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Configuring DB2 options (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Configuring system and services files (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 16

Installing and Configuring DB2 Client Enabler (UNIX) . . . . . . . . . . . . . . . . 16

Data source and start script settings for DB2 (UNIX) . . . . . . . . . . . . . . . . . . 18

DB2 binding and privileges for ODBC (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 19

Executing a DB2 stored procedure (Windows, UNIX) . . . . . . . . . . . . . . . . . 19

iv Contents

Connecting to dBASE/FoxPro Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Configuring dBASE/FoxPro options (Windows) . . . . . . . . . . . . . . . . . . . . . . 21

Configuring dBASE/FoxPro Driver options (UNIX) . . . . . . . . . . . . . . . . . . . 23

Connecting to Excel Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

ODBC: Microsoft Excel Driver options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

ODBC: MERANT Excel Workbook Driver options . . . . . . . . . . . . . . . . . . . . . 25

Connecting to Informix Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Configuring Informix using ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Configuring Informix using the native driver . . . . . . . . . . . . . . . . . . . . . . . . . 27

Connecting to Informix data sources (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . 27

Connecting to Informix through ODBC/CLI (Windows, UNIX) . . . . . . . . . 29

Connecting to Sybase Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

ODBC: MERANT Sybase ASE Driver options . . . . . . . . . . . . . . . . . . . . . . . . . 32

Native: Sybase 11 Driver options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Tips for connecting to Sybase System 11 (UNIX) . . . . . . . . . . . . . . . . . . . . . 33

Connecting to Text Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

ODBC: Microsoft Text Driver options (Windows) . . . . . . . . . . . . . . . . . . . . . 35

ODBC: MERANT Text Driver options (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 35

Connecting to Visual FoxPro Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 2 Administrator Tools . . . . . . . . . . . . . . . . . . . 39

Accessing the Administrator Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Features on the Tools Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Logs and Statistics tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

System Monitoring tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Archive and Deploy tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Part II ColdFusion Security . . . . . . . . . . . . . . . . 57

Chapter 3 ColdFusion Security . . . . . . . . . . . . . . . . . . 59

Why Is ColdFusion Security Important?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Types of ColdFusion Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Choosing a Level of ColdFusion Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Developing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Deploying applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Securing the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

To Learn More About Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Contents v

Chapter 4 Configuring Basic Security . . . . . . . . . . . . . 71

About Basic Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Installation defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Configuring Remote Development Security (RDS) . . . . . . . . . . . . . . . . . . . . . . . . . 73

Securing data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

ColdFusion Remote Development Services (RDS) . . . . . . . . . . . . . . . . . . . . . . . . . 74

Basic security limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Securing ColdFusion file resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Securing ColdFusion data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Using a Password to Restrict Access to RDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

ColdFusion Studio Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Removing password-based access control: Windows . . . . . . . . . . . . . . . . . 76

Configuring Basic Runtime Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 5 Configuring Advanced Security . . . . . . . . . 79

What is Advanced Security? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Advanced Security Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

User directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Resource types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Security contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Advanced Security Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Securing applications with User security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Securing resources with RDS security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Securing applications with a security sandbox . . . . . . . . . . . . . . . . . . . . . . . 85

Securing the ColdFusion Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Creating an Advanced Security Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Implementation summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Setting Up a Security Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Caching Advanced Security Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Defining User Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Defining a Security Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Specifying Resources to Protect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Implementing ColdFusion RDS Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Implementing User Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Implementing Server Sandbox Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Securing the ColdFusion Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Viewing a Map of your Security Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

vi Contents

An Example of ColdFusion Studio Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Enabling Advanced Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Specifying a User Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Defining a security context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Specifying resources to protect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Adding policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Granting access privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Assigning users/groups to policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Enable ColdFusion Studio Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Advanced Security Single Sign-On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Undocumented Tags and Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Administrative Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Administrative Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Part III Advanced Verity Tools. . . . . . . . . . . . . 113

Chapter 6 Configuring Verity K2 Server . . . . . . . . . . 115

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Verity operates in two modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Quick start to K2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

About K2 Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Installation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Two Verity modes now supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

How ColdFusion determines which mode to use . . . . . . . . . . . . . . . . . . . . 119

Collections created with ColdFusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Starting K2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Windows batch file example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Linux and UNIX scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Stopping K2 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Stopping K2 when run as a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Stopping K2 when run as an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Stopping K2 Server on Linux/UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Editing the k2server.ini File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Edit the vdkHome parameter of k2server.ini . . . . . . . . . . . . . . . . . . . . . . . . 124

Edit the Coll-n section of k2server.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

k2server.ini file listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

k2server.ini Parameter Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Server section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Search thread keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Collection sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Using the rck2 Utility to Search K2 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

rck2 syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

rck2 command options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Contents vii

Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Generic error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Usage error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Runtime error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Data error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Query error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Security error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Remote Connection error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

File Handling error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Dispatch error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

TCP/IP error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Chapter 7 Indexing XML Documents . . . . . . . . . . . . . 137

Indexing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Implementation summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Style Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Configuring style files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Configuring the style.xml file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

style.xml command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

style.ufl file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

style.dft file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Indexing XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Indexing using mkvdk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Searching using rcvdk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Chapter 8 Verity Spider . . . . . . . . . . . . . . . . . . . . . . . . 145

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Supports Web standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Restart capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

State maintenance through a persistent store . . . . . . . . . . . . . . . . . . . . . . . 146

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Verity Spider Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

The Verity Spider command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Using a command file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Command-line option reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Core Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Processing Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Networking Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Paths and URLs Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Content Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Locale Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

viii Contents

Logging Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Maintenance Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Setting MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Syntax restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

MIME types and Web crawling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

MIME types and file system indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Indexing unknown MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Known MIME types for file system indexing . . . . . . . . . . . . . . . . . . . . . . . . 183

Chapter 9 Managing Verity Collections with the

mkvdk Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Overview of the Verity mkvdk Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

mkvdk syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Getting Started with the Verity mkvdk Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Steps for building a collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Collection setup options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

General processing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Date format options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Messaging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Message types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Document processing options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Bulk Submit Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Using bulk insert and delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Collection Maintenance Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Examples: Maintaining collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Deleting a Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Optimization Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

About squeezing deleted documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

About optimized Verity databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Performance tuning options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Chapter 10 Verity Troubleshooting Utilities . . . . . . . 199

Overview of Verity Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Note on collection types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Using the Verity rcvdk Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Starting rcvdk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Attaching to a Collection Using rcvdk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Basic searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Viewing Results of the rcvdk Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Displaying more fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Contents ix

Using the Verity didump Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Viewing the word list with didump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Viewing the zone list with didump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Viewing the zone attribute list with didump . . . . . . . . . . . . . . . . . . . . . . . . 208

Using the Verity browse Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Using menu options with the browse utility . . . . . . . . . . . . . . . . . . . . . . . . 209

Displaying fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Using the Verity merge Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Merging collections using the merge utility . . . . . . . . . . . . . . . . . . . . . . . . . 211

Splitting collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Verity VDK Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Generic error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Usage error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Runtime error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Data error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Query error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Licensing error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Security error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Remote connection error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Filtering error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Dispatch error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Part IV ColdFusion High-Availabilty . . . . . . . . 219

Chapter 11 Scalability and Availability Overview . . . 221

What is Scalability? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Load management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Issues Affecting Successful Scalability Implementations. . . . . . . . . . . . . . . . . . . 225

Designing and coding scalable applications . . . . . . . . . . . . . . . . . . . . . . . . 225

Avoiding common bottlenecks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

DNS effects on Web site performance and availability . . . . . . . . . . . . . . . 228

Load testing your Web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

What is Web Site Availability? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Availability and reliability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Common failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

A Web site availability scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Failover considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Techniques for Creating Scalable and Highly Available Sites . . . . . . . . . . . . . . . 239

What is clustering? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Hardware-based clustering solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Software-based clustering solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Combining hardware and software clustering solutions . . . . . . . . . . . . . . 244

x Contents

Chapter 12 Configuring ColdFusion Clusters . . . . . . 245

Introduction to ClusterCATS Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ClusterCATS Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ClusterCATS Explorer (Windows only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

ClusterCATS Web Explorer (UNIX only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

ClusterCATS Server Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

btadmin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating Clusters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating clusters in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Creating clusters in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Removing Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Adding Cluster Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Adding cluster members in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Adding cluster members in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Removing Cluster Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Removing cluster members in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Removing cluster members in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Server Load Thresholds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Configuring load thresholds in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Configuring load thresholds on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Session-Aware Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Enabling session-aware load balancing on Windows . . . . . . . . . . . . . . . . 277

Enabling session-aware load balancing on UNIX . . . . . . . . . . . . . . . . . . . . 278

Configuring ColdFusion probes in Windows . . . . . . . . . . . . . . . . . . . . . . . . 280

Configuring ColdFusion probes in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Load-Balancing Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Using Cisco LocalDirector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Using third-party load-balancing devices . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Administrator Alarm Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Configuring administrator alarm notifications on Windows . . . . . . . . . . 297

Configuring administrator alarm notifications on UNIX . . . . . . . . . . . . . . 297

Administrator E-mail Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Configuring administration e-mail options on Windows . . . . . . . . . . . . . 300

Configuring administration e-mail options on UNIX . . . . . . . . . . . . . . . . . 300

Administrating Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Configuring authentication on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Configuring authentication on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Contents xi

Chapter 13 Maintaining Cluster Members . . . . . . . . . 307

Understanding ClusterCATS Server Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Changing Active/Passive Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Changing active/passive settings in Windows . . . . . . . . . . . . . . . . . . . . . . . 309

Changing active/passive settings in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Changing Restricted/Unrestricted Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Restricting/unrestricting servers in Windows . . . . . . . . . . . . . . . . . . . . . . . 311

Restricting/unrestricting servers in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Using Maintenance Mode (Windows only). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Updating an Existing Cluster Member (Windows only). . . . . . . . . . . . . . . . . . . . 317

Resetting Cluster Members. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Resetting cluster members on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Resetting cluster members on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Chapter 14 ClusterCATS Utilities . . . . . . . . . . . . . . . . 321

Using btadmin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Using btadmin on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Using btadmin on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

Using bt-start-server and bt-stop-server (UNIX only) . . . . . . . . . . . . . . . . . . . . . 325

Using btcfgchk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

btcfgchk DNS errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Using hostinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Using sniff. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Chapter 15 Optimizing ClusterCATS . . . . . . . . . . . . . 333

ClusterCATS Dynamic IP Addressing (Windows only) . . . . . . . . . . . . . . . . . . . . . 334

Understanding static and dynamic IP address configurations . . . . . . . . 334

Benefits of ClusterCATS dynamic IP addressing . . . . . . . . . . . . . . . . . . . . . 335

Setting up maintenance IP addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Enabling ClusterCATS dynamic IP addressing . . . . . . . . . . . . . . . . . . . . . . 337

Using Server Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Static versus ClusterCATS dynamic IP addressing . . . . . . . . . . . . . . . . . . . 340

Windows domain controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

xii Contents

Configuring Load-Balancing Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Overview of metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Load types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Output variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Troubleshooting the load-balancing metrics . . . . . . . . . . . . . . . . . . . . . . . . 343

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

About This Book

Advanced ColdFusion Administration is intended for anyone who needs to configure databases for the ColdFusion server.

Contents

• Intended Audience...................................................................................................xiv

• New Features............................................................................................................ xiv

• Developer Resources.................................................................................................xv

• About ColdFusion Documentation............................................. ....... ...... ....... ...... .xvi

• Getting Answers ......................................................................................................xvii

• Contacting Macromedia........................................................................................xviii

xiv About This Book

Intended Audience

Advanced ColdFusion Administration is intended for anyone who needs to perform ColdFusion server management tasks, such as configuring advanced security or managing clustered servers.

New Features

The following table lists the new features in ColdFusion 5:

Benefit Feature Description

Breakthrough productivity

Powerful business intelligence capabilities

Enhanced performance

User-defined functions Create reusable functions to

accelerate development.

Query of queries

Easily integrate data from heterogeneous sour ce s by merging and querying data in memory using standard SQL.

Server analysis and troublshooting

Quickly detect and diagnose server errors with built-in server reporting and the new Log File Analyzer.

Charting engine

Create professional-quality charts and graphs from queried data without leaving the ColdFusion environment.

Enhanced V erity K2 fu ll-text search

Index and search up to 250,000 documents and enjoy greater performance.

Reporting interface for Crystal Reports 8.0

Create professional-quality tabular reports from queried data and applications.

Core engine tuning

Take advantage of dramatically improved server performance and reduced memory usage to deliver faster, more scalable applications.

Incremental page delivery

Improve response time by delivering page output to users as it is built.

Wire protocol database drivers

Deliver high-performance ODBC connectivity using new drivers.

Developer Resources xv

Benefit Feature Description

Easy managment

Application deployment services

Effortlessly and reliably deploy, archive, or restore entire applications using ColdFusion archive files.

Enhanced application monitoring

Keep track of server performance and availability with customizable alerts and recovery.

SNMP support

Monitor ColdFusion applicatio ns from enterprise management systems.

Expanded integration

Expanded Linux support

Deploy on additional Linux distributions, including SuSE and Cobalt.

Enhanced hardware load balancer integration

Apply optimized, agent-based support for hardware load balancers, including new support for the Cisco CSS 11000.

Enhanced COM support

Experience easier integration with COM components.

Developer Resources

Macromedia Corpo r a tion is comm itte d to set tin g the stan da r d fo r custom e r suppo rt in developer education, tech nical supp o rt, and pro fes sio nal services . T he Web site is designed to give you quick access to the entire range of online resources, as the following table describes.

Resource Description URL

Macromedia Web site General information about Macromedia

products and services

Information on ColdFusion

Technical Support Professional support progra ms that

ColdFusion Support Forum

Detailed p roduct information on

ColdFusion and related topics

Macromedia offers

Access to experienced ColdFusion

developers through participation in the

Online Forums, where you can post

messages and read replies on many

subjects relating to ColdFusion

www.macromedia.com/

www.coldfusion.com/products/ coldfusion/

www.coldfusion.com/support/

http://forums.allaire.com/coldfusion/

xvi About This Book

Resource Description URL

Installation Support Support for installation-related issues

for all Macromedia products

Professional Education Information about classes, on-site

training, and online courses offered by

Macromedia

Developer Community All the resources that you need to stay

on the cutting edge of ColdFusion

development, including online

discussion groups, Knowledge Base,

technical papers, and more

ColdFusion Dev Center Development tips, articles,

documentation, and white papers

Macromedia Alliance Connection with the growing network of

solution providers, applica tion

developers, resellers, and hosting

services creating solutions with

ColdFusion

www.coldfusion.com/support/ installation/

www.coldfusion.com/developer/ training.cfm

www.coldfusion.com/developer/

www.coldfusion.com/developer/ referencedesk/

www.coldfusion.com/partners/

About ColdFusion Documentation

ColdFusion documentation is designed to provide support for ColdFusion developers and ColdFusion Server administrators. The print and online versions are organized to allow you to quickly lo cate the information that you need. The ColdFusion online documentation is provided in HTML and Adobe Acrobat formats.

Printed and online documentation set

The ColdFusion documentation set consists of the following titles.

Book Description

Installing and Configuring ColdFusion Server

Advanced ColdFusion Administration

Developing ColdFusion Applications

Describes system installation and basic configuration for Windows NT, Windows 2000, Solaris, and Linux

Describes how to connect your data sources to the ColdFusion Server, configure security for your applications, and how to use ClusterCATS to manage scalability, clustering, and load-bal ancing for your site

Describes on how to ColdFusio n Server to develop yo ur dynamic Web applications, including retrieving and updating your data, using structures, and forms

Getting Answers xvii

Book Description

CFML Reference The online-only ColdFusion Reference provides descriptions,

syntax, usage, and code examples for all ColdFusion tags, functions, and variables

CFML Quick Reference

A brief guide that shows the syntax of ColdFusion tags, functions, and variables

Viewing online documentation

All ColdFusion documentation is available online in HTML and Adobe Acrobat PDF formats. To view the HTML documentation, open the following URL on the We b server running ColdFusion: http://localhost/cfdocs/dochome.htm.

ColdFusion documentation in Acrobat format is available on the ColdFusion product CD-ROM and for download from the ColdFusion web site: http://

www .coldfusion.com.

ColdFusion Studio documentation

ColdFusion Studio contains a wide range of online assistance, including a complete collection of ColdFusion documentation. T o vie w ColdFu sion online documentation from within ColdFusion Studio, click the Help resource tab. You will see an expandable list of documents about ColdFusion Server and ColdFusion Studio, as well as other information that relates to Web programming:

ColdFusion Studio online documentation is searchable and you can bookmark individual pages. For more information about using the Cold Fu sion S tud io interface , see the ColdFusion Studio documentation set.

Getting Answers

One of the best ways to solve particular programming problems is to tap into the vast expertise of the ColdFusion developer communities on the ColdFusion Forums. Other devel opers on th e forum can help y ou f igur e out ho w to do jus t abo ut a nythin g with ColdFusion. The search facility can also help you search messages from the previous 12 months, allowing you to learn how others have solved a problem that you might be facing. The Fo rums is a gr e at r es our ce for learning C oldF u sion, bu t it is also a great place to see the ColdFusion developer community in action.

xviii About This Book

Contacting Macromedia

Corporate headquarters

Technical support

Sales

Macromedia, Inc. 600 Townsend Street San Francisco, CA 94103

Tel: 415.252.2000 Fax: 415.626.0554

Web: www.macromedia.com Macromedia offers a range of telephone and Web-based

support options. Go to http://www.coldfusion.com/

support/ for a complete description of technical support

services. You can make postings to the ColdFusion Support Forum

(http://forums.coldfusion.com/DevConf/index.cfm) at any time.

Toll Free: 888.939.2545 Tel: 617.219.2100

Fax: 617.219.2101 E-mail: sales@macromedia.com Web: http://commerce.coldfusion.com/purchase/

index.cfm

Part I

Data Sources and Tools

This part describes data source management and introduces the ColdFusion Administrator tools. The fol lowing chapters are included:

Advanced Data Source Management ..................................................3

Administrator Too ls................. ............. ... ............. .. ............. .. ..............39

Chapter 1

Advanced Data Source Management

This chapter describes how to create and configure ColdFusion data sources for several databases using ODBC, OLE DB, and native drivers. It also describes how to use ColdFusion to create a database file in a cfquery and how to use connection string options.

For basic information on data sources and fo r information on ho w to connect to SQL Server, Access, and Oracle databases, see Installing and Configuring ColdFusion Server.

Contents

• About ColdFusion database drivers................................ ....... ...... ....... ...... ....... ...... ....4

• Using ColdFusion to Create a Data Source (UNIX only)........................................10

• Using Connection String Options............................................................................12

• Connecting to DB2 Databases.................................................................................15

• Connecting to dBASE/FoxPro Databases................................................................21

• Connecting to Excel Databases................................................................................24

• Connecting to Informix Databases..................................................... ...... ....... ...... ..26

• Connecting to Sybase Databases.............................................................................32

• Connecting to Text Databases..................................................................................35

• Connecting to Visual FoxPro Databases..................................................................37

4 Chapter 1 Advanced Data Source Management

About ColdFusion database drivers

ColdFusion uses ODBC, OLE DB, and native database drivers. For detailed information about ODBC drivers, see Installing and Configuring ColdFusion Server.

About OLE DB

OLE DB is a Microsoft specification for a set of interfaces designed to access data. Although ODBC is primarily used to access SQL data in a platform-independent manner, OLE DB is designed to access SQL and non-SQL data in an OLE Component Object Model (COM) environment.

Note

OLE DB is available only on Windows NT/2000.

ColdFusion developers can access a range of data stores through Microsoft OLE DB, including:

• MAPI-based data stores such as Microsoft Exchange and Lotus Mail

• Nonrelational data stores, such as Lotus Notes

• LDAP 2.0 data

• Data from OLE applications like word processors and spreadsheets

• Mainf rame data

• HTML and text files, flat-file data

For more information, including a list of provider vendors, visit the Microsoft OLE DB site at http://www.microsoft.com/data/oledb/.

About OLE DB providers

Before ColdFusion can use OLE DB to access data stores, you must install an OLE DB provider, available from third-party vendors. The provider software handles data processing in response to requests from the OLE DB consumer, which in this case is ColdFusion.

ColdFusion uses an OLE DB provider to access an OLE DB data source. An OLE DB provider is a COM component that accepts calls to the OLE DB Application Programming Interface (API) and processes that request against the data source.

You can often achieve sultry performance levels by running an OLE DB provider, instead of an ODBC driver, to process SQL. This depends on how the provider implements the data call. Some providers route OLE DB calls through the ODBC Driver Manager, while others go directly to the data bas e. Provi ders tha t g o d ir e ctly to the database are akin to native drivers in providing an alternative to ODBC. Providers are available for all the major relational DBMS products as well as the data stores previously mentione d.

About ColdFusion database drivers 5

Installing the OLE DB provider

Before you configure an OLE DB data source, you must have installed a recent version of the Microsoft Data Access Components (MDAC). MDAC includes two OLE

DB providers—SQLOLEDB and MSDASQL. For Access d atabases, Microsoft makes available a Jet provider. For SQL Server, Microsoft offers MSDASQL and SQLOLEDB providers.

During its installation process, ColdFusion attempts to detect the MDAC version on your computer. If MDAC is absent or the identified version is 2.0 or earlier, ColdFusion installs MDAC version 2.5 and restarts the installation process. If you install MDAC on a Windows NT system, you get the MSDASQL and SQLOLEDB providers.

For updated versions of MDAC, visit the Microsoft Universal Data Access Download Page at http://www.microsoft.com/data/download.htm/.

Note

Before you install MDAC, stop all unnecessary services, such as Web servers, virus scanning programs, or mail servers.

You should be aware of the following characteristics in how ColdFusion handles OLE DB:

• The initial driver drop-down list box does not display all of the installed OLE DB providers. If you are creating a data source using a provider other than SQLOLEDB or Jet, such as MSDASQL or a MERANT OLE DB driver, you must select other from the drop-down list box.

• No matter which provider you select from the drop-down list box, you must still retype its name in the Provider field.

• When using MSDASQL, you must have an ODBC data source already defined for the database. Enter this ODBC DSN in the ProviderDSN text box.

6 Chapter 1 Advanced Data Source Management

The following procedure describes how to configure an OLE DB data source to a Microsoft SQL Server database on Windows NT, using SQLOLEDB as the provider.

To configure an OLE DB data source:

1Open the ColdFusion Administrator. 2 Under Data Sources, click OLE DB.

The OLE DB Data Sources page displays any existing OLE DB Data Source Names that are available to ColdFusion:

3 Enter a name for the new data source and select an OLE DB Provider from the

drop-down list.

Note

Do not name a ColdFusion data source Registry or Cookie, as these words are reserved for use by ColdFusion.

4Click Add.

The Create OLE DB Interface Data Source page displays:

5 (Optional) Enter a description.

About ColdFusion database drivers 7

6 Enter the following connection information:

• If SQLOLEDB is the provid er Enter SQLOLEDB a s the Provider, specify the

Server that hosts the database, and specify the name of the Default Database.

Note

For the Server field, if the database is a local SQL Server database, enclose the word local in parentheses: (local).

• If Microsoft Jet is the provider Enter Microsoft.Jet.versionnumber as the

Provider (such as Microsoft.Jet.OLEDB.4.0), and specify the path to the Database File.

• If you are using another provider Enter its name as the Provider. Be aware

that MSDASQL requires a predefined ODBC data source for the database to which you will connect. Enter the name of the ODBC data source in the Provider DSN field.

8 Chapter 1 Advanced Data Source Management

7 Click CF Settings and specify any ColdFusion-specific settings. For example,

enter a username and password if required for the data source.

Note

The omission of required username and password information is a common reason why a data source fails to verify.

8 Click Create to create the new data source.

ColdFusion automatically verifies that it can connect to the data source.

If ColdFusion cann ot verify the data sou rce, the S tatu s d isp lays a s Failed. You c an

cfquery against the failed data source to get more detailed information

run a about the problem. You also can try embedding a username and password into

cfquery tag to see if the query works.

the

About ColdFusion database drivers 9

If you are creating a UNIX data source, you might need to set environment variables for your database client library by editing the ColdFusion start script in <installdir>/coldfusion/bin. F or detailed information about editing the ColdFusion start script for your particular database, see the section about your database.

About native drivers

The Enterprise Edition of ColdFusion Server includes support for DB2, Informix, Sybase System 11 through Sybase Adaptive Server 12.0, and Oracle 7.3.4, 8.0, and 8i

databases through native database drivers on both Windows NT and UNIX platforms.

You might consider using native database drivers for the following reasons:

• Native drivers tend to offer better performance than their ODBC counterparts.

• Some stored procedure functionality is only available through native drivers. For

example, you must use an Oracle native driver to use packages.

Software requirements for native drivers

Before you can use the ColdFus ion native database drivers, you must install additional client software. Also, you must install the database client software and ColdFusion Server software on the same server.

The following table describes requirements for each database and each supported platform:

Database Client Software For more information

Oracle Oracle 7.3.4, Oracle 8.0.x

or Oracle 8.1.6 or higher

Sybase Sybase Open/Client

1 1.1 .1, 11.9.2 or 12.0

Informix Informix 2.50 SDK or

higher

IBM DB2 IBM DB2 Client

Application Enabler version 5 or 6

Installing and Configuring ColdFusion Server

“Connecting to Sybase Databases,” on page 32

“Connecting to Informix Databases,” on pag e 26

“Connecting to DB2 Databases,” on page 15

10 Chapter 1 Advanced Data Source Management

Using ColdFusion to Create a Data Source (UNIX only)

The MERANT ODBC drivers that ship with all UNIX versions of ColdFusion include a FoxPro 2.5/dBASE driver. You can use the FoxPro 2.5/dBASE driver to create a database file in a Oracle, Informix, Sybase, or DB2 database.

Note

See the MERANT DataDirect ODBC Reference for details about SQL statements used for flat-file drivers. The default location of this reference on UNIX machines is: <installdir>/coldfusion/odbc/doc/odbcref.pdf. On Win32 machines, the default location is: <installdir>/cfusion/bin/odbcref.pdf.

You need to create tables in a data source called newtable.

T o create a table in the data source:

1 Create the newtable data source in the ColdFusion Administrator, specifying the

MERANT dBASE/FoxPro ODBC driver. If you do not create the data source, you receive an error when you try to execute

this page.

2 Use the following code to generate these fields in the newtable data source:

cfquery with standard SQL syntax even if you do not have an

Field Data type

Bean_ID numeric Name char Price char Date date Descript char

<TITLE>dBASE Table Setup</TITLE> </HEAD> <BODY>

<!--Before running this code, you need to create the

newtable data source in the ColdFusion Administrator, specifying the MERANT dBASE/FoxPro ODBC driver.

--->

CREATE TABLE Beans1 (

Bean_ID numeric(6), Name char(50), Price char(50),

Using ColdFusion to Create a Data Source (UNIX only) 11

Date date,</P> Descript char(254))

</cfquery>

INSERT INTO Beans1 VALUES (

1,</P> ’Kenya’, ’33’, {ts ’1999-08-01 00:00:00.000000’}, ’Round, rich roast’)

</cfquery>

INSERT INTO Beans1 VALUES (

2, ’Sumatra’, ’21’, {ts ’1999-08-01 00:00:00.000000’}, ’Complex flavor, medium-bodied’)

</cfquery>

INSERT INTO Beans1 VALUES (

3, ’Colombia’, ’89’, {ts ’1999-08-01 00:00:00.000000’}, ’Deep rich, high-altitude flavor’)

</cfquery>

INSERT INTO Beans1 VALUES (

4,</P> ’Guatamala’, ’15’, {ts ’1999-08-01 00:00:00.000000’}, ’Organically grown’)

</cfquery>

CREATE UNIQUE INDEX Bean_ID on Beans1 (Bean_ID) </cfquery>

SELECT * FROM Beans </cfquery>

#Bean_ID# #Name#<br> </cfoutput>

</BODY> </HTML>

12 Chapter 1 Advanced Data Source Management

Using Connection String Options

ColdFusion 5 allows you to specify a connection string for ODBC data sources. You can do this programmatically or in the ColdFusion Administrator.

About the connection string

You can use the connection string to do the following tasks:

• Specify connection attributes that cannot be defined in the odbc.ini settings.

• Override odbc.ini settings.

• Make ODBC connections dynamically when there is no data source defined in

the odbc.ini settings.

Some ODBC data sources let you pass driver-specific options. A database administrator (DBA) can use t hese options to see whic h applications are connected to the database server, and to identify who is running those applications. For example, many applications that connect to Microsoft SQL Server pass the attribue-value pairs APP="appname" and WSID="work station id" when connecting.

Consider the following the APP and WSID attributes

<cfquery

name="getInfo" datasource="2Northwind" dbtype="ODBC"

connectstring="DRIVER={SQL SERVER}; SERVER=(local); UID=sa; PWD=; DATABASE=Northwind;

APP=ColdFusion5;WSID=Workstation_Moe"

SELECT *

FROM shippers </cfquery>

cfquery, which specifies values in the connection string for

The APP and WSID values are readily available when you run the above query. A SQL Server DBA can use Profiler to view this information in a trace:

Using Connection String Options 13

Limiting DSN definitions

Another use of the connect string feature is to limit data source name (DSN) definitions. For example, if you are connecting to a server that has multiple databases defined, you might not want to define a ColdFusion DSN for each database. Instead, you can now use the connec tion string to supply the d atabase name for the single DSN that you defined for th at server. The connection string allows ColdFusion to support ODBC connections for databases that lack a data source definition in the odbc.ini settings. All information required by the particular ODBC driver to connect must be specified in the connection string.

Changes to the ColdFusion Administrator

The Settings page in the ColdFusion 5 Administrator includes a Connection String option to support the connect string feature. You can specify a connect string in the ColdFusion settings for an ODBC data source. If you specify a connectstring attribute for a tag that supports the attribute, then it overrides the Administrator setting.

Changes to CFML tags

A new connectstring attribute is now available in the following CFML tags:

•

cfquery

• cfinsert

• cfupdate

• cfstoredproc

• cfgridupdate

Using a connect string in a cached query

As with other query settings, when a query is cached, the connect string setting becomes part of that cached query. The cache is purged only if the query is changed, for example, if you change the data source name.

Use dynamic for dbtype attribute

When connecting to data sources dynamically with a connection string, the dbtype attribute for tags making dynamic connections is set to feature allows a C oldF u si on appli cation to run on multiple se rvers without r e quiring odbc.ini Regist ry entries on each se rver. You must specify all info rmation r equir e d b y the ODBC driver to connect in the using the default dbtype (that is, dbtype=odbc), you can use the attribute to provide additional connection information or override connection information that is specified in the DSN.

connectstring attribute. For ODBC connections

dbtype=dynamic. This

connectstring

14 Chapter 1 Advanced Data Source Management

Example

The following code is a dynamic connection. There is no data source definition in the odbc.ini settings.

<cfquery name = "DATELIST" dbtype=dynamic blockfactor=100 connectstring="DRIVER={SQL SERVER}; SERVER=(local); UID=sa; PWD=; DATABASE=pubs"> SELECT * FROM authors </cfquery>

For dynamic connections, the ColdFusion Administra tor Maintain Connect defa ult value is enabled. If you need to change this, you must use regedit to add a pseudo __DYNAMIC__ key in the ColdFusion/CurrentVersion/DataSources Registry key and specify a Maintain Connect value of 0.

Connecting to DB2 Databases 15

Connecting to DB2 Databases

On Windows and UNIX, ColdFusion lets you acc e ss DB2 databases usin g ODBC and native drivers.

Configuring DB2 options (Windows)

If you install C oldFu sion o n a W indo ws server, you can configure a DB2 da tabase as a ColdFusion data source using ODBC, OLE DB, or a native driver. For information about using OLE DB with ColdFus ion data sources, see “About OLE DB” on page 4.

Native driver: DB2 Universal Database 5.2/6.1 options (Windows)

The following table describes ColdFusion options for the DB2 Universal Database

5.2/6.1 native driver:

Option Description

Data Source Name A name for your data source. Description Descriptive information about the data source. Database Alias The DB2 database name.

Note

Although native driver performance is usually superior to ODBC performance, you can connect to DB2 via ODBC on Windows. To do so, create the data source in the Windows ODBC Data Source Administrator, using the IBM ODBC driver. In the ColdFusion Administrator, configure any ColdFusion-specific settings, such as a username and password.

Configuring DB2 options (UNIX)

If you install ColdFusion Server Enterprise Edition on a Solaris or Linux server, you can configure DB2 ColdFusion data sources using a native driver. On Solaris, you can also use a MERANT ODBC driver.

Native driver: DB2 Universal Database 5.2/6.1 options (Solaris, Linux)

ColdFusion native drivers are the same for Windows NT and UNIX. For the ColdFusion options for the DB2 Universal Database 5.2/6.1 native driver, see the table in “Native driver: DB2 Universal Database 5.2/6.1 options (Windows)” on page 15.

16 Chapter 1 Advanced Data Source Management

ODBC: DB2/6000 options (Solaris)

The following table describes ColdFusion options for the MERANT IBM DB2/6000 ODBC driver:

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Database Name The name of the DB2/6000 database. Cursors Preserve cursors at the end of each transactio n. Select this

option if you want cursors to be held at the current position when the transaction ends. Do in g so can imp ac t the performance of your database operations.

Configuring system and services files (UNIX)

You must add some settings that are necessary for the Client Enabler software libraries to work.

T o configure system and services files:

1 Add the following settings to the /etc/system file:

set msgsys:msqginfo_msgmax = 65535 set msgsys:msqginfo_msgmnb = 65535 set msgsys:msqginfo_msgseg = 8192 set msgsys:msqginfo_msgssz = 16

2 You must restart the server for the settings to take effect. 3 Add the following settings to the /etc/services file:

dbserver1 50000/tcp # DB2 connection service port

• dbserver1 is the Connection Service name.

• 50000 is the port number for the Connection Port. The port number used on

the client must match the port number used on the server.

• tcp is the communication protocol that you are using.

If you are planning on supporting a UNIX client that is using Network Information Service (NIS), you must update the services file located on your NIS master server.

Installing and Configuring DB2 Client Enabler (UNIX)

Before you can c r e at e a ColdFusion data sou rce with the DB2 nati ve drive r, you must install the DB2 version 5.2 Client Enabler Software and create an instance. You can find the client software on the DB2 version 5.2 Software Development Kit CD-ROM. Refer to the documentation that comes with the software for details.

Connecting to DB2 Databases 17

You perform the following steps:

• Set environment variables.

• Catalog a TCP/IP node.

• Catalog the database.

• Test the connection.

You should be familiar with DB2 to successfully complete this process. Gather the following information before you begin:

• Host name where the DB2 database server resides

• Node name

• Database name

• Datab ase alias

• Database user id and password

• Service name from the /etc/services file on client and host

Set environment variables

After you install the Client Enabler, you need to run some scripts to set up your environment. You must also set environment variables to run the command line tool db2.

Look in the <installdir>/sqllib directory for the db2profile and db2cshrc scripts.

• For sh or ksh, run: <installdir>/sqllib/db2profile

• For csh, run: source <installdir>/sqllib/db2cshrc

Catalog a TCP/IP node

You must add an entry to the client’s node directory to describe the remote node. This entry specifies the chosen alias (node_name), the hostname (or ip_address),

and the servicename (or port_number) that the client will use to access the remote server.

To catalog a TCP/IP node:

1 Run the db2 command line utility db2. 2 At the db2 prompt, enter the following:

db2 => catalog tcpip node dbserver1node remote db2unixhost server

db2server1

db2 =>terminate

Catalog the database

Before a client application can access a remote database, the database must be cataloged on the server node and on any client nodes that will connect to it. When

18 Chapter 1 Advanced Data Source Management

you create a database, it is automatically cataloged on the server with the database

database_alias) the same as the database name (database_name). The client

alias ( uses the information in the database directory, along with the information in the node directory, to establish a connection to the remote database.

T o add an entry to the client’s database node directory:

1 Run the db2 command line utility db2. 2 At the db2 prompt, enter the following:

db2 => catalog database sample as sample1 at node dbserver1node db2 =>terminate

Test the connection

You are now ready to test the connection with a known table. The following procedure uses a table that is installed with DB2.

To test the connection:

1 Run the DB2 command line utility db2. 2 At the db2 prompt, enter the following:

db2 => connect to sample1 user username using password db2 => select * from employee db2 => terminate

Data source and start script settings for DB2 (UNIX)

This section describes changes that you must make to the ColdFusion start script. You must set the following environment variables in the <installdir>/coldfusion/

bin/start script file:

# DB2 environment variables DB2INSTANCE=db2inst1 INSTHOME=/export/home/db2inst1 # Set library search path # # NOTE: Add your database client library directory to the FRONT of this

# # Example: # LD_LIBRARY_PATH=/usr/dt/lib:/lib:/usr/openwin/lib:$INSTHOME/sqllib/

# # This is the list of variables that ColdFusion will see # Add any special Database environment variables here # VAR_LIST="LD_LIBRARY_PATH DB2INSTANCE INSTHOME CFHOME SYBASE

list

lib:$CFHOME/lib

ORACLE_HOME INFORMIXDIR INFORMIXSERVER II_SYSTEM"

Connecting to DB2 Databases 19

Data source settings for the ColdFusion DB2 native driver

The data source setting for the native driver must point to the database name and include a valid DB2 login name and password. The catalog procedures described in the previous section make the connection through the DB2 Client Enabler software.

DB2 binding and privileges for ODBC (UNIX)

Access to DB2 requires that you bind and grant privileges to the MERANT bind files. To locate the bind files, enter the DB2 command line processor by typing shell prompt. The bind files are located in the <installdir>/coldfusion/odbc/db2 directory. Before you proceed with the steps in this section, set up yo ur en vir o nm e nt by running the db2profile or db2csh script as described in “Set envir onm en t variables” on page17.

To connect to your DB2 database:

1 From the DB2 command line processor, connect your DB2 database using the

following syntax:

db2=> CONNECT TO <database_name> USER <userid> USING <password>

2 Bind the MERANT SQL files to the database, using special options on the BIND

command, based on your installation. For a detailed list of BIND options, see the DB2 Command Reference.

db2 from a

To bind the MERANT SQL files to the DB2 database:

1 Enter the following commands:

db2=> BIND iscsso.bnd blocking all grant public db2=> BIND isrrso.bnd blocking all grant public db2=> BIND isurso.bnd blocking all grant public db2=> BIND iscswhso.bnd blocking all grant public db2=> BIND isrrwhso.bnd blocking all grant public db2=> BIND isurwhso.bnd blocking all grant public

2 Enter quit to exit the DB2 command processor.

Executing a DB2 stored procedure (Windows, UNIX)

Follow these steps to execute a DB2 stored procedure through ColdFusion.

T o execute a DB2 stored procedure:

1 Use the PREP command to precompile the source file; for example: PREP

C:\TEMP\OUTSRV.SQC. When this command executes (barring any errors), you should have a C source

file; for example, OUTSRV.C.

2 Compile and link the .C file generated in step 1 to get the dll file.

20 Chapter 1 Advanced Data Source Management

3 Place the dll file generated in step 2 into the appropriate directory on the server.

For example, put the file on a server called DB 2SERVER into the C:\sqllib\function\ folder. You could also put it into the C:\sqllib\function\unfenced\ folder.

4 Run a CREATE PROCEDURE statement to register your stored procedure.

• The CREATE PROCEDURE statement creates a row in the database catalog

(syscat.procedures table), making it visible to client applications, including ColdFusion Server.

• The stored procedure’s name is what you called it in your SQC file. The

following example calls the stored procedure outsrv.

• The create procedure statement looks li ke this:

CREATE PROCEDURE server1 (OUT sal double, IN salind integer) EXTERNAL NAME ’outsrv!outsrv’ LANGUAGE C DETERMINISTIC PARAMETER STYLE DB2DARI;

5 Grant users who need to run the stored proced ure permission to execute it:

GRANT EXECUTE ON PACKAGE server1 TO PUBLIC;

Example

The following example demonstrates a CFSTOREDPROC tag that calls the stored procedure named outsrv. The actual stored procedure name and the password parameter are case sensitive.

<CFSTOREDPROC PROCEDURE="outsrv"

DATASOURCE="DB2SERVER" USERNAME="DB2" PASSWORD="DB2">

<CFPROCPARAM TYPE="OUT"

CFSQLTYPE="CF_SQL_DOUBLE" VARIABLE="FOO" NULL="NO">

<CFPROCPARAM TYPE="IN"

CFSQLTYPE="CF_SQL_INTEGER" VALUE="0" NULL="NO">

</CFSTOREDPROC>

Connecting to dBASE/FoxPro Databases 21

Connecting to dBASE/FoxPro Databases

On Windows and UNIX, ColdFusion lets you access dBASE/FoxPro databases using ODBC drivers.

Note

Because dBASE and FoxPro databases are configured identically in the ColdFusion Administrator, they are discussed together in this section. For information on connecting to Visual FoxPro data ba ses, see “Connecting to Visual FoxPro Databases” on page37.

Configuring dBASE/FoxPro options (Windows)

If you install ColdFusion on a Windows server, you can configure a dBASE/FoxPro database as a ColdFusion data source using ODBC or OLE DB. For information about using OLE DB w ith ColdFusion data sources, see “About OLE DB” on page 4.

ODBC: Microsoft dBASE/FoxPro Driver options (Windows)

The following table describes ColdFusion ODBC options for dBASE/FoxPro data sources. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Database Directory The path dBASE database that you want to use as an ODBC

data source.

Database Version Enter the version number of the dBASE or FoxPro database

that you want to use: dBASE versions III, IV, and 5.0 and FoxPro versions 2.0, 2.5, and 2.6.

Driver Settings Collating Sequence Determines the sequence in which

the fields sort. Page Timeout Specifies the period of time, in tenths of a

second, that an unused page remains in the buffer before being removed.

22 Chapter 1 Advanced Data Source Management

ODBC: MERANT dBASE/FoxPro Driver options (Windows)

The following table describes the ColdFusion ODBC options for MERANT dBASE/ FoxPro on Windows. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description A short description of the data source. Database Directory The name, including the complete path, of the database file

that you want to use as the ODBC data source.

Database Versi on The version num ber of the dBASE/Fox Pro dat abas e that you

want to use: Clipper, dBASE versions III, IV, V, and FoxPro versions 2.5, 3.0.

Data File Extension The file extension to use for data files. The default setting is

DBF. The setting cannot be more than three characters, and it cannot be one the driver already uses, such as MDX or CDX. The Data File Extension setting is used for all Create Table statements.

• Use international collating sequence Determines the order in which records display when you issue a Select statement with an Order By clause.

If you do not select this option, the driver automatically uses the ASCII sort order. This order sorts items alphabetically with uppercase letters preceding lowercase letters. For example, “A, b, C” sorts as “A, C, b.”

If you select this option, the driver uses the international sort order as defined by your operating system. This sort order is always alphabetic, regardless of case; the letters from the previous example would sort using as “A, b, C.”

Connecting to dBASE/FoxPro Databases 23

Configuring dBASE/FoxPro Driver options (UNIX)

If you install ColdFusion Server on a UNIX server, you can configure dBASE/FoxPro as a ColdFusion data source using the MERANT ODBC driver. The following table describes the ColdFusion ODBC options for dBASE/FoxPro (Solaris). You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description A short description of the data source. Database Directory The name, including the complete path, of the database file

that you want to use as the ODBC data source.

Database Versi on The version num ber of the dBASE/Fox Pro dat abas e that you

want to use. ColdFusion supports dBASE V, IV, and FoxPro v3.0.

Driver Settings • Use lowercase file extension (.dbf) Specifies whether

lowercase file extensions are accepted. Select this option to accept lowercase extensio ns. Clear this option to accep t only uppercase extensions.

• Use international collating sequence Determines the order in which records display when you issue a Select statement with an Order By clause.

24 Chapter 1 Advanced Data Source Management

Connecting to Excel Databases

On Windows, ColdFusion lets you access Microsoft Excel using ODBC or OLE DB. For information about using OLE DB with C oldFusion data sources, s ee “About OLE DB” on page 4.

ODBC: Microsoft Excel Driver options

The following table describes ColdFusion ODBC options for Microsoft Excel data sources. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Workbook/Directory The path and filename of the Excel workbook that you want

to use as the ODBC data source.

Version Enter the version number of the Excel workbook that you

want to use. The ColdFusion Administrator supports Excel versions 3, 4, 5, 97, and 2000.

Driver Settings Rows to Scan The number of rows to scan to determine

the data type of each column. The data type is determined by the maximum number of kinds of da ta fou nd. If dat a doe s not match the data type gue ss ed for the col um n, the dat a ty pe is returned as a NULL value.

Enter a number from 1 to 16 for the ro ws to sc an. Th e defau lt value is 16. If this setting is 0, all rows are scanned. A number outside the lim it returns an error.

Connecting to Excel Databases 25

ODBC: MERANT Excel Workbook Driver options

The following table describes ColdFusion ODBC options for data sources created with the MERANT Excel Workbook driver:

Option Description

Data Source Name A name for your data source. Description Descriptive information about the data source. Database Workbook A name that identifies the workbook file containing the Excel

database.

• International sort Determines the order in which records display w hen yo u iss ue a Se lect s ta tement with an Order By clause.

26 Chapter 1 Advanced Data Source Management

Connecting to Informix Databases

On Windows and UNIX, ColdFusion lets you access Informix databases using ODBC and native drivers. ColdFusion 5 supports Informix 7.3 and later, including Informix Dynamic Server.

If you install ColdFusion on a Windows server, you can configure an Informix database as a ColdFusion data source using ODBC, OLE DB, or a native driver. For information about using OLE DB with C oldFusion data sources, s ee “About OLE DB” on page 4.

Informix for Windows r equ ir e s v ersion 2.5 or later of either the I n formix-C onnect for Windows or the Informix Software Developer’s Kit for Windows. Informix for Solaris and HP-UX requires Informix-Client Software Developer’s Kit version 2.5 or later for UNIX.

Configuring Informix using ODBC

This configuration is now available on all platforms except Linux, which only supports the Informix Dynamic Server. The following table describes ColdFusion options for the MERANT Informix 7.x/9.x ODBC driver. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Database Name The name of the database to which you want to connect. Host Name • The name of the machine on which the Informix server

resides.

• Use Informix registry for Logon ID and Password Determines whether the server reads the

Logon ID and Password directly from the Informix registry.

Server Port Number (Informix Dynamic ODBC Server Driver only)

Service (Informix 7.x/

9.x Driver only)

Server Name The name of the Informix server as it appears in th e s qlh os t s

Protocol (Informix 7.x/

9.x Driver only)

The number of the server port. This will match the number entered in the services file for the Informix server.

The network services file. On Windows NT, the services file is located in

C:\winnt40\system32\drivers\etc. On UNIX, the file is located in /etc.

file. The network protocol.

Connecting to Informix Databases 27

Configuring Informix using the native driver

The configuration options for ColdFusion native drivers are the same for Windows NT and UNIX. The following table describes ColdFusion options for the Informix native driver. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your data source. Description Descriptive information about the data source. Default Database The name of the database to which you want to connect by

default. Server The name of the Informix server, including the full path. Host The name of the machine on which the Informix server

resides. Service The network services file.

On Windows NT, the services file is located in

C:\winnt40\system32\drivers\etc. On UNIX, the file is located

in /etc. Protocol The network protocol. Client Locale Specifies the language, territory, and code set that the client

application (ColdFus ion) uses to perform operatio ns that read

or write to the database. Database Locale Specifies the language, territory, and code set that the

Informix server ne eds t o inter pret local e-sensit ive d at a types . Translation DLL Leave blank.

Connecting to Informix data sources (UNIX)

Before you can connect to an Informix data source through ColdFusion, you must perform the following tasks:

1 Install the Informix client software. 2 Edit the following files: ColdFusion start script, SQLHOSTS, master NIS, and

$INFORMIXDIR/etc/onconfig.

3 Stop and restart ColdFusion Server.

Installing the Informix client software

The Informix client software does not ship with ColdFu sion, but you can do wnload it from the Informix Web site.

To install the Informix client software:

1 Download the appropriate client software from http://www.informix.com.

28 Chapter 1 Advanced Data Source Management

2 You must uncompress and/or untar this file into a separate subdirectory on your

server; for example: /opt/isdk.

This is the directory that you point to in the start script as INFORMIXDIR. 3 Run the script installclientsdk to install the client SDK. 4 Before you continue, ver if y that you can connect to the Informix server from a

client other than ColdFusion or with a utility such as iconnect.

Editing the ColdFusion start script

Add the following lines to the coldfusion/bin/start script:

# Informix client directory INFORMIXDIR=/opt/isdk;export INFORMIXDIR INFORMIXSERVER=alldevtli;export INFORMIXSERVER INFORMIXSQLHOSTS=$INFORMIXDIR/etc/sqlhosts;export INFORMIXSQLHOSTS LD_LIBRARY_PATH=/usr/dt/lib:/lib:/usr/openwin/lib:$CFHOME/lib LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$INFORMIXDIR/lib:$INFORMIXDIR/lib/esql

Editing the SQLHOSTS file

Add the following lines to the sqlhosts file:

dbserver nettype hostname service name alldev onipcshm alldev online0 alldevtli ontlitcp alldev turbo

The following table describes the code and its functions:

Code Description

dbserver This name matches the value in your Informix server /etc/onconfig

file, and also matches the INFORMIXSERVER environment

variable in your /coldfusion/bin/start script. nettype Determines what kind of network protocol to connect with. hostname The hostname of the server where the dat abase is . You can put the

IP address or hostname. service name The entry in the /etc/services or master NIS file for the port that

informix listens on. This can also be the port# for the service nam e,

such as 1526.

Editing the /etc/services or NIS file

Edit your /etc/services or master NIS file so that it contains a line like this:

turbo 1526/tcp

Connecting to Informix Databases 29

Editing the $INFORMIXDIR/etc/onconfig file

Edit the $INFORMIXDIR/etc/onconfig file so that it contains the following lines:

# System Configuration SERVERNUM 0 # Unique id corresponding to an OnLine instance DBSERVERNAME alldev # Name of default database server DBSERVERALIASES alldevtli # List of alternate dbservernames DEADLOCK_TIMEOUT 60 # Max time to wait for lock in distributed env. RESIDENT 0 # Forced residency flag (Yes = 1, No = 0)

Stopping and restarting ColdFusion services

After you complete all the steps in this sec tion, yo u must st op and r esta rt ColdF us ion services to reload the odbc.ini file.

Connecting to Informix through ODBC/CLI (Windows, UNIX)

The following setup information for Informix describes how to install and configure Informix client software for Windo ws and U NIX sys tem s. This information applies to native driver connec tivity and ODBC.

In order to install INFORMIX-CLI on Windows NT, you must have administrative privileges. Log on as administrator before performing the installation. Check with your database or network administrator for database server name, host name, correct protocol, and service name.

To install the client software:

1 Connect to the machine that is hosting the Informix software; for example, on

Windows: 2Run the 3Select Custom. 4 Select the Client connectivity: I-Connect 7.20, CLI 2.50.

\\machine1\infshare\informix\Informix_ODS_722.

setup.exe and click Next.

Modifying the services file entry

After the installation is complete you must modify your workstations’ Services File located in the

\windows\system\ for Windows 95/9 8. This en try is need ed for the c lient softwar e to

find the instance of the Informix service on your network. Make the following entry at the bottom of the file:

turbo 1526/tcp

Note

If necessary, check with your system administrator for the name of the service.

\winnt\system32\drivers\etc\ folder for Windows NT and

30 Chapter 1 Advanced Data Source Management

Configuring Informix SETNET32 settings

After you install the c lient software, you must configure your workstation to connect to the Informix databases. The following example assumes that the demo database that ships with I nformix is ins talled on th e I nf ormix server and the n ame of th e demo database is “stores7.” Using the Start button in the Windows taskbar, go to Programs/ Informix-CLI 32 and select Informix Setnet 32.

Configure the Informix Setnet32 utility as follows:

• Host Information:

Current Host = ts_informix Username = informix Password = informix

After you enter the values, click the Apply button.

• Server Information:

Informix Server = ol_ts_informix Hostname = ts_informix Protocol = olsoctcp Service Name = turbo

After you enter the values, click the Apply button.

• Environment:

INFORMIXDIR=C:\PROGRAM FILES\INFORMIX INFORMIXSERVER=ol_ts_informix INFORMIXSQLHOSTS=\\TS_INFORMIX

After you enter the values, click the Set button. Now you must create an ODBC data source using the ODBC Administrator in the

Windows ODBC Control Panel applet.

Adding the ODBC data source

Follow these steps to add the ODBC data source to your system.

To add the ODBC data source to your system:

1 Run the ODBC administrator in Control Panel. 2 Select the System DSN tab and click the Add button. 3 From the list of installed drivers, select Informix-CLI 2.5 (32 bit). 4 Enter the following information in the ODBC INFORMIX 7.2 Driver Setup dialog

box:

Data Source Name: Inf_ol7

Description: Demo Data

Database Name: stores7

Click the advanced button

Database List:

Default User Name: informix

Host Name: ts_informix

Service Name: turbo

Server Name: ol_ts_informix

Connecting to Informix Databases 31

Protocol Type: olsoctcp

Yield Proc: 1 - None

Cursor Behavior: 0 - Close

Enable Scrollable Cursors: 0 - Disabled

Get DB List From Informix: 1 - Yes

Now you have an Informix ODBC data source. You can use this in a ColdFusion application. It is important to note that you must provide a usernam e and password in the ColdFusion

cfquery tag.

Verifying the Informix data source

After you configure the client softwar e, verify the Inf_ol7 data source , as des cribed in Installing and Configuring ColdFusion Server, to make sure it is configured properly. If verification fails, check the system environment variables.

T o check the system environment variables:

1 Open the System Control Panel/system and click the Environment tab. In the

System Variables dialog box, the variable called InformixDir should point to the

Informix folder (for example,

add an InformixDir variable.

There should also be a variable called Path, which should include the path to the

Informix bin directory. If it does not, then modify the Path variable to include it. 2 After adding these variables, restart the system. If you are having trouble accessing a data source, and the data source resides on a

different machine, try running ColdFusion under an administrator account on the Web server.

Also, make sure that all ColdFusion services are running under a specific account (“This Account”, in the Control Panel) instead of the default system account. By default, ColdFusion installs to run under the system account.

C:\program files\informix). If it does not exist,

To change the Windows NT account that ColdFusion uses:

1Select Start > Settings > Control Panel > Services > Cold Fusion Application

Server > StartUp.

2 In the Log On As section, select This Account and browse to an administrator

account. Enter username and pass word values. 3 Reenter the Password and Chang e Password values. 4 Stop and Restart the ColdFusion Application Server service. 5 Repeat steps 1 through 4 for the ColdFusion Execu tive and ColdFusion IDE

services as well. After you reconfigure the account under which ColdFusion runs, you can retry

verification of the data source in the ColdFusion Administrator.

32 Chapter 1 Advanced Data Source Management

Connecting to Sybase Databases

On Windows and UNIX, ColdFusion lets you access Sybase databases using ODBC and native drivers. ColdFusion 5 supports Sybase 11 and later.

If you install ColdFusion on a Windows server, you can configure a Sybase database as a ColdFusion data source using ODBC, OLE DB, or a native driver. F or information about using OLE DB with ColdFus ion data sources, see “About OLE DB” on page 4.

ODBC: MERANT Sybase ASE Driver options

The following table describes ColdFusion options for the MERANT Sybase ASE ODBC driver. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Database Name The name of the database to which you want to connect. Server Name The name of the serve r conta ining the Sybase t ables that you

want to access. If no t su ppl ied , the initial default is the se rve r name in the DSQUERY environment variable. On UNIX, the name of a server from your $SYBASE/interfaces file.

Server Port The port number that the Sybase server monitors for

requests. The default value is 5000.

Network Library (Windows only)

Performance Row Limit (Fetch Array Size on W indows) The number of

The name of the network library. This specifies which network protocol to use (Winsock or NamedPipes). The default is Winsock. This option has no effect on UNIX; on UNIX, TCP/ IP is used.

rows the driver retrieves from the serve r fo r a fetch. Selecti ng this option can increase performance by reducing network traffic.

Create stored procedures (UNIX only) Determines whether stored procedures are created on the server for every call to SQLPrepare.

When enabled, stored procedures are created for every call to SQLPrepare. This setting can result in bad performance when processing static statements.

When disabled, the driver do es not cre ate stored procedure s. Disable database cursors for Select statements

Determines whether database cursors are used for Select statements. In some cases performance degradation can occur when performing large numbers of sequential Select statements because of the amount of overhead associated with creating database cursors .

Connecting to Sybase Databases 33

Native: Sybase 11 Driver options

To connect to Sybase System 11 databases on Windows NT and UNIX, you must first install the Sybase client software, Sybase Open Client version 11.1.0 with Update

11.1.1 applied.

T o use the native driver:

1 Install the Sybase Open Client version 11.1.0 (with Update 11.1.1 applied) client

software. 2 Verify the connection to the database using a tool like Sybase SQL Advantage. 3 Create the data source in the ColdFusion Administrator, Native Drivers page. 4 You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Server Enter the name of the server hosting the Sybase System 11

database.

Default Database Enter the name of the default database to use on the

specified server. Enable RAISERROR Select to obtain user-defined errors

from stored procedures and triggers.

Tips for connecting to Sybase System 11 (UNIX)

Keep the following tips in mind when you create Sybase ColdFusion data sources:

• You can set up the Sybase data source using the ColdFusion Administrator Data sources page.

• You need Sybase Open Client version 11.1.0 with Update 11.1.1 applied on your server. This software does not ship with ColdFusion.

• Check that the SYBASE environment variable is set up in the

script. Also check that the LD_LIBRARY_PATH has the $SYBASE/lib

start

directory in the beginning of its path; for an example, see “The /opt/coldfusion/ bin/start script” on page 34.

• Set up an entry in the inte rfaces file for the particul ar database that you want to connect to. The interfaces file is in the $SYBASE directory; for example,

or /work/sybase or wherever y ou install ed the S ybase client softw are . You

sybase

can use a Sybase utility called

sybinit on UNIX to update this file.

/opt/coldfusion/

/opt/

34 Chapter 1 Advanced Data Source Management

Note

If the Sybase database is on the same server as ColdFusion, make sure the $SYBASE environment variable that you set up in the ColdFusion start script is pointing to the Sybase client directory and not the Sybase server directory. Both of these directories contain an interfaces file.

The /opt/coldfusion/bin/start script

#!/bin/sh # start - setup environment and run Cold Fusion servers # This script should be run as root. # Run as root, we are able to start the system registry deamon # and then change to the Cold Fusion userid to start the servers # Set during install

CFHOME=/opt/coldfusion CFUSER=nobody

# Sybase Open Client directory

SYBASE=/work/sybclient11.1;export SYBASE

#II_SYSTEM=/home # Set library search path # NOTE: Add your database client library directory to the FRONT # of this list # Example: # LD_LIBRARY_PATH=$SYBASE/lib:/usr/dt/lib:/lib:/usr/openwin/lib: # $CFHOME/lib

LD_LIBRARY_PATH=$SYBASE/lib:/usr/dt/lib:/lib:/usr/openwin/lib:$CFHOME/

lib

# This is the list of variables that Cold Fusion will see # Add any special Database environment varaibles here

VAR_LIST=""LD_LIBRARY_PATH CFHOME SYBASE ORACLE_HOME INFORMIXDIR

INFORMIXSERVER II_SYSTEM""

After you complete all the steps in this sec tion, yo u must st op and r esta rt ColdF us ion services to reload the odbc.ini file.

Connecting to Text Databases 35

Connecting to Text Databases

On Windows and UNIX, ColdFusion lets you access text databases using ODBC drivers.

ODBC: Microsoft Text Driver options (Windows)

The following table describes ColdFusion ODBC options for Microsoft Text data sources. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description Descriptive information about the data source. Database Directory The directory that contains the text files. Extensions List Lists the filename extensions of the text files on the data

source. To use all files in the directory, enter *.*. To use only files with specific extensions, add each extension that you want to use.

ODBC: MERANT Text Driver options (UNIX)

The following table describes ColdFusion ODBC options for data sources created with the MERANT Text driver. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your data source. Description Descriptive information about the data source. Database Directory The directory that contains the text files. Extensions List Lists the filename extensions of the text files on the data

source. To use all files in the directory, enter *.*. To use only files with specific extensions, add each extension that you want to use.

36 Chapter 1 Advanced Data Source Management

Option Description

Table Type Select the default type of text file. ColdFusion supports

comma-separated , tab-separated, c ha rac ter-s eparated, fixed length, and stream t able types . The defau lt type is use d when creating a new table and opening an undefined table.

• Column Names in First Line Select this check box to use the first row of data in the text file as column names.

• International Sort Determines the order in which records display w hen yo u iss ue a Se lect s ta tement with an Order By clause.

Connecting to Visual FoxPro Databases 37

Connecting to Visual FoxPro Databases

On Windows, ColdFusion lets you access Microsoft Visual FoxPro databa ses using ODBC or OLE DB. For information about using OLE DB with ColdFusion data sources, see “About OLE DB” on page 4.

The following table describes ColdFusion ODBC options for Visual FoxPro data sources. You set these options when you configure a ColdFusion data source.

Option Description

Data Source Name A name for your ODBC data source. Description A short description of the data source. Database Info • Path The name, including the full path, of the

database to which you want to connect.

• Visual FoxPro Database Connect to a Visual FoxPro database (dbc file) and to all the tables and local views in the database.

• Free T a ble Di recto ry Connect to a directory of free tables, that is, tables not associated with any particular dbc file.

Driver Settings • Collating Sequence Select the collating sequence

that you want to us e. The colla ting sequenc e determine s the sequence in which the fields sort.

• Exclusive Select this check box so that the driver opens the Visu al FoxPro dat abase exc lusively wh en you access data using this data source. Other users cannot access the database or the tables in the database while the database is opened exclusively. Tables within the exclusively opened database are opened as shared.

This opti on is not valid when you se lect the Free Table Directory option.

• Fetch data in background Select this check box to fetch records in the background (progressive fetching). Otherwise, ColdFusion waits until all records in the result set are fetched.

38 Chapter 1 Advanced Data Source Management

Chapter 2

Administrator Tools

The tools provided with ColdFusion Administrator make it easy for you to share Web site files, analyze log files, and monitor Web site performance. This chapter introduces the Administrator Tools included with ColdFusion Server 5 and their benefits. The Co ldFusi on Ad ministra tor online H elp pr o vide s additional information about how to use these tools.

Contents

• Accessing the Administrator Tools...........................................................................40

• Features on the Tools Tab.........................................................................................41

40 Chapter 2 Administrator Tools

Accessing the Administrator Tools

ColdFusion Server 5 includes a series of administrative tools. To access these tools, open the ColdFusion Administrator and click the Tools tab.

On each page, you can click Help

Tools tab

Navigation bar

to get additional information about the tool settings.

The left navigation bar lists the tools provided with ColdFusion Administrator. Note that some of the tools provided are limited to the ColdFusion Server 5 Enterprise Edition.

Features on the Tools Tab 41

Features on the Tools Tab

The Tools tab offers several administrative tools that you can use to help manage Web site activities or the components that make up your Web site. All tools on this tab are organized into one of the following tool groups: Logs and Statistics, System Monitoring, and Archive and Deploy. Each tool group is outlined in the following sections.

Logs and Statistics tools

The Logs and Statistics tools are designed to help you configure ColdFusion logging settings, view and analyze log file content, and monitor your site performance. These tools include: Logging Settings, Log Files, and Server Reports. A description of each of these features follows.

Logging Settings

Use the Logging Settings page in the ColdFusion Administrator to specify where you want to store your log files and which log file format you prefer to use when viewing your log files. To access the Logging Settings page in the ColdFusion Administrator, click Tools > Logging Settings.

Default logging directory.

Help button Submit Change

button

42 Chapter 2 Administrator Tools

On the Logging Se ttings page , you can accept t he defau lts or ch ange th em as nee ded. Each time you make a change, you must apply the change by clicking Submit Change.

By default, log files are stored in the CFusion\log directory and all log files are saved using the ColdFusion 5 format. To learn more about the log settings and the differences between the log file formats, click Help on the Logging Settings page.

Log Files

The Log Files page in ColdFusion Administrator enables you to view a list of all generated log files from a single display. On this page, you can search and filter the content of log files, store log files for future use, and remove log files that are no longer needed. To access the Log Files page in ColdFusion Administrator, click Tools > Log Files.

Help button

Check boxes for viewing single or multiple log files.

View Log Files button

Controls

Y ou can view single or multiple log files b y checking the log files you want to view and clicking View Log Files.

Use the individual controls when you want to search and filter log files, remove log files, store log files for future reference, and/or schedule the storage of log files.

To learn more about the log files and its settings, click Help on the Log Files page.

Features on the Tools Tab 43

Server Reports

The Server Repor ts supplied with ColdFusion Server 5 Enterprise Edition pr ovide instantaneous statistics about the performance of your ColdFusion Server. In addition, some of these reports provide information that you can use to track server configuration changes and view current configuration settings.

To access the Server Reports in the ColdFusion Administrator, click Tools > Server Reports. The following table provides a brief overview of each report type.

Report Type Description

Server Performance Reports ColdFusion Administrator off ers eight server performance reports

that you can use to help measure the performance of your system. All reports offer cumulative averages of server statistics for a given time range. You can choose one of four intervals to report data: monthly, weekly, daily, or hourly.

You can access any of the following eight performance reports on the Server Reports page in the ColdFusion Administrator:

• Performance Statistics Summary This report summarizes the behavior reported in all other performance reports. It specifically identifies all performance counters related to CFML requests, database operations, ColdFusion template cache pops, and other counters used for measuring throughput and internal congestion.

• Requests Report This report identifies per second the average number of CFM pages requested and the maximum average number of CFM pages requested. Other information provided in this repo rt inclu des ave rage C PU usage, ColdF usion CPU usage, ColdFusi on mem ory us age, an d ColdFu sion h andle and thread counts.

• Database Operat ions Report This report identifies per seco nd the average number of database operations performed and the maximum average number of database operations performed. Other information provided in this report includes average CPU usage, ColdFusi on CPU u sage, Co ldF usion memo ry usag e, and ColdFusion handle and thread counts.

44 Chapter 2 Administrator Tools

Report Type Description

Performance Reports

• Cache Pops Report This report identifies per second the average number of C oldFusio n temp lates that w ere ej ected from cache and the maximum average number of ColdFusion templates that were ejected from cache. Other information provided in this repo rt inclu des ave rage C PU usage, ColdF usion CPU usage, ColdFusi on mem ory usage , an d ColdFu sion h andle and thread counts

• Queued Requests Report This report identifies per second the average number of ColdFusion requests waiting to be processed. Other information provided in this report includes average CPU usage, ColdFusion CPU usage, ColdFusion memory usage, and ColdFusion handle and thread counts.

• Requests in Progress Report This report identifies per second the average number of ColdFusion requests that are actively being processed by ColdFusion. Other information provided in this repo rt inclu des ave rage C PU usage, ColdF usion CPU usage, ColdFusi on mem ory us age, an d ColdFu sion h andle and thread counts.

• Time Out requests This report identifies the total number of ColdFusion requests that timed out while waiting to be processed. Other information provided in this report includes average CPU usage, ColdFusion CPU usage, ColdFusion memory usage, and ColdFusion handle and thread counts.

• Throughput Report This report identifies per second the average number of bytes received and returned between the ColdFusion Application Server and the Web server. Other information provided i n thi s rep ort i nc lud es aver age CPU u sa ge, ColdFusion CPU usage, ColdFusion memory usage, and ColdFusion handle and thread counts.

Features on the Tools Tab 45

Report Type Description

Settings Summary Report

The Settings Summary Report s hows th e st atus o f all C oldFu sion configuration setti ng s in one vie w. From this view, you can prin t the current configuration settings, or edit them directly by clicking the setting name shown in the report.

Settings Change Report

The Settings Change Report helps you track ColdFusion configuration changes as they occur. This report, generated for a specified time period, summarizes all changes made to the ColdFusion configuration.

For additional information about the Server Reports, click Help on the Server Reports page.

System Monitoring tools

The System Monitoring tools, supplied with ColdFusion Server 5 Enterprise Edition, offer various features to help you monitor and manage your Web site. These features include an easy-to-read site management configuration page, Web application monitors (probes), load management capabilities, alarm notifications, and the ability to integrate ColdFusion with a third-party load-balancing device. The following sections provide a brief overview of each of the System Monitoring tools that appear in the ColdFusion Administrator.

Note

If ClusterCATS is installed on your machine, all ColdFusion System Monitoring features appear in the ClusterCATS application and do not appear in the ColdFusion Administrator. To learn how to use the System Monitoring features in ClusterCATS, see the sections later in this book.

46 Chapter 2 Administrator Tools

Web Server Monitoring

The Web Server Configuration page in the ColdFusion Administrator enables you to easily determine the operating status of your Web servers and configured monitoring device(s). Use this page to monitor the operating status of each monitoring device, view and manage incoming server traffic, and to place a Web server in maintenance mode for necessary repairs. To access this page in the ColdFusion Administrator, click Tools > Web Servers.

Help button

The tabular form provides operating status fields and traffic management controls.

The easy-to-read tabular form on the Server Configuration page lists the names and status of the Web servers configured on your local system along with the status of each threshold setting and monitoring device configured. To learn more about the information and management controls provided on this page, click Help on the Server Configuration page.

Note

A monitoring device in ColdFusion can include Server Probes and/or a third-party hardware load balancing device. The status for t hese monitoring devices only appears on the Server Management page after each device is configured in ColdFusion using the Server Probes page or Hardware Integration page. For more information about the configuration options required for these monitoring devices and their benefits, see the sections in this chapter on Server Probes and Hardware Integration.

Features on the Tools Tab 47

Server Probes

The Server Probes tool in the ColdFusion Administrator enables you to actively test the health and operation of your local Web sites. Specifically, ColdFusion offers two probes for monitoring your Web site environment:

• Default probes The default probes let you test the availability of the ColdFusion Server or a specific URL.

• Custom probes The custom probes let you specify a test program to run as a probe. Depending on the program executable that you specify, you can use a custom probe to verify the availability of almost any part of your Web site such as

a database.

You can easily configure a default or custom probe from the Server Probes page in the ColdFusion Admin ist ra tor. To access thi s page , cl ick Tools > System Probes.

The tabular form provides both operating status fields and probe management controls.

Help button

Probe management controls.

Probe type setting.

Required Web server user-defined setting.

Optional user-defined settings.

48 Chapter 2 Administrator Tools

The tabular form on the Server Probes page ide ntifies the names and status of each probe configured in ColdFusion along with the name of the Web server that the probe is monitoring. The probe management controls let you suspend the oper ation of a configured probe and/or create, edit, and remove probe configurations.

The Server Probe Setup page lets you configure the settings required to set up a default or custom probe in ColdFusion. Use the Type drop- do wn lis t box to select the type of probe you want to configure. For more information about how to configure a default or custom probe in ColdFusion, click Help on the Ser ver Probe Setup page.

Alarms

The Alarm Email Notification page in ColdFusion Administrator lets you set up alarm notifications in the event that one or more critical events fail in your Web site. You can choose to notify yourself or others when one of the following events occur: Web server failure, Web server busy, load balancing device is unreachable, or a system probe failed.

T o access the Alarm Email Notification page in ColdFusion Administrator, click Tools > Alarms.

Help button

Required user-defined notification fields

On the Alarms Email Notification page you can choose to set up alarm notifications for one or all events. To notify someone of an event, enter their e-mail address in the Notification Recipient field. To learn more about how to configure alarm notifications in ColdFusion, click Help on the Alarm Email Notification page.

Features on the Tools Tab 49

Load Balancing Integration

The Load Balancing Integration page in the ColdFusion Administrator lets you configure ColdFusion with the Cisco Local Director. The Cisco Local Director is a network device with a secure, real-time, embedded operating system that intelligently load balances IP traffic across multiple servers. You can configure ColdFusion to provide availability and load information to the Local Director using the Cisco Dynamic Feedback Protocol (DFP). The Local Director then actively manages HTTP traffic across the servers based on the load information provided to it by ColdFusion.

To use Cisco Local Director with ColdFusion, you must configure the Cisco load balancing device on the Setting Up Load-Balancing Hardware page in the ColdFusion Administrator. To access this page in the ColdFusion Administrator, click Tools > Hardware Integration.

Help button

Required user-defined fields

To configure ColdFusion to work with Cisco Local Director, you must specify the DNS name and IP address of the Local Director box and the DFP Port that the ColdFusion Server uses to communicate with the Local Director box. For more information about configuring Cisco Local Director with ColdFusion, click Help on the Setting Up Load Balancing Hardware page.

Archive and Deploy tools

The Archive and Deploy tools supplied with ColdFusion Server 5 Enterprise Edition let you archive and deploy Web site configuration information, files, and/or applications. Use these features to deploy your Web site applications to another location or to back up your files quickly and easily. Additionally, you can use these features to securely deploy and receive any ColdFusion archive file electronically.

50 Chapter 2 Administrator Tools

The Archive and Deploy tools group in the ColdFusion Administrator includes the following features: Archive Settings, Create Archive, Deploy Archive, and Archive Security. A description of each of these features follows.

Archive Settings

The Archive Settin gs page in the ColdF usion Adm inistrator let s you configur e various archive system settings that apply to all archive and deploy operations. To access the Archive Settings pa ge in Co ldFusion Administrator, click Tools > Archive Settings.

Help button

Archive working directory.

Archive save log files settings.

Controls for defining archive variables.

Features on the Tools Tab 51

The following table provides a brief description of the features presented on the Archive Settings and Variable Definition page:

Feature Description

Archive working directory

Save log files The save log file controls let you specify when ColdFusion writes

Controls for defining archive variables

Default settings You can use the default settings provided on the Archive Settings

The archive working dir ectory text box le ts you spe cify the di rectory where all archive and restore temporary files and log files are written.

By default the archive temporary files and log files are written to Cfusion\cfam\car\temp directory.

archive events to a log file. ColdFusion, by defaul t, logs event s to the arc hive l og file each ti me

you create or restore an archive. The archive variable controls let you add, edit, and view archive

variables in ColdFusi on. Archive v ariables d efine locat ions that yo u commonly archive and restore on your system. The variable acts as an alias, saving you time from t yping lon g paths to files yo u want to archive or restore.

The tabular form on the Archive Settings page identifies all the archive variables su pplied with C oldFusion plus all the user-d efined archive variables. You can click Add Variables to define new variables or click a variable name shown in the tabular form to edit the definition of an existing variable.

All variable definitions in the ColdFusion Administrator are defined and edited using the Variable Definition page. In the Variable Definition page you must provide a name for the variable definition and a full path to the file(s) that you often archive and restore.

page or change them as needed. Each time you make a change on the Archive Settings page, you need to apply that change by clicking Submit Changes.

To learn more about the archive settings and archive variables in ColdFusion, click Help.

52 Chapter 2 Administrator Tools

Create Archive

The Create Archive page in ColdFusion Administrator lets you create and edit archive definitions and build archive files. To access the Create Archive page in ColdFusion, click Tools > Create Archive.

Help button

Controls for defining archive definitions.

Build archive control

Navigation bar to specify the items to archive.

Use the controls on the Create ColdFusion Archive page to add, edit, and view archive definitions. The tabular form on the this page identifies all user-defined archive definitions in ColdFusion. You can click Create Archive Definition to define new archive definitions or click any definition name shown in the tabular form to view and edit the settings of an existing definition.

Features on the Tools Tab 53

All archive definiti ons are defined and edited using the Archive Definition page. Use the navigation bar on the Archive Definition page to define the items you want to archive and restore. Each time you make a change in the Archive Definition page you must click Apply. You can remove items in the archive definition by clicking Delete.

After you create your archive definition, you can click Build Archive on the Create ColdFusion Archive page. The Build Archive control creates a compressed archive file (.car file extension) of your definition.

To learn more about creating archive files in ColdFusion, click Help on the Create ColdFusion Archive page or the Archive Definition page.

Note

After you build an archive file (car), you can deploy that archive file on your system or securely send it electronica lly to another syst em. F or more information about how to deploy an archiv e file or se curely send an archive file electronically, see the following sections in this chapter on Deploy Archive and Archive Security.

Deploy Archive

The Deploy A r chive p age in C oldF usion lets y ou to re stor e an existi ng ar chiv e file (car file) to either a location on your system or to a mapped network location.

To access the Deploy Archive page in ColdFusion Administrator, click Tools > Deploy Archive.

Help button

Archive file retrieval control.

Controls to proceed with restoring the file or to cancel the restore operation.

The archive file retrieval control lets you specify the retrieval method required to obtain the archive file (car file) you want to deploy. You can select one of three controls: local, http, or ftp. Use local when the archive file is on your system or on a mapped network drive. Use http if the archive file is posted on a Web site. Use ftp if the archive file is posted on an FTP site. Alternatively, if you specified local as the

54 Chapter 2 Administrator Tools

retrieval method you can click Browse Server to specify the archive file’s location on your system. After you specified the retrieval method and location of the archive file you can then click Next on this page to specify the location to restore the file.

To learn more about how to deploy archive files in ColdFusion, click Help on the Archive Deploy page.

Archive Security

The Archive Security page lets you digitally sign and/or encrypt your ColdFusion archive files. With these features you can securely send and receive archive files electronically.

By signing an archive file, you notify the recipient of the archive file that the file actually came from you and has not been forged or tampered with. By encrypting an archive file, you can help protect the contents of the archive file from intruders.

After you sign or encrypt an archive file in ColdFusion, you can then securely exchange this file electronically by using any of the following transport methods:

• E-mail program Use an e-mail program, such as Microsoft Outlook, to exchange secure archive files.

• FTP site Exchange secure archive files by posting the secure file on an FTP (File Transfer Protocol) site.

• Web site Exchange secure archive files by posting the secure file on an on a Web site.

• Shared file system Exchange secure archive files by posting the secure file to a shared local or remote network location.

To sign or encrypt files in ColdFusion Administrator use the Archive Security page. To access this page, click Tools > Archive Security.

Navigation bar lists the names of the settings that you can use to secure archive files.

Help button.

Features on the Tools Tab 55

Click the names of the settings in the navigation bar to import a security certificate, sign an archive file, verify the signature of an archive file, encrypt an archive file, or decrypt an archive file.

Note

Certificates are required to digitally sign a ColdFusion archive file or to verify the signature of an archive file. You can obtain a certificate from a Certificate Authority such as VeriSign, Inc., or you can generate a certificate using the Key Tool utility provided with the Sun Microsystem JDK 1.3.

For details on how to import a certificate, sign an archive file, verify the signature of an archive file, or encrypt and decrypt an archive file, click Help on the Archive Security page in the ColdFusion Administrator.

56 Chapter 2 Administrator Tools

Part II

ColdFusion Security

This part describes security fea tures and configuration in ColdFusion Server. The following chapters are included:

ColdFusion Security........................................... ............................ ....59

Configuring Basic Security.................................................................71

Configuring Advanced Security..........................................................79

Chapter 3

ColdFusion Security

This chapter introduces ColdFusion Server Basic and Advanced security features that allow you to protect a wide variety of ColdFusion resources.

Contents

• Why Is ColdFusion Security Important?..................................................................60

• Choosing a Level of ColdFusion Security................................................................62

• To Learn More About Security..................................................................................67

60 Chapter 3 ColdFusion Security

Why Is ColdFusion Security Important?

Today’s Web applications offer unique opportunities from e-commerce to global communication and collaboration. Today, developers and administrators alike must concern themselves with issues of security. The nature of the Web—global access, ease of connectivity and interaction, and lack of any real control over clients— creates an environment where application misuse or abuse can flourish. As a result, almost any discussion of Web applications and data integration quickly becomes a discussion of security. Web developers must fully understand the security risks that could affect their applications so they can address legitimate concerns while ignoring the tabloid-style hype that sometimes surrounds any mention of Web security.

All Web applications can potentially fall victim to these security breaches:

• Snooping and eavesdropping The risk that someone could “overhear” data being sent over the Web is a primary concern when applications send confidential data, such as credit-card information, over public connections.

• User impersonation Without proper authentication control, the risk of non-trusted users gaining access to secur e informatio n b y impers onating trusted users is a very real risk. Someone who successfully impersonates a trusted user could gain access to anything that user was authorized to see or download.

• Unauthorized access The risk of exposing sensitive information to unauthorized users is the biggest and most complex security risk, because the Internet effectively links every computer to one large network. While completely allowing or disall owing access to a given system or da ta so urce remains re latively straight-forward, allowing the partial access that is required for an application to be useful remains risky . F or example, it is easy for a large bank to publish a public, freely accessible site where no individual account information is available, but it’s much harder for the bank to create an account maintenance site where users have exclusive access to their own personal accounts.

ColdFusion is a pro ven, highly secur e environment for Web application development and deployment. ColdFusion can help you reduce these security risks:

• Encryption ColdFusion supports the Secure Sockets Layer (SSL) protocol which protects against snooping, eavesdropping, or any sort of message tampering when information is passed between clients and servers. For more information, see “Data encryption” on page 61.

• Authentication Authentication simply means making sure someone is a valid user of the system. Authentication involves prompting a user for a unique identification, like a login name, and some form of verification—information that no one other than the user could know, like a password or personal identification number (PIN).

• Access control Authenticated users are usually granted access to particular features or components based on security clearance, group affiliation, or other criteria specified by the developer.

Why Is ColdFusion Security Import ant? 61

Types of ColdFusion Security

ColdFusion Server provides two mutually exclusive security frameworks called Basic security and Advanced security. You can use either type of security to secure ColdFusion application development and deployment.

Basic security

Basic security is the initial default security framework for ColdFusion and lets you secure the ColdFusion server with password access:

• Application development Secure access to data sour ces an d files with p asswor d protection. Block access to several sensitive ColdFusion tags.

• Application deployment Prevent applications from executing several ColdFusion tags that could be used to upload, delete, or otherwise manipulate server files.

• Administrative Access Secure access to ColdFusion administrative functions with password protection.

All editions of ColdFusion Server include Basic Security features. When you install ColdFusion Server, Basic Security is automatically activated.

Advanced security

ColdFusion Server Professional and Enterprise editions include Advanced Security features that provide scalable, granular security for building and deploying your ColdFusion applications:

• Application development Control access to files, data sources and

• Application deployment Create complex rules to programmatically control

• Administrative access Assign different degrees of administrative access to

Data encryption

Both Basic and Advanced security support the Secure Sockets Layer (SSL) protocol which encrypts Internet application protocols (like HTTP) with public key cryptography. SSL protects against snooping, eavesdropping, or any sort of message tampering when inform ation is passed between clients and servers. Most Web servers support SSL. Th e server administrator installs a private key that is used to decrypt inbound data and encrypt outbo und da ta. Once the key is installe d, th e Web server automatically encrypts or decrypts data as it is received or transmitted.

administration for each developer on your team. Coordinate team development on shared servers with the assurance that sensitive data and applications are secure.

access to functionality within applications. Provide multiple levels of user access from within an application. Confine applications to secure areas that can flexibly restrict the access applications have to directories, components, databases or other resources on the server.

specified users.

62 Chapter 3 ColdFusion Security

If your Web server connections are encrypted with SSL, all communications, including ColdFusion transmissions, are automatically encrypted. You do not have to do anything from within ColdFusion to activate data encryption.

Choosing a Level of ColdFusion Security

The rest of this chapter is designed to help you decide which type of ColdFusion security is right for your particular development needs. Basic and Advanced security are mutually exclusive ColdFusion features. When you install ColdFusion Server, Basic security is turned on by default. If you turn on Advanced security, it automatically overrides all your Basic security settings except one: Tags you protected with Basi c security remain protected when you implement Advanced security .

Note

If you turn off both Basic and A d van ced se curity, all ColdFusion resour ces an d s erver administration functions become available to anyone who has access to the server. When you install ColdFusion S erver , leav e Basic se curity password s in place until y ou finalized your security plan and are ready to implement it.

As you begin to think about how you will secure your Web applications, keep these important points in mind:

• Security is never absolute. Technology is fast-evolving and the Web is, by nature, an environment that favors openness and access over privacy and security. You should regularly review your security plans to make sure your company hasn’t outgrown them.

• No single security model is perfect for every application or development environment. For example, an intranet deployed only to employees from a server behind your company’s firewall and an e-commerce site on the Web would have very different security plans. When they plan applications, ColdFusion developers must weigh the costs and benefits of the various security alternatives in the context of the project requirements.

• Trust is perhaps the most important concept to consider when you are planning any security strategy. When users decide whether or not to download something from the Web, it usually depends on if they trust the site. The site can engender trust in any number of ways, by providing a digital certificate, for instance. Similarly, how open you choose to make your ColdFusion environment depends on whether or not all your users are trusted. Generally speaking, the level of trust is inversely proportional to the lev el of sec urity you ne ed to imple m ent. If tru st is high—for example, if your development group consists of five people and th ey all access the ColdFusion server over a LAN—then you can probably manage with a less secure environment. However, if trust is lower—for example, if you're an Internet Servic e Provider (ISP) hosting a development site—then you will need to implement a more complex and restrictive security plan. The more public the application or development environment, the lower the level of trust.

Choosing a Level of ColdFusion Security 63

Basic security covers all phases of application development and deployment. Basic security is a good solution for trusted users because it offers them a single access level—complete control. Consider implementing Basic security if you have legacy systems or other security models in place.

Basic security also requires very little support from the ColdFusion Server administrator: You’ll want to choose a password that can’t be easily guessed and change it regularly, but aside from that, Basic security won’t require much of your time. Developers, on the other hand, will need to spend more time writing their applications; granular run-time access security is possible with Basic security, but involves custom development .

Advanced Security, on the other hand, allows you a great deal of flexibility and control, but requires more time and greater effort to set up and maintain than Basic security. Depending on how you implement it, Advanced Security can also affect performance when developers try to access resources from ColdFusion studio or when users try to run ColdFusion applications.

The following sections examine the effects of Basic and Advanced security on application development and deployment, and on administrative access to ColdFusion Server. Remember that when you select Basic or Advanced security, you’re making a global choice that affects all aspects of ColdFusion. You can’t, for instance, select Basic security for server administration and Advanced security for RDS. This section is organized by major task simply to help you prioritize your security concerns and then se lect th e type of C oldF usion security tha t best mee ts the majority of your needs.

Developing applications

Basic and Advanced security both restrict access to ColdFusion servers from ColdFusion Studio. Y o u ca n restrict access b y de ve lope rs who co n nec t t o C old F u sion servers over a local area network as well as by developers who use RDS to access ColdFusion servers.

Developing applications with Basic security

Basic security for application development hinges on the protection of a single password per server. As long as you change the password frequently and your users keep it secret, you should not have to worry about unauthorized access to the directories and resources on your ColdFusion server. Before you choose Basic security, it is imperative that you understand the security liabilities of this model:

• Password vulnerability If the passwor d is lost, hacke d, or sto len, server sec urity is compromised. See “Data encryption” on page 61 for information about protecting communications, including password transmissions, between your server and clients.

• Generalized access control Remote developers have access either to all files and data sources, or none. Basic security does not let you protect individual directories o r resources.

64 Chapter 3 ColdFusion Security

Basic security is a good choice to protect ColdFusion resources if your company consists of a single development group or several small groups all physically located at the same site. Because these developers can be considered highly-trusted users, Basic security can still make sense when they are away from the office and are using RDS to develop applications remotely.

When you use Basic security to restrict access to a ColdFusion server, developers can access all files and mapped ne twor k drive s on the server with a si ngle pa sswor d. This same password provides remote access to the server through RDS.

Developing applications with Advanced security

Advanced security is the ideal choice for administrators who need to meet the security challenges posed by remote or hosted ColdFusion application development. Unlike Basic security, which gives all developers the same level of access to all ColdFusion resources, Advanced security lets you customize access control for individual developers and development groups.

Using Advanced security requires more planning and configuration than using Basic security, but the benefits you’ll see in streamlined development processes are well worth the time you’ll invest. With Advanced security, you must specify the data sources and directories you want to protect, and then grant explicit access to these resources to specific groups or individual users. Protected resources can’t be accessed by anyone to whom you haven’t given permissions. A dv a nce d sec urity provides even further granularity by letting you explicitly specify the following on a group-by-group basis:

• The types of SQL commands that can be performed against a data source

• Read and write access to files

• The types of actions allowed by CFML tags

• Delete, optimize, purge, search, and update access to search collections

Because Advanced security uses your existing LDAP directories, NT domains, or ODBC data sources to authenticate ColdFusion developers, you never have to maintain redundant user lists. Advanced security automatically inherits any changes you make to your LDAP directories, NT domains, and ODBC data sources.

Deploying applications

Web applications present new security challenges for IT managers, administrators, and application developers. Basic security leaves the bulk of runtime security implementation to ap plication developers. Advanced security makes it easier for developers to authenticate users and authorize application access, because Advanced security separates group membership and user logon maintenance from security policy specification.

Choosing a Level of ColdFusion Security 65

Deploying applications with Basic security

Basic security lets you disable execution of CFML tags that could prevent security hazards if they were used in a Cold F usio n a pp licatio n, because th ey co uld be us ed to upload, delete, or otherwise manipulate files on the ColdFusion server. ColdFusion displays an error when it encounters a disabled tag in an application.

Besides the ability to restrict CFML tags, Basic security provides no runtime security for ColdFusion applications. When Basic security is implemented, the responsibility for securing applications falls mainly on the application developers. For example, developers must a uthen ticate end-us ers o f the ir applic ations b y creating customized user directories. Developers can also integrate existing user directories, like NT domains, by using any of the custom extension mechanisms supported by ColdFusion, including CFX tags, and COM or CORBA objects. Similarly, developers must custom-build all access privileges into all their applications.

Deploying spplications with Advanced security

Advanced security lets ColdFusion developers authenticate users and match protected resources with authorized users. Advanced security builds consistent, standardized authentication right into the ColdFusion server engine, making it easier for developers to control all aspects of access to their applications.

When Advanced security is implemented, developers don’t need to create customized directories or databases to authenticate users; Advanced Security can automatically authenticate users against existing LDAP directories, NT domains, or ODBC data sources. Advanced security also makes it easier to enforce access rights for authenticated users and groups. You can expressly grant or forbid run-time access to ColdFusion Applications, CFML tags, collections, components, Data sources, Files, Directories, and Custom Tags on a user-by-user or group-by-group basis. For example, you could use Advanced security to:

• Restrict sensitive CFML tags like <CFREGISTRY> so they can be used only by members of the NT Domain Administrators group of the local domai n.

• Make a sensitive search collection available only to your company’s Human Resources staff. No matter which applications use the collection, it would only ever be available to th is one group.

• Make CORBA or COM objects that work with a company’s financial information available only to the departments and Web applications that require them

In the Enterprise edition of ColdFusion, Advanced security also lets you run applications in a security sandbox, which assigns security permissions to any applications running from a specified directory tree. Unlike other Advanced security features, Security sandboxes automatically enforce control over resources without additional coding to autehnticate and authorize users. Security sandboxes eliminate the risk that one application will access another application’s resources, and are most useful to hosted sites where multipl e ColdFusion applicatio ns are deployed on the same server.

66 Chapter 3 ColdFusion Security

Securing the ColdFusion Administrator

The ColdFusion Administrator is a powerful tool that lets you perform administrative tasks like managing server performance, adding and configuring ColdFusion data sources, scheduling pages, and managing log files. You can secure the Administrator with either Basic or Advanced Security. Just as with application development and deployment, the level of security that controls administrative access depends on the level of trust.

Note

You can access the ColdFusion Administrator either locally or remotely. Because the ColdFusion A dministr ator is a Web-based interface, it inherits the lev el of encryption you set on the Web server on which ColdFusion is installed. If the Administrator is installed on a Web server that encrypts Web connections, information sent to the server during remote server administration is aut omatically encrypted.

Securing the Administrator with Basic security

When Basic security is implemented, you enter a password to access to the ColdFusion Administrator. (Note that the ColdFusion Administrator password is separate from the RDS security password.) Anyone who know s the administrative password can gain access to all the functionality of the ColdFusion Administrator. This situation may be desirable if you’re implementing ColdFusion in a small group where no one person is a designated administ rator and everyone pitches in with administrative tasks.

The liabilities of using Basic security to protect the ColdFusion Administrator are similar to those discussed in “Developing applications with Basic security” on page

63:

• Password vulnerability If the administrativ e pa sswor d is lost, h acke d, or st olen, server security is compromised. See “Data encryption” on page 61 for information about protecting communications, including password transmissions, between your server and clie nts.

• Generalized access control Anyone who knows the administrative password has full access to the ColdFusion Administrator. Users who are not familiar with the Administrator could unwittingly cause problems by changing administrative settings.

Securing the sdministrator with Advanced security

When Advanced security is implemented, you have complete control over who can access the ColdFusion Administrator. Additionally, you can decentralize ColdFusion server management by assigning varying degrees of administrative access to a select number of users. If you manage ColdFusion servers for a large, diverse organization or for hosted sites, you'll likely find that the ability to delegate server management tasks helps you run your operation more efficiently. See “Securing the ColdFusion Administrator” on page 102 in Chapter 5, “Configuring Advanced Security” on

page 79 for more information.

To Learn More About Security 67

To Learn More About Security

Security at the speed of the Web changes more frequently and over a broader spectrum than can be covered here. Allaire is dedicated to educating its customers about new security information as it becomes available.

Visit the Allaire Security Zone (http://www.allaire.com/developer/securityzone/) to read Allaire’s latest security bulletins and technical briefs that provide information about issues Allaire believes are significant. The Security Zone also contains an extensive list of non-Allaire sites where you can go to learn about everything from security standards and pr otocols to the most recent security bulletins fro m companies like Netscape, Microsoft, and Sun.

To learn how to configure ColdFusion Server with Basic or Advanced Security, continue on to the next two chapters in this book:

• Chapter 4, “Configuring Basic Security” on page 71

• Chapter 5, “Configuring Advanced Security” on page 79

68 Chapter 3 ColdFusion Security

To Learn More About Security 69

70 Chapter 3 ColdFusion Security

Chapter 4

Configuring Basic Security

Basic ColdFusion security allows you to secure a number of ColdFusion Server resources with password access. This chapter describes configuration options for basic ColdFusion security.

Contents

• About Basic Security ............................................................... ...... ....... ...... ....... ...... ..72

• Configuring Remote Development Security (RDS)................................................73

• ColdFusion Remote Development Services (RDS).................................................74

• Using a Password to Restrict Access to RDS............................................................76

• Configuring Basic Runtime Security........................................................................77

72 Chapter 4 Configuring Basic Security

About Basic Security

ColdFusion Server offers two levels of security: Basic and Advanced. Basic security allows you to impose the following types of control on the ColdFusion development environment:

• You can sec ur e the Col dFu sion A dmi nistr ator with a passw or d. R efer to “Securing

the ColdFusion Admin ist rato r ” on page 66 for more information.

• You can secure access from ColdFusion Studio to data sources and files with a password. See “ColdFusion Studio Password” on page 76 for more information.

• You can restrict the execution of specific ColdFusion CFML tags. See “Specifying

Resources to Protect” on page 96 for more information about securing

ColdFusion resources.

To access Basic security settings in the ColdFusion Administrator, open the Server, Basic Security page.

Advanced Security allows you to exercise a high degree of control over a wide range of ColdFusion resources, including CFML tags (as well as individual tag ACTION types), specific SQL operations, as well as other ColdFusion resources. For more information, see Chapter 5, “Configuring Advanced Security” on page79.

Installation defaults

The ColdFusio n Admin istrato r install s with secu re acc ess enab led. The p asswor d you enter as part of the setup is saved as the default, so that when you open the Administrator for the first time, you are prompted to enter the password. We recommend that you continue to use Administrator security until you complete the ColdFusion server configuration. Once you’ve determined your security requirements, you may decide to set up Advanced security. For more information, see Chapter 5, “Configuring Advanced Security” on page 79.

Disabling Administrator security

You can disable Basic security for the ColdFusion Administrator on the Server, Basic Security page. Once you’ve disabled this option, anyone can open the Administrator pages and make changes to ColdFusion Server settings.

Disabling ColdFusion Studio security

You can disable file and data source security from ColdFusion Studio on the Server, Basic Security page. With Basic security disabled, you rely on the Web server’s security to set permissions to ColdFusion application and document directories. In addition, you rely on your database settings to control access to data sources.

Configuring Remote Development Security (RDS) 73

Configuring Remote Development Security (RDS)

Restricting access to your applica tion page dir ectories is the most important step y ou can take in making your site secure. You can do this using ColdFusion Basic security. However, you may find it necessary to provide broader access to these directories if, for example, you have several geographically dispersed participants in a development project. In addition, a group of widely dispersed developers may require different levels of access to files and data sources.

Securing data sources

In addition to y o ur ap pli cat io n pages, you also ne ed to co n side r da ta source secu rity. Using basic security measures, you can take several steps to ensure that your data sources remain secure even when your application page directories are partially accessible:

1 If you do not need to ins ert, up date, or delete data in the data source, configure it

as read-only. You can do this in the ColdFusion Administrator ODBC Data Source Advanced page.

2 Use a database system that supports security and create a user account that has

access to only selected tables and operations (such as, SELECT, INSER T). You can then configure ColdFusion to use that account when interacting with the data source.

3 Using the ColdFusion ODBC or Native Drivers page, configure ColdFusion

settings to allow only certain SQL operations (such as SELECT and INSERT) in interactions with the data source.

74 Chapter 4 Configuring Basic Security

ColdFusion Remote Development Services (RDS)

ColdFusion RDS is a component of ColdFusion Server used by the ColdFusion Administrator and ColdFusion Studio to provide remote HTTP-based access to files and databases. You can use RDS to manage ColdFusion Studio access to files and databases on a server hosting ColdFusion.

RDS provides both Basic and Advanced security services for ColdFusion, allowing you to configure the level of security you need for your situation. For more information see Chapter 5, “Configuring Advanced Security” on page 79.

Basic security options managed by RDS can be found in the Administrator Server, Basic Security page, where you will find options for defining passwords and securing a subset of ColdFusion tags.

Basic security limit ations

ColdFusion Basic security hinges on the protection of a single password per server. So long as the password is kept secret, unauthorized access to the files and databases on the server is impossi ble . I t is importa nt to un derstan d that th is secu rity mod el has two liabilities:

• Password vulnerability. The password can be lost, stolen, or hacked.

• Access control is generalized, that is, remote developers have access either to all

files and data sources, or none. With Basic security, you can’t protect individual directories and or databases.

Securing ColdFusion file resources

The following table shows how ColdFusion Basic security compares with native OS options available to you in securing files for remote development:

Method Description Security Model

LAN-based Uses the native file system t o

provide access to local and network drives.

FTP-based Connects to an FTP server

running on same mac hine as the target Web server.

RDS-based Interacts with the remote file

system using RDS on the target ColdFusion Server.

Access is determined by the network permissions of user logged into workstation where Studio is being run.

Permissions defined using the native security of the FTP server software.

Files on the target s erver can be secured with the ColdFusion Studio password.

ColdFusion Remote Development Services (RDS) 75

Securing ColdFusion data sources

The following ta ble sho w s how ColdF usion B asic secu rity can be conf igure d to secur e ColdFusion data sources:

Method Description Security Model

Basic security is enabled on the local workstation.

Basic security is enabled on the remote server.

By using a LAN based file access model and by restricting developer data source access to the local workstatio n, a very secure development envi ronment can be achieved.

Data sources ar e acc essed through RDS on the local ColdFusion Server.

Data sources ar e acc essed through RDS on the remote ColdFusion Server.

Data sources that are accessible to the user lo cally are accessible through ColdFusion Studio.

Data sources that are accessible to ColdFusion Server are accessib le remotely via ColdFusion Studio.

76 Chapter 4 Configuring Basic Security

Using a Password to Restrict Access to RDS

The Server, Basic Security page of the ColdFusion Administrator is used to configure passwords for securing the Administrator and for preventing unauthorized access to ColdFusion data source and file resources through ColdFusion Studio.

Note

Password protection is enabled by default at server installation time. If you have not explicitly disabled password access, then security is already configured for your server.

ColdFusion Studio Password

The ColdFusio n St udio pa sswor d, like the Adminis trat or passwo rd is s pecified during ColdFusion setup. You can specify a new password in the Administrator to control database and file access from Studio. Separate Studio and Administrator passwords allow you to separate access control to ColdFusion data sources and files, and Administrator pages.

Note

Whenever you make a change to Basic security settings, you need to stop and restart the ColdFusion RDS service using the Services Control Panel in Windows or the stop and start scripts on Solaris.

Removing password-based access control: Windows

To allow ColdFusion Studio users access to files and databases without being prompted for a password:

1 In the Security section of the ColdFusion Administrator, click the CF Studio

Password link.

2 Clear the Use a ColdFusion Studio Password checkbox. 3 Open the Services Control Panel. 4 Stop and then restart the ColdFusion RDS service. On non-Windows platforms,

you run the ColdFusion Stop script, then run the ColdFusion Start script.

Configuring Basic Runtime Security 77

Configuring Basic Runtime Security

Basic security lets you disable execution of seven CFML tags that could present security hazards. You can, however, specify a special directory, called the Unsecured T ags Directory; this is the only directory from which ColdFusion will execute tags you disable with Basic security. Tags you disable with Basic security remain disabled if you switch to Advanced security.

To restrict tag execution

1 Open the ColdFusion Administrator and click the Security link at the top of the

navigation bar.

2 Click the Tag Restrictions link. 3 On the Tag Restrictions page, clear the check box that appears in front of each tag

you want to disable. You can block execution of the following tags:

cfcontent

•

• cfdirectory

• cffile

• cfobject

• cfregistry

• cfadminsecurity

• cfexecute

• cfftp

• cflog

• cfmail

• The cfquery dbtype = dynamic attribute

• The connectString attribute, available in the cfgridupdate, cfinsert,

cfquery, cfstoredproc, and cfupdate tags.

4 Click the Submit Changes button.

78 Chapter 4 Configuring Basic Security

5 T o specify a directory from which otherwise blocked tags can be executed, enter a

fully qualified path (using forward slashes) in the Unsecured Tags Directory field. By default, this is the directory in which the ColdFusion Administrator is installed.

ColdFusion displays an error message when it encounters a restricted tag in an application. For more information about these tags, see to the CFML Reference.

Chapter 5

Configuring Advanced Security

This chapter describes how to set up and configure ColdFusion Server advanced security. Advanced security, which is based on Netegrity SiteMinder v. 4.11, lets you protect a wide variety of ColdFusion resources.

Contents

• What is Advanced Security?......................................................................................80

• Advanced Security Basics......................................... .............................................. ..81

• Advanced Security Implementations.................................................................... ..84

• Creating an Advanced Security Framework............................................................88

• Setting Up a Security Server.....................................................................................89

• Caching Advanced Security Information................................................................91

• Defining User Directories.........................................................................................92

• Defining a Security Context......................................................................................95

• Specifying Resources to Protect...............................................................................96

• Implementing ColdFusion RDS Security....................... ....... ...... ....... ...... ....... ...... ..98

• Implementing User Security.................................................................................. ..99

• Implementing Server Sandbox Security................................................................100

• Securing the ColdFusion Administrator................................................................102

• Viewing a Map of your Security Framework.........................................................103

• An Example of ColdFusion Studio Security ..........................................................104

• Advanced Security Single Sign-On..................... ...... ....... ....... ................................109

• Undocumented Tags and Functions .....................................................................110

80 Chapter 5 Configuring Advanced Security

What is Advanced Security?

ColdFusion Server Professional and Enterprise editions include Advanced security features that provide scalable, granular security for building and deploying your ColdFusion applications:

• Application development Control access to files, data sources and administration for each developer on your team. Coordinate team development on shared servers with the assurance that sensitive data and applications are secure.

• Application deployment Create complex rules to programmatically control access to functionality within applications. Confine application s to secure areas that can flexibly restrict the access applications have to directories, components, databases or other resources on the server.

• Administration Secure the ColdFusion Server Administrator against unauthorized access and g rant various levels of ad ministr ative access to specifie d users.

It is important to remember that unlike Basic security, which automatically password-protects your resources, Advanced security provides a self-enforced security framework that must be explicitly en force d by de velopers in th e application s they write. (In the Enterprise version of ColdFusion, Advanced security does provide for security sandboxes, which automatically protect the resources they contain.)

Note

If you have not already read Chapter 3, “ColdFusion Security” on page 59," take a few minutes now to do so. This chapter discusses the differences between Basic and Advanced security and helps you decide which type of security is best for your ColdFusion environm ent.

Advanced Security Basics 81

Advanced Security Basics

All types of Advanced Security implement the following four elements:

• User directorie s

• Resources

• Policies

• Security contexts

This section introduces these elements and describes how they work together to build your Advanced Security framework. For detailed, hands-on instructions for actually implementing an Advanced Security framework, see “Crea ting an Advanc e d Security Framework” on page 88.

User directories

User directories provide a listing of user information, s uch as the user’s name, login password, and the names of any groups to which the user belongs. ColdFusion Advanced Security lets you incorporate any of the following industry-standard user directories:

• Lightweight Directory Access Protocol (LDAP) directory

• Windows NT doma in

• ODBC data source

A user directory authenticates users by verifying that their credentials match those in the directory. It tells you if someone is a valid user of the system. When you create a security context, you select users and groups from a user directory and then individually assign them access rights to ColdFusion resources. ColdFusion developers then include cod e in their app lications th at checks if a user has rights to a resource.

Because ColdFusion uses your existing LDAP directories, NT domains, or data sources, you don’t have to create and maintain redundant user directories just to develop or deploy ColdFusion applications. Using existing NT or LDAP provides an added bonus: User groups to whom you assign security privileges automatically inherit changes to group membership; no additional maintenance is required. For example, suppose your company’s NT Domain contains a user group called BigDev. You’ve used Advanced Security to give the BigDev group access to a number of custom tags. Your company hires a new developer to work in the BigDev group. When the new developer is added to the BigDev group in your company’s NT domain, she’s automatically granted access to the custom tags because of her user group affiliation.

82 Chapter 5 Configuring Advanced Security

Resource types

A ColdFusion resource type that yo u w ant to p ro tec t is th e core of Advanc e d s ecu rity. Selecting a resource to protect doesn’t specify how to protect it or which users can access it; you’re simply telling ColdFusion the name and, if applicable, the action of the resource you intend to secure. For example, you can control:

• Write access to all the files in a specified direc tory

• Which actions of a specified CFML tag are restricted

• Inserts and updates for a specific ColdFusion data source

Resources are not secured until you specifically choose to protect them. You can secure the following types of resources:

• Applications

• Verity Collections

• Components

• Col dFusion Tags

• ColdFusion Functions

• Custom Tags

• Data Sources

• Files and Directories

• User Objects

• Users

Policies

After you specify a resource to protect, you need to create a policy that gives a set of users access rights to that resource. A policy binds resources to users or user groups, that is, it grants a group of users access to specified resources.

For example, you can create a policy that gives members of a team complete access to three data sources that the team uses regularly. You could also create a policy that specifies the system administrator as the only user who ca n use the

write action.

If you specify a resource to protect but do not include it in any policy, the resource is fully protected within the Security Context—in other words, no users have access to those resources.

cffile tag’s

Macromedia Advanced ColdFusion Administration User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

About This Book

Intended Audience

New Features

Developer Resources

About ColdFusion Documentation

Printed and online documentation set

Viewing online documentation

Getting Answers

Contacting Macromedia

Data Sources and Tools

Advanced Data Source Management

About ColdFusion database drivers

About OLE DB

About native drivers

Using ColdFusion to Create a Data Source (UNIX only)

Using Connection String Options

About the connection string

Changes to the ColdFusion Administrator

Changes to CFML tags

Connecting to DB2 Databases

Configuring DB2 options (Windows)

Configuring DB2 options (UNIX)

Configuring system and services files (UNIX)

Installing and Configuring DB2 Client Enabler (UNIX)

Data source and start script settings for DB2 (UNIX)

DB2 binding and privileges for ODBC (UNIX)

Executing a DB2 stored procedure (Windows, UNIX)

Connecting to dBASE/FoxPro Databases

Configuring dBASE/FoxPro options (Windows)

Configuring dBASE/FoxPro Driver options (UNIX)

Connecting to Excel Databases

ODBC: Microsoft Excel Driver options

ODBC: MERANT Excel Workbook Driver options

Connecting to Informix Databases

Configuring Informix using ODBC

Configuring Informix using the native driver

Connecting to Informix data sources (UNIX)

Connecting to Informix through ODBC/CLI (Windows, UNIX)

Connecting to Sybase Databases

ODBC: MERANT Sybase ASE Driver options

Native: Sybase 11 Driver options

Tips for connecting to Sybase System 11 (UNIX)

Connecting to Text Databases

ODBC: Microsoft Text Driver options (Windows)

ODBC: MERANT Text Driver options (UNIX)

Connecting to Visual FoxPro Databases

Administrator Tools

Accessing the Administrator Tools

Features on the Tools Tab

Logs and Statistics tools

System Monitoring tools

Archive and Deploy tools

ColdFusion Security

ColdFusion Security

Why Is ColdFusion Security Important?

Types of ColdFusion Security

Choosing a Level of ColdFusion Security

Developing applications

Deploying applications

Securing the ColdFusion Administrator

To Learn More About Security

Configuring Basic Security

About Basic Security

Installation defaults

Configuring Remote Development Security (RDS)

Securing data sources

ColdFusion Remote Development Services (RDS)

Basic security limit ations

Securing ColdFusion file resources

Securing ColdFusion data sources

Using a Password to Restrict Access to RDS

ColdFusion Studio Password

Removing password-based access control: Windows

Configuring Basic Runtime Security

Configuring Advanced Security