Adobe ColdFusion 8

Web server configuration

ColdFusion uses the Web Server Configuration Tool to configure an external web server with the modules and settings that the connector needs to connect to ColdFusion. You can run the Web Server Configuration Tool through either the command-line interface or the graphical user interface (GUI). In either case, the Web Server Configuration Tool configures your external web server to interact with a ColdFusion server.

Using GUI mode

The Web Server Configuration Tool includes a GUI mode, which you can use to specify external web server configuration settings through a graphical interface.

Note: When you use the Web Server Configuration Tool in GUI mode, you must select the Configure Web Server for ColdFusion Applications check box.

Run the Web Server Configuration Tool in GUI mode

  1. Open a console window.

    Note: In Windows, to start the Web Server Configuration Tool, select Start > Programs > Adobe > ColdFusion 8 > Web Server Configuration Tool.

  2. Change to the cf_root/runtime/bin (server configuration) or jrun_root/bin (multiserver configuration) directory.
  3. Start the Web Server Configuration Tool using the wsconfig.exe (Windows) or wsconfig (UNIX) command.

    The Web Server Configuration Tool window appears.

  4. Click Add.
  5. Select Configure Web Server For ColdFusion Applications.
  6. In the Server drop-down list box, select the server or cluster name that you want to configure. (Individual server names in a cluster do not appear. Clustering support is only available on the multiserver configuration.)

    Note: The server or cluster does not have to reside on the web server computer. In this case, enter the IP address or server name of the remote computer in the JRun Host field.

  7. In the Web Server Properties area, enter web-server-specific information, and click OK.
  8. (Optional) Move the CFIDE directory and other directories (such as cfdocs) from the built-in web server's web root to your web server root directory. In addition, you can copy your application's CFM pages from the built-in web server's web root to your web server root directory.

    Note: When a page is requested, the web server connector first looks for the ColdFusion page in the cf_root/wwwroot (server configuration) or jrun_root/servers/cfusion/cfusion-ear/cfusion-war (multiserver configuration) directory, and then looks under the web server root. Alternatively, you can use the command-line interface and specify the -cfwebroot option.

  9. (Optional) The web server connector does not serve static content (such as HTML files and images) from the built-in web server's root directory. If your ColdFusion web application has an empty context root (/) and you want to serve pages from the built-in web server's root directory, you can create a web server mapping to the corresponding directory under the built-in web server.

Using the command-line interface

You can also run the Web Server Configuration Tool through a command-line interface.

Run the command-line interface

  1. Open a console window.
  2. Change to the cf_root/runtime/bin (server configuration) or jrun_root/bin (multiserver configuration) directory.
  3. Execute the wsconfig.exe (Windows) or wsconfig (UNIX) command:
       wsconfig.exe [-options]
   ./wsconfig [-options]

The following table describes the options:

Option

Description
-ws

Specifies the web server, as follows:

  • IIS
  • Apache
  • SunOne
  • iPlanet
  • NES

The web server name you supply is not case-sensitive.
-dir

Specifies the path to the configuration directory (Apache conf or NES/iPlanet config).
-site

Specifies the IIS website name (case-sensitive). Specify All or 0 to configure the connector at a global level, which applies to all IIS websites.
-host

Specifies the ColdFusion server address. The default value is localhost.

-server

Specifies the ColdFusion server name.

-username

Specifies a username defined to the JRun server. The default value is guest account.
-password

Specifies a password that corresponds to -username. The default value is guest account.
-norestart

Specifies not to restart the web server.
-cluster

Specifies the JRun cluster name. Use this option to define a connection to a JRun cluster instead of a single server.
-l

Enables verbose logging for the connector.
-a

Enables native OS memory allocation.

-map .cfm,.cfc,.cfml,.cfr,
.cfswf,.jsp,.jws

Specifies the extension mappings list. (To use the web server connector with ColdFusion, specify .cfm, .cfc, .cfml, .cfr, .cfswf, .jsp, .jws.)

-filter-prefix-only

(IIS 5 only) Sets ignoresuffixmap=true in the jrun.ini file. This means that the connector module runs as an IIS extension.
-coldfusion

Ensures that the proper ColdFusion mappings are set (.cfm, .cfml, .cfc, .cfswf, .cfr, .jsp, .jws), and, if IIS, filter-prefix-only is implicitly specified.

Always use this option when you configure a web server for use with ColdFusion.
-upgrade

Upgrades existing configured connectors with newer modules from a newer wsconfig.jar file.

-service

Specifies the Apache Windows service name. The default value is Apache.

-bin

Specifies the path to the Apache server binary file (apache.exe in Windows, httpd on UNIX).
-script

Specifies the path to the Apache UNIX control script file (apachectl, but slightly different with certain Apache variants, such as Stronghold).
-v

Enables verbose output from the Web Server Configuration Tool.
-cfwebroot

