ColdFusion MX & Windows Server 2003 Family (内容也是英语)

[Dogfish]

Overview
This tutorial has been provided in response to the vast number of individuals experiencing difficulty in attempting to install Macromedia ColdFusion MX Application Server on the Microsoft Windows Server 2003 family of operating systems.

This tutorial applies to the following Microsoft Windows Server 2003 family of operating systems:

Browsing the links below will take you to a Product Overview for each operating system.

Microsoft Windows Server 2003 (Web Edition)
Microsoft Windows Server 2003 (Standard Edition)
Microsoft Windows Server 2003 (Enterprise Edition)
This tutorial does not apply to the following Microsoft Windows Server 2003 family of operating systems:

Testing has not been performed on these operating systems.

Microsoft Windows Server 2003 (Standard Edition 64-bit)
Microsoft Windows Server 2003 (Enterprise Edition 64-bit)
Microsoft Windows Server 2003 (Datacenter Edition 32-bit)
Microsoft Windows Server 2003 (Datacenter Edition 64-bit)
Getting Started
In order to complete this tutorial you will need to have the following products available:

A licensed version of at least one of the first three Microsoft Windows Server 2003 family operating systems
A licensed version of Macromedia ColdFusion MX Application Server
A Service Pack for ColdFusion MX (used to apply bugs fixes) known as Updater 3 (See link below)
Alternatively If you do not have a licensed version of Macromedia ColdFusion MX Application Server, you may use a Developer Edition. This version of the product provides the same functionality as the Enterprise Edition however this version is intended primarily for development purposes.

Visit the following link for information about obtaining Macromedia ColdFusion MX Application Server (Developer Edtion).

Additional Requirements
You will also need to make a single temporary modification to the Window Registry. This modification will be later returned to its original setting and so should not affect system stability at a later date.

Please note that while this registry modification is a required part of the installation process, incorrectly modifying your registry may result in system instability. Please make sure you backup your registry before continuing further.

Introduction
With the roll-out of the Microsoft Windows Server 2003 family of operating systems, comes the latest version of its web server software - Internet Information Services 6.0. Offering both new features and improved stability over its predecessor IIS 5.0.

However, developers wishing to use Macromedia ColdFusion MX are presented with a problem since ColdFusion MX cannot simply be installed against the latest version of IIS 6.0 until a patch (QFE/Updater) has been released from Macromedia.

This tutorial provides a temporary work-around to this issue and is outlined below.

Please note that it is recommended that you only attempt to complete these steps on a development platform until Macromedia releases an updater for ColdFusion MX to resolve this issue. Check the Product Updates section at Macromedia for updates newer than Updater 3 (Released March 19, 2003), which may resolve this issue already.

Installing Macromedia ColdFusion MX
With IIS 6.0 successfully installed and running we need to install ColdFusion MX. Part of this whole issue is in understanding how ColdFusion MX is installed onto a Microsoft Windows platform.

ColdFusion MX uses the Microsoft Windows Installer technology. This essentially means that the install is not a standalone executable, but requires the Windows Installer service to be present and up-to-date before the install can be performed. Microsoft Windows Server 2003 includes this technology by default (as does ColdFusion MX if it is absent from your system) and so problems on this front are a non-issue, however it should serve to point out that the operating system does play a significant role in the overall installation process.

Also included as part of the install executable is a database which provides much of the logic needed to install ColdFusion MX using the Windows Installer service. This database has an .msi extension and is typically named ColdFusion MX.msi. While this database is extracted to your system at runtime it is promptly deleted after the install completes.

It is within this database that the ColdFusion MX installation, stores among many other things, registry paths and values to either be set or searched for during installation. Because we are attempting to install ColdFusion MX on a platform for which it was not planned, we are presented with a major problem... it simply will not install against IIS 6.0 because the database does not know it exists.

For those who have attempted the installation, you most likely will have come across either of the following two error messages:

[Dogfish]

ColdFusion MX Installer Information
Error 1801 - The path \ is not valid. Please specify a valid path.
Error 1314 - The specified path \ is unavailable.
These error messages (stored within the database) are given after choosing Internet Information Services (IIS) as the web server for ColdFusion MX to use and presented to you when you attempt to browse to a directory for the web root. The directory information already supplied is hard-coded as \ which would imply the root drive that the installation is started from (typically drive C:\), however since this is not where one would want to install the web root, when attempting to change directory the error messages are shown. (Please note: Error 1801 will only be shown when selecting next from this dialog).

Install The Standalone Web Server
With our options now limited to only the standalone (JRun) web server it seems that this is the only way to run ColdFusion MX on Windows Server 2003. This is exactly what we are going to do here, however we are not going to use the standalone web server to serve our ColdFusion pages... we definitely are going to use Microsoft Internet Information Services 6.0 to do that for us, just like it did in Windows 2000, only better in 2003.

