CFMX Administrator "for Dummies" Jo Ann Goertner

CFMX Administrator
"for Dummies"
Jo Ann Goertner
[email protected]
TeraTech, Inc.
Speaker Information
 Absorbing programmer-think 'by osmosis' since childhood
 Began software experience as a user – on the job since 1981
 Career change to software development 1998
 Formal training: “Fast Track” Software Development Certificate
(Enterprise Focus) in procedural and object-oriented languages
 Learned to "break software" on the job (Quality Assurance)
 Programmer since 2000 – ColdFusion, Java, SQLServer
 Enterprise-scale CF applications (Application Service Provider
model)
 ColdFusion Developer with TeraTech since May 2006
Why “for Dummies”?

None of us are really “dummies”!

Many times as coders, someone else is administering the server. We
just don’t get much experience in this area.

This presentation assumes you have a basic understanding of CF
development (but maybe not much interest in servers).

So why do I need to know this?

If you want to be able to write code locally or try new things, at home or
on your laptop, you become the administrator of your own local CF
server.

When troubleshooting code, it is helpful to understand the environment
your code is running in:
 What parts are “just how ColdFusion works”?
 What parts are dependent on settings that can be changed?
 Why does my code sometimes work on one server, but fail when deployed
in a different environment?
What this presentation will cover










What is the Administrator?
Where is it and how do I get into it?
ColdFusion data sources
Debugging settings & why they are important
Path settings in the Administrator (mappings and
custom tag paths)
CF variable settings
Logging settings & CF log files
Remote Development Services (RDS)
Other settings and services to be aware of
Suggested resources for learning more
1. What is the Administrator?
(and why do I need to know?)

The ColdFusion MX Administrator is a browser-based interface that
runs on the same machine with the ColdFusion application server.

It is used to configure your ColdFusion server, thereby managing your
ColdFusion environment.

Many settings related to security and functionality.

Available options differ depending on:
 Edition of ColdFusion MX 7: Standard or Enterprise
 Server installation: server, multiserver, or J2EE

You need to know the territory your code is running in, and the invisible
rules it is following.
 Would you drive down the highway without knowing which side of the road
they drive on here?
2. Where is the Administrator?
 You browse to the CFMX Administrator using your web browser.
 The default location is:
http://servername[:portnumber]/CFIDE/administrator/index.cfm
 On your local computer, common names for the webserver are
localhost or 127.0.0.1 (use as servername above).
 If using the CF built-in webserver, include the port number.
 Default port number is 8500.
 Local example using CF built-in webserver:
http://127.0.0.1:8500/CFIDE/administrator/index.cfm
2. Where is the Administrator?
(continued …)
 For a remote server, use the DNS name or IP address.
 http://www.mysite.com/CFIDE/administrator/index.cfm
 Default port numbers may vary:
 Default for multiserver configuration is 8300.
(Be sure to use the site (DNS or IP) pointing to the specific instance
of CF Server you want to administer.)
 Upgrades from a previous version to MX7 will assign an unused
port (typically 8501).
 If you move the Administrator outside the web root, you need to
create webserver mappings … actually two of them:
 /cfide/
and
/CFIDE/
…
case matters, both ways!
3. How do I find my way around?
 Left menu (expandable tree)
 Topics listed under broad categories (Server
Settings, Data & Services, etc.)
 Tree may differ based on edition and
configuration.
 Top links and menu choices
 System Information
 Help
 Other resources and documentation.
4. Password protection
 Must use the password specified when
ColdFusion MX was installed.
 Just one password!
 Limit to trusted users.
 No roles-based access.
 In the Administrator, under Security > CF
Admin Password, you can change the
password or turn password protection off and
on.
4. Password protection (continued)
“How do I retrieve a lost or forgotten password?”
“You cannot access the password, but you can turn off password usage
so as to be able to reset it. To do this locate the neo-security.xml file (it
will be in the lib directory beneath the ColdFusion root).
“Look for a section that reads:
<var name='admin.security.enabled'><boolean value='true'/></var>,
change the 'true' to 'false', save the file, and then restart ColdFusion.
You will then be able to log into the ColdFusion Administrator without a
password so as to set a new password and then turn on password use
again.”
– Ben Forta’s www.cffaq.com

Caution! Always back up any XML configuration file before handediting.
5. Data Services > Data Sources

“Data Sources” topic under “Data Services” category (left navigation
tree).

A CF data source is a complete database configuration that uses a
JDBC driver to communicate with a specific database.
 Must configure a data source in CFMX Administrator for each database
