Configuring ColdFusion for Multiple Hosts

The ColdFusion installer utilizes the JRun 4 Web Server Configuration tool ( wsconfig ) to install the connector into the Web server. The connector is a filter that intercepts ColdFusion template requests from the Web server and passes them to the ColdFusion engine. The wsconfig tool ( cf_root\runtime\bin\wsconfig.exe in Server configuration and jrun_root\bin\wsconfig.exe in Multiserver configuration) has a GUI and a command-line interface.

Previously, the ColdFusion MX 6.0 installer when installing on multi- homed servers only configured the first virtual server instance. For IIS, this is usually the Default Web Site, and for Sun ONE it is the first configuration directory (in alphabetical order). Since Apache's virtual host configuration is contained in one file (apache_root\conf\httpd.conf) , the installer correctly configures all Apache virtual hosts.

Although later versions of the installer now correctly configure multi-homed Web servers, you may still need to configure the remaining virtual sites for the IIS and Sun ONE server platformsand any new additions. The following sections explain how to do this.

TIP

Think of the connector as the Web server stub in ColdFusion 4.x/5.0.

Microsoft IIS 5.x/6.0

To properly integrate with ColdFusion, you must make these configuration changes to your IIS server:

Add the ColdFusion filename extensions ( .cfm , .cfc , .cfr , etc.)
For IIS 5.x: Create the JRun Connector ISAPI Filter, and create the JRunScripts virtual directory.
Configure an IIS 6.0 wildcard application mapping for ColdFusion.

NOTE

ColdFusion MX 6.1 was the first version to officially support Windows 2003 and IIS 6.0. If you are upgrading from CFMX 6.1 to 7, the CFMX 7 installer should properly configure your IIS for multi-homing.

Creating the JRun Connector ISAPI Filter and the JRunScripts Virtual Directory

The ColdFusion installer uses the wsconfig tool to implement these changes. However, it only adds the ISAPI filter and JRunScripts virtual directory to the Default Web Site. These need to be configured at the WWW Master property sheet level in order to propagate to all sites (existing and new). Because the ColdFusion filename extensions are mapped at the WWW Master property sheet level, the individual virtual servers properly handle all ColdFusion template requests.

NOTE

On IIS 6.0, the JRun Connector ISAPI filter is replaced by the wildcard application mapping to provide connect to the Flash Remoting gateway.

For IIS 5.x, you need to configure a JRunScripts virtual directory for each of your virtual sites. Macromedia has created batch files in the cf_root\bin\connectors directory for removing and adding the Web server (Apache, IIS, and iPlanet/Sun ONE) connectors. Follow these steps to correct your IIS 5.x configuration:

Stop the World Wide Web Publishing Service via the Services applet or the Internet Services Manager.

Run the cf_root\bin\connectors\Remove_ALL_connectors.bat to remove the misconfigured ISAPI filter.

The Remove_ALL_connectors.bat file will remove all configured connectors for all Web servers on the machineApache, IIS, and iPlanet/Sun ONE. You can modify this file by replacing the -uninstall with -remove and supplying the appropriate -ws <server name > , and -site <site name> or -dir <config directory> parameters. See Table 10.3 for more command-line options, and consult the ColdFusion online documentation for a complete overview at http://livedocs.macromedia.com/coldfusion/7/htmldocs/00001755.htm#121511.

Table 10.3. WSCONFIG Command-Line Removal Options

WEB SERVER	COMMAND
IIS	`cf_root\runtime\bin\wsconfig.exe remove server coldfusion -ws IIS -site sitename -v` .
Apache	On Windows: `cf_root\runtime\bin\wsconfig remove server coldfusion -ws Apache -dir [ path to httpd.conf]` . On Unix: `./cf_root/runtime/bin/wsconfig remove server coldfusion ws Apache dir [path to httpd.conf] -v` .
Sun ONE/iPlanet/Netscape	On Windows: `cf_root\runtime\bin\wsconfig.exe remove server -ws sunone iplanetnes -dir [path to config] v` . On Unix: `./cf_root/runtime/bin/wsconfig remove server -ws sunoneiplanetnes -dir [path to config] v` .

NOTE

You can also use the wsconfig GUI tool to remove the IIS mappings.

Run the cf_root\bin\connectors\IIS_connectors.bat to properly reconfigure all existing sites.

NOTE

The IIS_connectors.bat will configure all virtual sites for ColdFusion. You may have virtual sites that should not have access to ColdFusion, or you may have sites that integrate with JRun 4. Since you need to have ColdFusion properly configured at the WWW Master Property sheet level, you can run the IIS_Unconfigure_one_Site.bat file for each site for which you wish to remove ColdFusion access.

Restart the World Wide Web Publishing Service.

Adding the ColdFusion Extensions

