# Installing ColdFusion on Solaris

ColdFusion is distributed as a Solaris package. You can use a number of Solaris package utilities, such as `pkgadd`, `pkgrm`, and `pkginfo` to manage the ColdFusion package file, as well as any other package files on your system.

This section addresses the following topics related to installing ColdFusion on Solaris:

- "Installing ColdFusion"
- "Upgrading from a previous release of ColdFuison"
- "Uninstalling ColdFusion"
- "Configuring Web servers for Solaris"
- "Using scripts to start and stop ColdFusion manually"

## Installing ColdFusion

Before installing ColdFusion please note the following considerations:

- The installation procedure assumes you are installing from a CD. If you purchased and downloaded ColdFusion from the Allaire Online Store, follow the download instructions found there and then follow the install procedure below, substituting the location you downloaded ColdFusion to for references to the CD.
- ColdFusion requires Solaris 2.5.1 or higher.
- You must be logged in as root to run the `pkgadd` utility.
- There are three versions of the Netscape NSAPI plug-in. The installation script will ask you which version of Netscape you are running if you choose to automatically configure a Netscape server.
- By default the package file installs ColdFusion into the `/opt` directory. If you want to install ColdFusion into a different directory, you must create that directory before running the `pkgadd` utility.
- Note the location and version number of your installed Web server. The `pkgadd` utility prompts you for this information.

| To install ColdFusion on Solaris:

1. Log in as `root`.
2. Load the ColdFusion CD-ROM into your CD drive.
3. Mount the CD-ROM on `/cdrom/cdrom0` if necessary.

   If the Solaris Volume Manager is active, you won't need to mount the CD.

4. Type `pkgadd -d /cdrom/cdrom0` to start the installation process.
5. Enter `cfusion` at the prompt and press Enter to select the ColdFusion package. Alternatively, you can just press Enter to accept the default (`All`), as ColdFusion is the only package available.
6. Enter the ColdFusion registration ID (serial number) when prompted.

   You'll find your ColdFusion registration ID on the product box.

7. Enter the name of the directory in which you want to install ColdFusion or accept the default directory.

   `/opt` is the default installation directory.

   Note | If you specified a directory other than the default, the installation script will create a symbolic link from `/opt/coldfusion` to wherever you installed ColdFusion.

8. Enter the name of the Web server you are running and press Enter or just press Enter if you are running the default Web server (Netscape Enterprise Server).
9. Press Enter to have the installation program automatically configure the Web server.

   The program loads the necessary plug-in for Netscape or module for Apache 1.3.x Web servers.

10. When prompted with whether to install ClusterCATS, press Enter to do so.
11. If you want the server on which you are installing ClusterCATS to be able to assume the IP address and HTTP traffic of a failed server in the cluster, press Enter to configure this server with failover services. Otherwise, enter `n` and press Enter.

    Typically, you want all of the servers in your cluster to be configured for failover, particularly if all of the servers have the same processing capacity. However, if you have a mixed server environment with some high capacity servers and several lower capacity servers, you may not want the less powerful machines to accept the additional load of unavailable servers in the cluster.

12. Enter your Web server's document root directory and press Enter.

    The default document root directory is determined by the Web server you are using.

13. When asked if you want to install Advanced Security, enter `n` and press Enter.

    You can install Advanced Security at a later time by re-running the pkgadd utility.

14. Enter the password you want to use to access the ColdFusion Administrator, which allows you to configure and modify settings for the ColdFusion Server.

    You'll be asked to re-enter the password for verification purposes.

15. Enter the password you want to use to connect to ColdFusion Server when developing applications with ColdFusion Studio.

    You'll be asked to re-enter the password for verification purposes.

16. Press Enter to install the ColdFusion documentation.

    The documentation is installed in the /`cfdocs` directory, which resides under the Web root directory.

17. Enter the user name under which ColdFusion will run or press Enter to run under the default user name (`nobody`).
18. Press Enter to begin the installation.

When the installation is complete, a shell script restarts the Web server and starts ColdFusion services. If the ColdFusion services are not started automatically, you can start them manually using the ColdFusion start-up script, which is found in the `/etc/inet.d` directory. See "Using scripts to start and stop ColdFusion manually".

## Upgrading from a previous release of ColdFuison

When upgrading from an earlier release of ColdFusion on Solaris, you may need to edit the package installation defaults file before running the pkgadd utility. The package installation defaults file is located in the following location:

    /var/sadm/install/admin/default