Specifies the directory corresponding to cf_root/wwwroot. If you use this option, the Web Server Configuration Tool creates web server mappings for /CFIDE and /cfdocs, each of which points to the corresponding directories under cf_root/wwwroot. This option is useful in a multihoming or hosting environment where you want multiple applications to share the ColdFusion Administrator.
-list

Lists all configured web servers.
-list -host server-host

Lists all JRun servers on the specified host.
-remove

Removes a configuration. Requires the -ws and either the -dir or -site options.
-uninstall

Uninstalls all configured connectors.
-h

Lists all parameters.

Using the batch files and shell scripts

The ColdFusion server configuration includes batch files and shell scripts that implement typical command-line connector configurations. These files are in the cf_root/bin/connectors directory. For example, the IIS_connector.bat file configures all sites in IIS to site 0, which establishes a globally defined connector so that all sites inherit the filter and mappings.

If you use Apache or Sun ONE Web Server, use these files as prototypes, editing and saving them as appropriate for your site.

Command-line interface examples

This section provides examples of multiple use-cases for different web servers:

  1. Configure a specific IIS site:
    cf_root/runtime/bin/wsconfig.exe -server coldfusion -ws iis -site "web31" -coldfusion -v

    On systems where all sites run ColdFusion, there is generally no need to configure an individual site.

  2. Configure all existing IIS sites (ISPs):
    cf_root/runtime/bin/wsconfig.exe -server coldfusion -ws iis -site 0 -coldfusion -cfwebroot C:\Inetpub\wwwroot -v

    The -cfwebroot option allows all sites to share the ColdFusion Administrator that runs under C:\Inetpub\wwwroot. This example does not automatically configure newly added sites after the first -site 0 run, but you can rerun with -site 0 at a later time, and the Web Server Configuration Tool configures new sites only.

  3. Configure Apache on UNIX #1:
    cf_root/runtime/bin/wsconfig -server coldfusion -ws Apache -bin /opt/apache2/bin/httpd -script /opt/apache2/bin/apachectl -dir /opt/apache2/conf -coldfusion -v

  4. Configure Apache on UNIX #2:
    cf_root/runtime/bin/wsconfig -server coldfusion -ws Apache-bin /usr/bin/httpd -script /usr/bin/httpd -dir /etc/httpd/conf -coldfusion -v

  5. Configure Apache in Windows:
    cf_root/runtime/bin/wsconfig.exe -server coldfusion -ws apache -dir "c:\program files\apache group\apache2\conf" -coldfusion -v

  6. Configure Netscape on UNIX:
    cf_root/runtime/bin/wsconfig -server coldfusion -ws nes -dir [path to config] -coldfusion -v

  7. Configure Sun ONE Web Server on UNIX:
    cf_root/runtime/bin/wsconfig -server coldfusion -ws sunone -dir [path to config] -coldfusion -v

Configuration files

The Web Server Configuration Tool stores properties in configuration files, as follows:

IIS
In the jrun.ini file, typically found in a subdirectory of the cf_root/runtime/lib/wsconfig (server configuration) or jrun_root/lib/wsconfig (multiserver configuration) directory. For IIS 5 only, it also defines filter and extension mappings in the IIS metabase.
Apache
In the httpd.conf file, typically found in the apache_root/conf directory.
Sun ONE Web Server/iPlanet
In the obj.conf and magnus.conf files, typically found in the ws_root/server-http-xxx/config directory.

The following table describes the web server connector properties in the web server configuration files. The web server connector uses these settings to help it find the ColdFusion server and know which servers to connect to.

Property

Description

bootstrap

Specifies the IP address and port on which the JRun server's proxy service is listening for connector requests. JRun must also be configured to listen on this port and address combination, the ProxyService must be activated, and the JRun server must be running. Specify ipaddress:portnumber (for example, 127.0.0.1:51011).

serverstore

Specifies the full path and filename of the file that contains information for the associated JRun server. The connector creates this file automatically. The default filename is jrunserver.store.

verbose

Creates more detailed web server log file entries for the connector. Enabling this option can cause the web server's log files to fill quickly. Specify true or false; the default value is false. In Apache and Sun ONE Web Server, the connector writes to the error log configured for the web server; on IIS, the connector writes to its own log in the related wsconfig subdirectory.

scriptpath

(IIS only) Points to the virtual /JRunScripts directory on the web server.

errorurl

(Optional) Specifies the URL to a file that contains a customized error message. This property is commented out by default. You must restart the web server after enabling this setting.

ssl

(Optional) Enables secure sockets layer (SSL) between the web server and the JRun server. You must set this setting to false.

apialloc

Enables native operating-system memory allocation rather than the web server's allocator (for use on Solaris with Sun ONE, at the direction of Adobe Support staff).

ignoresuffixmap

(IIS only) Forces the connector to use application mappings.

proxyretryinterval