before it can be accessed with your CF code.
 After configuring the data source, CF can communicate with the database
by referencing the data source name.

Not to be confused with the Windows data source (ODBC)
configuration tool (under Start > Control Panel > Administrative Tools)
 If you need to use an ODBC data source, the Administrator provides a
driver type of “ODBC Socket” for this purpose.
 Preferred way is to connect directly with the correct JDBC driver for your
database, when possible.
5. Data Sources, continued
To add a new data source:
 Assign a unique name to the data source. (The name you will
later use for the <cfquery> datasource attribute in your code.)
 Select the appropriate driver type for the database and click
“Add”.
 A form will appear with fields specific to the selected driver and
database type.
 Complete required fields and submit.
 Should show a status of OK if it is able to successfully connect.
 Can also edit, verify or delete any of the listed data sources.
5. Data Sources, continued
An “interesting” quirk to be aware of:

Data sources “should not” be case-sensitive. However, if you enable
Sandbox Security (SBS), also called Resource Security in the Standard
Edition, they can become case-sensitive.
 Again, this is because of the underlying Java code.
 Version 7.0.2, hot fix 1 included a fix for this behavior.
 Check System Information link at top of Administrator for your version level.

If your code works great in development, and suddenly stops working
when deployed in a shared hosting environment using Sandbox
Security, this is a possible culprit.

To find out if Sandbox Security is configured, go to
 Security > Sandbox Security or
 Security > Resource Security (depending on your server edition)
6. Debugging & Logging >
Debugging Settings & IP Addresses

The settings in here are critically important to the performance and
security of your server!

Enable Robust Exception Information
 Very useful on a development server
 Very dangerous on a live server!
 Exposes server information to would-be attackers

Enable Debugging – turns debugging on or off (the output appended to
end of every page request).
 The “Enable Debugging” checkbox overrides all customized debugging
configuration in the section below.
 Custom Debugging Output – detailed configuration options.
 On a live server, you will normally keep debugging disabled.
 However, your custom configuration remains.
 If you need to enable it temporarily to troubleshoot a problem, one click on
“Enable Debugging” enables all custom settings.
6. Debugging & Logging (continued) >
Debugging Settings
Performance considerations!
 When turned on, debugging consumes significant
resources on the server … whether you see any
debug output or not!
 This is an important place to look when
troubleshooting performance issues such as slow
response times or processes that never return.
 Long-running processes can run out of memory and
fail invisibly, based on the information you told CF to
collect through these settings.
6. Debugging & Logging (continued) >
Debugging IP Addresses
 Specify the IP addresses to receive debugging
messages
 The output appended to end of every page request.
 Enter or delete IP addresses to maintain the list.
 When no IP addresses are entered, all users receive
debugging information.
 So, at least keep the local address (127.0.0.1) in here.
 And remember, to show it for one, the server must
collect it for all.
 Go back to “Debugging Settings” and disable it when that is
not what you want!
7. Path settings in the Administrator
 The CFMX Administrator lets you configure
paths, where CF will look for code you can
call from within the currently executing
template.
 Use Server Settings > Mappings to create
ColdFusion mappings.
 Use Extensions > Custom Tag Paths to
specify paths where CF will look for custom
tags.
7. Path settings, continued
Server Settings > Mappings
 ColdFusion mappings are directory aliases created in CFMX
Administrator, for use by
 <cfinclude> and <cfmodule> tags
 <cfinvoke> and <cfobject> tags
 CreateObject() function
 Mappings can simplify code reuse and site maintenance by
replacing relative paths with an absolute alias, maintained at
one location rather than hundreds.
 If the physical location changes, one edit to the mapping applies
to all code that uses it.
7. Path settings, continued
Server Settings > Mappings (continued)
 Mappings in tag attributes begin with ‘/’ and can be called the
same way regardless of where in your directory structure they
are located.
 Why would you want to write this:
<cfinclude template=‘header.cfm>
<cfinclude template=‘display/header.cfm>
<cfinclude template=‘../display/header.cfm>
<cfinclude template=‘../../display/header.cfm> etc …
 When you can do this from ANY location, instead?
<cfinclude template=‘/display/header.cfm>
7. Path settings, continued
Server Settings > Mappings (continued)
To create a ColdFusion mapping:
 Enter the name for your mapping.
 The leading ‘/’ is not required. The Administrator will add it for you.
 Browse to select the physical location your mapping will point to.
Note:
 ColdFusion mappings are independent of web server mappings,