This file controls the behavior of the Solaris packaging commands. The value of the instance setting may need to be changed from `quit` or `unique` to `overwrite`. Setting the value of the instance to `overwrite` allows the existing version of ColdFusion to be overwritten by the new version.

After modifying the package installation defaults file, install your new release of ColdFusion following the steps in "Installing ColdFusion".

## Uninstalling ColdFusion

Use the `pkgrm` utility to remove an installed version of ColdFusion.

Note | The uninstall script removes your `odbc.ini` file and all Verity collections. Therefore, you may want to preserve these items by saving them to a new location before uninstalling ColdFusion.

| To uninstall ColdFusion:

1. Log in as root.
2. Enter the following command at the prompt:

   `pkgrm cfusion`

   ColdFusion is deleted from your server.

## Configuring Web servers for Solaris

If you run Netscape or Apache Web servers in conjunction with ColdFusion on Solaris, you must perform several Web server configurations for ColdFusion to work properly. This section addresses the following topics:

- "Configuring the Netscape Web server"
- "Configuring the Apache Web Server"

### Configuring the Netscape Web server

The ColdFusion NSAPI plug-in has been tested with Netscape Enterprise Server versions 2.01, 3.0, and 3.5.1, and the Netscape FastTrack Web Server 2.01. The installation script prompts you to automatically configure either of these servers. If you do not want the script to configure the Netscape plug-in, you can configure it manually. See "To configure the Netscape plugin:".

#### Choosing the right plug-in version

Netscape plug-ins for ColdFusion are installed in the `<installdir>/coldfusion/webserver/nsapi` directory. Use the following table to select the proper plug-in file.

ColdFusion Plugins for Netscape
Use this Plugin | With this Netscape Server Product | With this Version of Solaris
--- | --- | ---
coldfusion2x.so | Netscape Enterprise Server 2.01 Netscape FastTrack 2.01 | 2.51 or higher 2.6
coldfusion3x.so | Netscape SuiteSpot Enterprise Server 3.0 Netscape FastTrack Server 3.0 Netscape Enterprise Server 3.51 | 2.51
coldfusion35.so | Netscape Enterprise Server 3.51 | 2.6 or higher

Note | The Netscape 3.0 servers will not work on Solaris 2.6 with ColdFusion. You should use version 3.51, which Netscape certifies for use on Solaris 2.6.

The following procedure assumes you have the Enterprise 3.0 server installed in `/usr/netscape/suitespot` on the machine named `smurf`.

| To configure the Netscape plugin:

1. Copy the appropriate plugin (see table above) to a directory in your server directories. Name it `coldfusion.so`.

       mkdir /usr/netscape/suitespot/plugins/coldfusion
       cp /opt/coldfusion/webserver/nsapi/coldfusion3x.so \
           /usr/netscape/suitespot/plugins/coldfusion/coldfusion.so

2. Edit the `/usr/netscape/suitespot/https-smurf/config/mime.types` file to add a new ColdFusion type. Add the line:

       type=magnus-internal/cold-fusion exts=cfm,dbm

3. Edit the `/usr/netscape/suitespot/https-surf/config/obj.conf` file to add new service and init directives. Add all of the following syntax on one line:

       Init fn="load-modules" shlib="/usr/netscape/suitespot/
       plugins/coldfusion/coldfusion.so" funcs="DoCFRequest"

4. Add the following line in the default Object:

       Service fn="DoCFRequest" method="(GET|POST)"
       type="magnus-internal/cold-fusion"

5. Stop and restart the Web server.

   If you run the Netscape Server Manager, Netscape's browser-based administrator, you may get a warning about edits to the Netscape configuration files. This is normal. Follow the instructions and click on the Apply button to reload the new configuration files.

6. Test the setup by accessing the ColdFusion Administrator by entering the following URL in your browser:

       http://localhost/CFIDE/administrator/index.cfm

   If your server does not restart, check to make sure the pathname for the plug-in you specified in the `obj.conf` file is correct for your installation and that it is on a single line.

#### Updates made to Netscape configuration files after installing ClusterCATS

If you select the ClusterCATS load balancing and high availability installation option when installing ColdFusion, the ClusterCATS installation process updates the Netscape `magnus.conf` and `obj.conf` configuration files.

Note | The sections that the ClusterCATS installation script modifies are enclosed by Start BT and End BT comment blocks.