Specifies the number of seconds to wait before trying to reconnect to an unreachable clustered server.

connecttimeout

Specifies the number of seconds to wait on a socket connect to a JRun server.

recvtimeout

Specifies the number of seconds to wait on a socket receive to a JRun server.

sendtimeout

Specifies the number of seconds to wait on a socket send to a JRun server.

Each time you run the Web Server Configuration Tool, it creates a new configuration file and directory. For example, the first time you run the tool in the server configuration, it creates files under cf_root/runtime/lib/wsconfig/1; the second time, it creates cf_root/runtime/lib/wsconfig/2; and so on. Each of these subdirectories contains the appropriate platform-specific connector module and web-server-specific supporting files.

Sample configuration files

To help describe the web server configuration file parameters, this section provides examples of connector-specific web server properties. These examples assume that JRun and the web server are on the same computer.

Apache configuration file

The following is a typical httpd.conf file for an installation of ColdFusion on the same computer as an Apache 2.0 web server:

# JRun Settings
LoadModule jrun_module "C:/coldfusion8/runtime/lib/wsconfig/1/mod_jrun20.so"
<IfModule mod_jrun20.c>
JRunConfig Verbose false
JRunConfig Apialloc false
JRunConfig Ssl false
JRunConfig Ignoresuffixmap false
JRunConfig Serverstore "C:/coldfusion8/runtime/lib/wsconfig/1/jrunserver.store"
JRunConfig Bootstrap 127.0.0.1:51011
#JRunConfig Errorurl <optionally redirect to this URL on errors>
#JRunConfig ProxyRetryInterval <number of seconds to wait before trying to reconnect to unreachable clustered server>
#JRunConfig ConnectTimeout 15
#JRunConfig RecvTimeout 300
#JRunConfig SendTimeout 15
AddHandler jrun-handler .jsp .jws .cfm .cfml .cfc .cfr .cfswf
</IfModule>

IIS configuration file

For IIS, the connector uses the jrun.ini file to initialize the jrun.dll file (jrun_iis6.dll on IIS 6). The following is a typical jrun.ini file:

verbose=false
scriptpath=/JRunScripts/jrun.dll
serverstore=C:/coldfusion8/runtime/lib/wsconfig/1/jrunserver.store
bootstrap=127.0.0.1:51011
apialloc=false
ssl=false
ignoresuffixmap=true
#errorurl=<optionally redirect to this URL on errors>
#proxyretryinterval=<number of seconds to wait before trying to reconnect to unreachable clustered server>
#connecttimeout=<number of seconds to wait on a socket connect to a JRun server>
#recvtimeout=<number of seconds to wait on a socket receive to a JRun server>
#sendtimeout=<number of seconds to wait on a socket send to a JRun server>

Netscape, iPlanet, or Sun ONE configuration file

The following is a typical obj.conf file for Netscape, iPlanet, or Sun ONE Web Server:

Note: Java must be disabled for the virtual server class that contains the server configured for JRun.

...
<Object name="default">
AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true"
NameTrans fn="pfx2dir" from="/mc-icons" dir="C:/Sun/WebServer6.1/ns-icons" name="es-internal"
NameTrans fn="pfx2dir" from="/manual" dir="C:/Sun/WebServer6.1/manual/https"
NameTrans fn="document-root" root="$docroot"
PathCheck fn="nt-uri-clean"
PathCheck fn="check-acl" acl="default"
PathCheck fn="find-pathinfo"
PathCheck fn=find-index index-names="index.jsp,index.html,home.html,index.cfm"
PathCheck fn="jrunfilter"
ObjectType fn=type-by-exp exp=*.jsp type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.jws type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.cfm type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.cfml type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.cfc type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.swf type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.mxml type="jrun-internal/ext"
ObjectType fn=type-by-exp exp=*.cfr type="jrun-internal/ext"
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
Service method=(GET|HEAD|POST) type="jrun-internal/*" fn="jrunservice"
Service method="(GET|HEAD)" type="magnus-internal/imagemap" fn="imagemap"
Service method="(GET|HEAD)" type="magnus-internal/directory" fn="index-common"
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
Service method="TRACE" fn="service-trace"
AddLog fn="flex-log" name="access"
</Object>
...

The following is a typical magnus.conf file for Netscape, iPlanet, or Sun ONE Web Server:

...
Init fn="load-modules" shlib="C:/coldfusion8/runtime/lib/wsconfig/1/jrun_nsapi.dll" funcs="jruninit,jrunfilter,jrunservice"
Init fn="jruninit" serverstore="C:/coldfusion8/runtime/lib/wsconfig/1/jrunserver.store" bootstrap="127.0.0.1:51011" verbose="true" apialloc="false" ssl="false" ignoresuffixmap="false" #errorurl="<optionally redirect to this URL on errors>" connecttimeout="15" recvtimeout="300" sendtimeout="15"