Newly created virtual servers will inherit the ColdFusion filename extension mappings and ISAPI filter. However, you will need to manually configure the JRunScripts virtual directory for IIS 5.x using the following steps:

1.	Start the Virtual Directory Creation Wizard shown in Figure 10.4 for your newly added virtual site: Figure 10.4. Use the Virtual Directory Creation Wizard to create the JRunScripts virtual directory. a. Open the Internet Service Manager. b. If the new server isn't already open, click the + next to the server name. c. Right-click the new virtual site name and select New > Virtual Directory. d. Click Next.
2.	Enter `JRunScripts` as the Alias. Click Next.
3.	Browse to or type in the path to the directory containing the `jrun.dll` (for example, `cf_root\runtime\lib\wsconfig\1` ). Click Next.
4.	Only check the boxes next to Execute (such as ISAPI applications or CGI). Clear all other check boxes as shown in Figure 10.5, and click Next. Figure 10.5. Enable Execute permissions only for JRunScripts.
5.	Click Finish. The Wizard will close, and your new JRunScripts virtual directory should be selected, as shown in Figure 10.6. Figure 10.6. New JRunScripts directory after completing the wizard.
6.	Right-click the JRunScripts virtual directory and select Properties.
7.	Click Remove. Your properties sheet should resemble Figure 10.7, with the Application Name disabled, the virtual server name as the Starting Point, and Scripts and Executables as the Execute Permissions. Figure 10.7. Final view of the JRunScripts properties sheet Virtual Directory tab.
8.	Click OK to close the properties sheet.

You'll need to repeat these steps each time you add a new virtual server.

Sun ONE/iPlanet

Whether the ColdFusion installer actually configures all of your Sun ONE servers depends on how you have them set up. Sun ONE 6.x allows for multiple Web servers via two configurations: virtual servers, and multiple Web server instances.

You configure virtual servers on a single IP address and port of an individual, installed Web server instance. All of the virtual server's configuration parameters are stored in the server.xml file in the configuration directory of the Web server instancefor example, sunone_root\ https -<server_id>\config\server.xml .

Web server instances are typically installed on a particular IP addressalthough they can work on different ports with the same IP address, as well. In addition, they have their own autonomous configuration directory ( sunone_root\https-<server_id>\config ). They exist for backwards compatibility with earlier Netscape/iPlanet builds.

Multiple virtual servers configured per Web server instance is Sun's preferred way to implement multi-hosting.

NOTE

KISS it! If you want centralized management of your multi-homed configuration, install a single Sun ONE instance on a static IP address, and configure multiple virtual instances. ColdFusion will correctly install the connector to integrate with all your virtual hosts. See the Sun ONE Web Server Enterprise Edition Administrator's Guide for more details on the recommended Sun ONE configuration.

If you have configured multiple virtual servers against a single Web server instance, then the ColdFusion MX 6.0 installer has properly configured your Web sites. This is because the configuration parameters for each individual virtual server are contained in the server.xml of the Web server instance.

If you have installed multiple Web server instanceseach with its own configuration directory ( sunone_root\https-<server_id>\config )then the ColdFusion installer only configured the first configuration directory it found alphabetically . You will need to run the wsconfig tool to properly install connectors for ColdFusion. The following steps illustrate how to use the wsconfig tool GUI to make your configuration changes:

1.	Start the JRun 4 Web Configuration tool GUI shown in Figure 10.8: Figure 10.8. The JRun 4 Web Server Configuration tool. On Windows, select Start > Run and type in the path to the executable: `cf_root\runtime\bin\wsconfig.exe` On Unix/Linux, change directories at the command line to `cf_root\runtime\jre\bin` , and enter . `/java -jar ../../lib/wsconfig.jar` . TIP Notice that the configuration directory of the one instance configured by the installer is already present in the `wsconfig` tool window.
2.	Click Add. The Add Web Server dialog box opens (Figure 10.9). Figure 10.9. Point to your Sun ONE server's configuration directory.
3.	Choose Sun ONE Web Server (iPlanet) in the drop-down list for Web Server. Then enter or browse to the configuration directory path of one of your installed servers.
4.	Check the box next to Configure Web Server for ColdFusion applications.
5.	Click OK, and click Yes at the response shown in Figure 10.10. Figure 10.10. Restart the iPlanet Web server instance.
6.	The JRun 4 Web Server Configuration window returns, as shown in Figure 10.11. The Configured Web Servers list now displays the configuration directory path of your newly configured Sun ONE server instance. Figure 10.11. Congratulations! You have configured your Web server instance.
7.	Click Add to repeat the process for your remaining Web server instances.

{% if main.adsdop %}{% include 'adsenceinline.tpl' %}{% endif %}

NOTE

For each Web server instance, you'll have to go to the Sun ONE Server Manager and apply the configuration file edits. Click the Apply button to restart the Web server.