#### obj.conf

    # Netscape Communications Corporation - obj.conf
    # You can edit this file, but comments and formatting changes
    # might be lost when the admin server makes changes.

    #Start BT:  Add Init routines and Entry points
    Init fn=load-modules shlib="<ClusterCATS Install Dir>/btcats/
    teserver.so"
    funcs="btcats_server_init,btcats_nsapi_AuthTrans,btcats_nsapi_NameTrans,
    btcats_ErrorFixup"
    Init fnInit fn="btcats_server_init"
    #End BT:

    Init fn="flex-init" access="/local1/netscape/https-skagway/logs/access"
    format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
    \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req-
    >srvhdrs.content-length%"
    Init fn="load-types" mime-types="mime.types"
    <Object name="default">
    #Start BT: Entry Points
    NameTrans fn=btcats_nsapi_NameTrans
    AuthTrans fn=btcats_nsapi_AuthTrans
    Error fn=btcats_ErrorFixup reason="BrightTiger"
    #End BT:

    NameTrans fn="pfx2dir" from="/ns-icons" dir="/local1/netscape/ns-icons"
    NameTrans fn="pfx2dir" from="/mc-icons" dir="/local1/netscape/ns-icons"
    NameTrans fn="document-root" address="192.168.0.220" root="/local1/
    netscape/root-wrangle"
    NameTrans fn="document-root" address="192.168.0.173" root="/local1/
    netscape/root-kodiak"
    NameTrans fn="document-root" root="/local1/netscape/root-skagway"

    PathCheck fn="unix-uri-clean"
    PathCheck fn="check-acl" acl="default"
    PathCheck fn="find-pathinfo"
    PathCheck fn="find-index" index-names="index.html,home.html"
    ObjectType fn="type-by-extension"
    ObjectType fn="force-type" type="text/plain"
    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)" type="*~magnus-internal/*" fn="send-file"
    AddLog fn="flex-log" name="access"
    </Object>

    <Object name="cgi">
    ObjectType fn="force-type" type="magnus-internal/cgi"
    Service fn="send-cgi"
    </Object>

#### magnus.conf

    ServerRoot /local1/netscape/https-skagway
    ServerID https-skagway
    ServerName skagway.brighttiger.com
    #Start BT:  Remove Address line from magnus.conf.  This will cause
    #the Netscape Server to listen on INADDR_ANY
    #Address 192.168.0.24
    #End BT:
    Port 80
    LoadObjects obj.conf
    RootObject default
    ErrorLog /local1/netscape/https-skagway/logs/errors
    PidLog /local1/netscape/https-skagway/logs/pid
    User root
    MtaHost localhost
    NntpHost name-of-news-server
    DNS off
    Security off
    Ciphers +rc4,+rc4export,+rc2,+rc2export,+des,+desede3
    SSL3Ciphers
    +rsa_rc4_128_md5,+rsa_3des_sha,+rsa_des_sha,+rsa_rc4_40_md5,+rsa_rc2_40_
    md5,-rsa_null_md5
    ACLFile /local1/netscape/httpacl/generated.https-skagway.acl
    ClientLanguage en
    AdminLanguage en
    DefaultLanguage en
    AcceptLanguage off
    RqThrottle 128

### Configuring the Apache Web Server

ColdFusion has been tested with Apache version 1.2.x and 1.3. To obtain Apache free of charge, go to the Apache Web site at http://www.apache.org.

You can build the ColdFusion module into your Apache Web server binary. This method is efficient because the server does not have to start a new process for every ColdFusion request. This section describes:

- "Adding the ColdFusion module to Apache 1.2.x"
- "Adding the ColdFusion module to Apache 1.3.x"

Note | If necessary, consult the Apache ReadMe file for additional information (README.Apache)

#### Adding the ColdFusion module to Apache 1.2.x

The ColdFusion module can be found in the installation directory (usually `/opt`) under the `coldfusion/webserver/apache` directory.

The following procedure assumes that your Apache Web server is installed in `/usr/local/etc/httpd` and you installed ColdFusion in `/opt`.

| To add the ColdFusion module:

1. Copy the module (`mod_coldfusion.a`) to your Apache source directory.

       cp /opt/coldfusion/webserver/apache/mod_coldfusion.a \
           /usr/local/etc/httpd/src/mod_coldfusion.a

2. Edit the `/usr/local/etc/httpd/src/Configuration` file to contain the following line:

       Module coldfusion_module mod_coldfusion.a

3. If you are using the Sun C compiler, edit the `EXTRA_LIBS=` line to include the C++ library:

       EXTRA_LIBS=-lC

   If you are using the gcc compiler, you should add the absolute path of the C++ library to this line. You should include the version number of the library and use the highest one available.

   For example:

   EXTRA_LIBS=/usr/lib/libC.run.so.1
4. Run the Configure script to regenerate the configuration.

       ./Configure

5. Run `make` to build a new Apache httpd executable.
6. Install the new httpd executable in your installation directory and restart httpd.

You should now be able to access the ColdFusion Administrator with the following URL:

    http://localhost/CFIDE/administrator/index.cfm

#### Adding the ColdFusion module to Apache 1.3.x

You can find the ColdFusion module in the installation directory (usually `/opt`) under the `coldfusion/webserver/apache` directory. The pre-built module shipped with ColdFusion 4.5 is built with Apache 1.3.6. This module will not work with earlier versions of Apache 1.3.x, and it may not work with later versions if the Apache Group changes the MODULE_MAGIC_NUMBER_MAJOR (src src/include/ap_mmn.h in the Apache source).

Note | The module has been tested with Apache 1.3.9.

If you have a C compiler (gcc or SUN cc) available, you can build a version of mod_coldfusion.so which should work with any versionof Apache 1.3.

| To configure and add the ColdFusion module:

In order for the Apache httpd to load the ColdFusion module at startup time, you must have configured the `mod_so` module. This module is not built into Apache by default. If necessary, consult the Apache documentation for details (README.DSO).

Configure this module into the Apache build by running the following command:

`$ ./configure --enable-module=so <other apache options>
$ make
$ make install`

If you are using gcc to compile Apache, you should include the following environment variables for configure:

`$ env LIBS=/usr/lib/libC.so.5 CFLAGS=-fPIC \
./configure --enable-module=so <other apache options>`

Once you have `mod_so` configured in to your Apache binary, the simplest way to configure the ColdFusion module is to use the apxs program that is included in the Apache distribution. It is installed by default in `<apachedir>/apache/bin`. This is a perl script, so you must have perl installed on your system. Perl is freely available at http://www.perl.com.

| To use the apxs program:

1. Ensure that perl is available in `/usr/local/bin/perl`.

   Also, make sure a C compiler is in your PATH.

2. Add the `apache/bin` directory to your path:

   `csh:`

   `set path=($path /usr/ccs/bin /usr/local/apache/bin)`

   `sh/ksh:`

   `PATH=$PATH:/usr/ccs/bin:/usr/local/apache/bin`

   `export PATH`

3. Change to the `apache/src` directory in the ColdFusion installation.

   `cd /opt/coldfusion/webserver/apache/src`

4. Run the apxs command to build mod_coldfusion.so by entering the following command:

   `make`

5. Run the apxs command to add the module to the Apache configuration by entering the following command:

   `make install`

6. Restart your Apache server by entering the following command:

   `apachectl restart`

| To configure the Apache module that Allaire provides:

1. Copy the ColdFusion module to the Apache modules directory:

   `cp /opt/coldfusion/webserver/apache/mod_coldfusion.so \ /usr/local/ apache/libexec`

2. Edit your httpd.conf file to include the following directive:

   `LoadModule coldfusion_module libexec/mod_coldfusion.so`

   Note | If you have a ClearModuleList directive in httpd.conf, you will need to add the following directive to the AddModule list as stated by the comments in the httpd.conf file: `AddModule mod_coldfusion.c`

3. Restart apache.

   You should now be able to access the ColdFusion Administrator with the following URL:

   `http://localhost/CFIDE/administrator/index.cfm`

## Using scripts to start and stop ColdFusion manually

ColdFusion provides two scripts for starting and stopping ColdFusion processes manually:

    <installdir>/colfusion/bin/start
    <installdir>/colfusion/bin/stop

Note | You must be logged in with root privileges to run these scripts.

The ColdFusion installation scripts also installs the following scripts to start and stop ColdFusion during system boot and shutdown:

    /etc/init.d/coldfusion
    /etc/rc1.d/K19coldfusion
    /etc/rc3.d/S25coldfusion

ColdFusion runs the following processes on the system:

- `cfexec` -- Starts/stops the other processes and manages page scheduling
- `cfserver` -- The application server process
- `cfrdsservice` -- Provides system support for the Administrator as well as security and debugging services for ColdFusion Studio

The following processes also run if you've installed the ClusterCATS for ColdFusion option:

- `ipaliasd` -- Provides IP failover capability for ColdFusion Server
- `reqmgr` -- Processes ClusterCATS operations as root