aka “virtual directories”. If you would like to create a virtual
directory to access a given directory through a URL, consult
your web server documentation.
7. Path settings, continued
Extensions > Custom Tag Paths

Custom tag paths tell CF where to look for custom tags.

Custom tag paths affect tags called by simple syntax (<cf_mytagname>) or by
using the <cfmodule> tag.

Simple syntax:
 CF always looks for custom tags in the current directory first.
 If not found, it searches a special directory created by CF upon installation (normally
c:\cfusionmx7\customtags\ on a Windows machine).
 This default Custom Tag Path can be seen in the CFMX Administrator.
 Any subdirectories of this path are also searched (recursively, in alphabetical order).
 Additional custom tag directories may be added using the Administrator, causing CF to
look there as well.
 CF will execute the first custom tag it finds that matches the name you called.
8. CF variable settings
Server Settings > Memory Variables

ColdFusion Application variables and Session variables must be
enabled in the CF Administrator before they can be used in your code.
 Application variables expire when you restart the ColdFusion server.
 Session variables expire when the user's session ends.
 Both types of variables also expire after a time-out period that you specify
on this page or in the <cfapplication> tag.

Use this page to:
 Enable or disable Application variables or Session variables
 Specify maximum and default timeouts for these variable types.
 You can also specify the type of Session management (a server-wide
setting).
8. CF variable settings (continued)
Server Settings > Memory Variables (troubleshooting)

The “CFAPPLICATION tag” part of this message can be rather
misleading.

You could get this same error message for 2 different reasons:
 Application variables enabled in the Administrator, but code is trying to read
or write to Application scope before executing a <cfapplication> tag.
 Application variables disabled in the Administrator. Your <cfapplication> tag
will not enable Application scope until you first enable Application variables
in the Administrator.
8. CF variable settings (continued)
Server Settings > Memory Variables (troubleshooting)
 The following message about Session scope is more accurate:

Once Session variables are enabled using the Administrator, you may
get the error “Before session variables can be used, the session state
management system must be enabled using the CFAPPLICATION
tag.”

This will happen if session variables are enabled on the server but
you did not enable them in your <cfapplication> tag prior to
referencing them in code.
8. CF variable settings (continued)
Server Settings > Memory Variables
 Once Application and Session variables are enabled in the
Administrator, you can turn them on and off and set their
timeouts in the normal way:
<CFAPPLICATION NAME="MyApp"
SESSIONMANAGEMENT="Yes"
SESSIONTIMEOUT="#CreateTimeSpan(0, 0, 20, 0)#"
APPLICATIONTIMEOUT="#CreateTimeSpan(2, 0, 0, 0)#">
8. CF variable settings (continued)
Server Settings > Client Variables

Client variables are used to store user information and preferences (specific to a
single user) between sessions.
 Client variables must be enabled in <cfapplication> tag before they can be used.

When you use Client variables in your code, there are several places CF can
store them.
 Registry
 Cookie
 A CF Data Source

This page of the Administrator lets you tell ColdFusion how to store them:
 Available storage mechanisms
 Which is the default.
 Unless you specify a different ClientStorage attribute in your <cfapplication> tag, this
setting applies.
8. CF variable settings (continued)
Server Settings > Client Variables
 THE DEFAULT STORAGE METHOD SHOULD BE CHANGED!
 Registry use should be avoided, as it can de-stabilize your system
through unnecessary use of the registry.
 Best practice is to create a data source for ColdFusion’s use
and make it your default Client storage location.
 CF must be allowed to create tables in this database (temporarily at
least).
 ColdFusion will create 2 tables in the database, named CDATA and
CGLOBAL, to be used for client variable storage.
8. CF variable settings (continued)
Server Settings > Client Variables
 To add a ColdFusion data source to the list of available client
storage mechanisms:
 Select the data source from the drop-down list and click “Add”
 To set a data source as the default storage mechanism:
 Select the radio button and click “Apply”
 You can also set a Purge Interval to control how often
ColdFusion executes a purge operation on your client stores.
 Default is 1 hour 7 minutes.
8. CF variable settings (continued)
Server Settings > Client Variables

You can turn Client variables on or off in your applications using the
<cfapplication> tag:
<CFAPPLICATION NAME="MyApp"
CLIENTMANAGEMENT="Yes"
CLIENTSTORAGE=“datasource_name">

ClientStorage attribute must refer to something in the list of available
Client Storage mechanisms

CF must be able to access it.

Otherwise, an error will be thrown.
9. Debugging & Logging >
Logging Settings & Log Files
Debugging & Logging > Logging Settings