Run the ColdFusion MX installer and follow the dialogs as presented to you to install the standalone web server - (do not) select Internet Information Services (IIS). After you have successfully completed the installation, the ColdFusion MX Administrator should appear running on TCP port 8500. Close this browser window, the next time you see the ColdFusion Administrator it will be running on TCP port 80 and will be served off IIS 6.0.

Stop Internet Information Services (IIS 6.0)
Next we need to stop running IIS 6.0. We can quickly accomplish this by opening either your Application Server MMC console or by using the Internet Information Services (IIS) Manager MMC console held under Administrative Tools on your Start menu.

Once in the console right-click on the branch (node) in the console tree displaying your computer name and select All Tasks / Restart IIS...
From the dialog box shown select the second option to Stop Internet Information Services on computername, where computername is the name assigned to your Windows Server upon installation.

If you work better with the command line, then you can also stop IIS 6.0 at a command prompt window - open one and confirm the following command:

IISRESET /STOP

This should present you with the following output:

Attempting stop...
Internet services successfully stopped

This will achieve the same goal as above and requires less navigation, however do this only if you are comfortable using the command prompt.

Modify Registry (DWORD Value)
This next step involves temporarily modifying the Windows Registry and is required to run ColdFusion MX against IIS 6.0. Open regedit from either a command prompt window or the run command from your Start menu.

This will launch the built-in Microsoft Windows Registry editor, navigate to the following key:

My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp

Held under this registry key is a DWORD Value named MajorVersion with a data value of 0x00000006 (6). This value will prevent ColdFusion MX from working with IIS 6.0 correctly and thus needs to be temporarily modified to reflect a prior version of IIS, namely version 5.0.

Right-click on this DWORD Value and select Modify from the context menu shown (you can also just double-click since to modify is the default action). In the Value data: field change the default value from 6 to 5 and click OK, leaving all other settings at their default value.

This registry modification is required because when completing the next step in this tutorial, we are going to use a tool provided by Macromedia which was installed with ColdFusion MX. This tool looks at this registry value and will cause an error if it is set at its default value.

JRun Web Server Configuration
We now need to connect ColdFusion MX to IIS 6.0 and the tool we are going to use to do this was installed along with ColdFusion MX by default and is located in the following directory:

C:\CFusionMX\runtime\bin\wsconfig.exe

Please note that you may need to adjust the path shown to reflect where you installed ColdFusion MX (although I would recommend that you choose the default installation path).

This tool is primarily intended to configure web servers for ColdFusion MX to use after installation, for example to configure either Microsoft Internet Information Services, Apache, or Netscape Enterprise Server/iPlanet. We are going to use this tool of course to configure IIS 6.0, although since we have modified our registry this tool thinks we are configuring IIS 5.0.

Run the tool and click on the Add button to move to the Add Web Server Configuration dialog box to begin configuring IIS 6.0.

[Dogfish]

Typically the values for JRun Server Properties are correct for your installation and can be left at their default values. We are more concerned with the field shown below for Web Server Properties. Make sure that Internet Information Services (IIS) is selected from the Web Server drop down menu and the IIS Web Site menu is set to select All and click on the Advanced button.

Clicking on the Advanced button will present you with a dialog to set futher options for your web server. Under the first field for Connector Settings check the box to Enable verbose logging for connector if you wish to receive addtional logging output for later analysis (leave the second option deselected).

Please note: If you do "Enable verbose logging for connector" a *.log file is created in the following directory:

C:\CFusionMX\runtime\lib\wsconfig\1

Please note that you may need to adjust the path shown to reflect where you installed ColdFusion MX (although I would recommend that you choose the default installation path).

Next under IIS Settings chose the option to Use Application Mappings and add to the two already selected extensions the following:

List of application mappings to add
.cfm
.cfml
.cfc
Please note that should you wish to later include addtional mappings for ColdFusion MX to process you can enable this through IIS 6.0, which will be working shortly.

Once all your application mappings are in place click OK twice to be presented with a dialog informing you of the following:

Confirm
The web server is not running. The web server must be started to add this configuration.


Would you like to start it now?