Here, you can set the Logging directory to which CF error log files
should be written.
 Default is C:\CFusionMX7\logs (Windows, single-server)
 To change the logging directory, type in or click Browse Server to select
from the directory tree.
 Drive must have sufficient disk space
 Must have security privileges for the ColdFusion system service.

Stop and restart the ColdFusion Service for the change to take effect.

Other logging settings available:





Maximum file size
Maximum number of archives
Log slow pages taking longer than ____ seconds
Log all CORBA calls
Enable logging for scheduled tasks
9. Debugging & Logging (continued) >
Logging Settings & Log Files
Debugging & Logging > Log Files
 Use this page to manage CF log files:
 search, view, download, archive, delete
 Some log views on this page are more useful than
others.
 Can select and view multiple logs at once
 interleaved according to time stamp
 Log files can also be opened directly through your file
system with any text editor/viewer.
9. Debugging & Logging (continued) >
Logging Settings & Log Files
Debugging & Logging > Log Files

Suggested viewers for very large log files (I haven’t tried these yet!):
 Far Manager (File and ARchive Manager) http://farmanager.com/
 Console.app in OS X (built-in under /Applications/Utilities)
 Or another application wrapped around the Unix “Tail” utility.
 (Google search: Tail Windows GUI)
 Eclipse plug-in CF LogViewer 1.0?

For very large log files, look for a viewer that is:
 Not also an editor (without the overhead of tracking changes)
 Live – stays open and refreshes to watch new info being logged
 Stays at the end of the log file (Tail)
 Doesn’t interfere with the process of writing logs
10. Security > RDS Password
 Remote Development Services (RDS) cannot be enabled and
disabled on this page.
 Contrary to what some of the CF documentation states.
 All you can do here is change the password, or specify whether
RDS requires a password.
 If you uncheck the box, RDS will simply allow all connections
without a password.
 RDS allows developers (or hackers) to remotely access all the
drives and all the data sources on the server where it resides.
 Disable RDS in a production environment!
 For an explanation on how to do this (disable the RDS servlet by
editing the web.xml file) refer to:
http://www.adobe.com/devnet/coldfusion/articles/cf7_security_04.html
Learning more …
Server Settings > (multiple sub-sections)
 Spend some time browsing through the remaining pages of the
Administrator.
 Brief, helpful explanations included on the pages.
 HELP link in upper right corner gives default values, and in
some cases additional information.
 Server Settings > Settings Summary:
 A compact view of existing settings
 Provides quick links back to where these settings can be modified.
Learning more (continued) …

System Information (link at top of page)
 Shows your current CF server version, edition, update level
 Apply license (serial number) here
 Apply update files to your installed CF server

Security
 Read up on RDS and Sandbox security (aka Resource security)
 That is a whole presentation in itself!

Mail settings
 Specify a default Mail Server (for your <cfmail> tags) and other mail-related settings on
the Server Settings > Mail page.
Learning more (continued) …

CF scheduled tasks
 Schedule a CF template to run once or periodically at specified time(s) or
intervals, using the Debugging & Logging > Scheduled Tasks page.

What is the Code Analyzer?
 The Code Compatibility Analyzer (Debugging & Logging > Code
Analyzer) helps migrate your applications to ColdFusion MX from earlier
versions of ColdFusion.
 It reviews the CFML pages that you specify, and informs you of any
potential compatibility issues.
 It detects unsupported and deprecated CFML features, and outlines the
required implementation changes that ensure a smooth migration.

Linked documentation
 Spend a few minutes getting familiar with the links across the top of the
page (Getting Started, Documentation, TechNotes, Release Notes,
Resources).
Resources

ColdFusion MX 7 documentation: many ways to get it!
 Follow the “Documentation” link at top of the CFMX Administrator
 Local HTML version on any machine with CF installed:
C:\CFusionMX7\wwwroot\cfdocs\dochome.htm
 LiveDocs: http://livedocs.macromedia.com/coldfusion/7/
 Download the full CFMX7 pdf documentation set (15.2 MB .zip file) and search the
index: http://www.adobe.com/support/documentation/en/coldfusion/index.html

http://cfdocs.org/
 Can search on any tag name and for different CF server versions
 Searches LiveDocs first
 If nothing found, it goes to Google

Ben Forta’s http://www.cffaq.com

Macromedia ColdFusion MX7 Certified Developer Study Guide by Ben Forta

http://www.houseoffusion.com/groups/
Questions? Comments?
Thank you for your listening!
Jo Ann Goertner
ColdFusion Developer
TeraTech, Inc.
[email protected]