Select Yes to proceed. (please note that it is at this point that an error would have been shown by this tool had you not modified the previous registry entry.

Having chosen Yes to start IIS we are now shown a dialog box that states that Internet Information Services (IIS) is configured for All web sites. Click Exit to close this dialog.

Internet Information Services Configuration
In order to take a more proactive stance against malicious users and attackers, IIS 6.0 is not installed on members of the Microsoft Windows Server 2003 family by default. Furthermore, when you do initially install IIS 6.0, the service is installed in a highly secure and "locked" mode. By default, IIS 6.0 serves only static content - meaning features like ASP, ASP.NET, Server-Side Includes, WebDAV publishing, and FrontPage Server Extensions do not work unless enabled.

This also applies to our situation, since ColdFusion MX serves dynamic content that is considered script enabled and falls under the umbrella of non-static content, like the above technolgies listed. In order to enable ColdFusion MX to serve dynamic content we need to add a new Web Service Extension.

Web Service Extensions are new to IIS 6.0 and provide web administrators with more control over what content can and cannot be served through IIS. In order to add a new web service extension for ColdFusion MX perform the following procedure:

First open your Internet Information Services (IIS) Manager and expand the tree node labeling your computer name. Select Web Service Extensions from the tree list to present its details pane (please note that there are no nested levels below Web Service Extensions in the console tree.).

From the Action menu choose the first option to Add a new Web service extension...
In the New Web Service Extension dialog enter ColdFusion MX for the extension name. This is a friendly name used to display in the Web Service Extensions details pane and can be modified if desired.

For the next section of the dialog box we have to choose a specific file that ColdFusion MX provides and is required to complete this dialog box. This file is located here:

C:\CFusionMX\runtime\lib\wsconfig\1\jrun.dll

Please note that you may need to adjust the path shown to reflect where you installed ColdFusion MX (although I would recommend that you choose the default installation path). (Also note that the directory 1 shown in the path did not exist upon installation of ColdFusion MX and was created when we used the wsconfig.exe tool to configure IIS).

Click Add to open a browse dialog to navigate to the above file and select OK once to add this required file to the list. Make sure that the option below the list field (Set extension status to Allowed) is checked to allow this web extension and then click OK to close this dialag box.

At this point we should now see ColdFusion MX listed as a new Web Service Extension with its status set to Allowed. Close Internet Information Services (IIS) Manager and proceed to the next final steps.

Ensuring System Stability
As previously mentioned the modification made to the Windows Registry was only to be a temporary measure to allow us to install and configure ColdFusion MX. With this task now behind us, let's change back the DWORD Value to its original value.

Once again open up the Windows Registry editor as instructed above. Provided that no other registry keys have been navigated since we last closed the editor, you should be presented with the same key already selected. If not then navigate to the following key:

My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp

Going back to how we modified the registry value earlier, we simply need to change the DWORD Value for MajorVersion from 5 back to 6. Either right-click on the MajorVersion entry or double-click it to change the value data: field from 5 to 6 and select OK to close this dialog box and then exit the registry. (Ensure to leave all other settings at their default value as before, before selecting OK.).

De-activating The Standalone Web Server
When we first installed ColdFusion MX, we did so using the built-in JRun standalone web server. This is more than satisfactory for development purposes, however now that we have ColdFusion MX installed and configured to run against IIS 6.0, it is no longer needed. Let's de-activate it now.

Open your Services MMC console held under Administrative Tools on your Start menu, and shutdown the following three services only:

ColdFusion MX Application Server
ColdFusion MX ODBC Agent
ColdFusion MX ODBC Server
These are the services needed by ColdFusion MX in order to function correctly, however we temporarily need to close these services in order to make a change to one of ColdFusion MXs' configuration files. Once this change has been made these services can be restarted to allow ColdFusion MX to function correctly using only IIS 6.0 instead of the built-in JRun standalone web server.

With the above three services now stopped, navigate to the following configuration file and then open Windows Notepad:

C:\CFusionMX\runtime\servers\default\SERVER-INF\jrun.xml

Please note that you may need to adjust the path shown to reflect where you installed ColdFusion MX (although I would recommend that you choose the default installation path).

[Dogfish]

This file is written using XML and stores many of the settings used by ColdFusion MX in order to function correctly. We are only going to modify two values in this file so if you are unfamiliar with XML don't worry, we shall go through the steps in a detailed fashion.

With Windows Notepad already open and and a Windows Explorer window already open at the previous address (shown above), drag and drop the jrun.xml configuration file onto Notepad. Choose the Edit menu and then select the Go To... option. Enter 315 for the Line Number: value and click OK.

This will take you to the 315th line of the configuration file and should read as follows:

JRun.xml - Line 315
<attribute name="deactivated">false</attribute>

Change the word false to true and then choose File/Save.

Now once again, choose the Edit menu and then select the Go To... option. Enter 333 for the Line Number: value and click OK.

This will take you to the 333rd line of the configuration file and should read as follows:

JRun.xml - Line 333
<attribute name="cacheRealPath">true</attribute>

Change the word true to false and then choose File/Save.

Close this configuration file when done.

Brief Explanation of Changes Made to JRun.xml
ColdFusion MX stores much of its configuration using XML. This provides for a multitude of configuration options to be modified (as we have just done) using basic text editors such as Windows Notepad.

These modifications can then be read by ColdFusion MX once all of its services start/restart allowing changes to be instantly reflected. The two modifications we made were firstly to prevent ColdFusion MX from using the JRun standalone web server (installed originally) and the second modification was to prevent ColdFusion MX from caching pages if more than one web site is configured in IIS 6.0.

Please note that this last modification was not deemed necessary by the author of this tutorial since since its author only has one web site configured for use with ColdFusion MX. If you do have more than one web site configured however I strongly suggest you leaving this option as modified, I also recommened that you consult the originating author of this tutorial (Scott Glassbrook) for further information regarding this second modification.