HAHTsite Application Server Installation Guide

(1)

HAHTsite Application Server

Installation Guide

(2)

Server

Installation

Guide

release 4.0

(3)

July 1999 MN04-C-00-400-00

Notice

No part of this publication may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without the prior written consent of HAHT Software, Inc. Information in this document is subject to change without notice. Names and information used in examples are fictitious.

U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraph (c)(1) and (2) of the Commercial Computer Software—96 Restricted Rights at FAR 52.227-19, as applicable. Contractor is HAHT Software, Inc., 4200 Six Forks Road, Raleigh, NC 27609. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.

Trademarks

HAHT, HAHT Software, HAHTsite, e-Scenario, and “e-nable your enterprise” are trademarks or U.S. registered trademarks of HAHT Software, Inc.

This product includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/).

Any other corporate names, product names, tradenames, trademarks, service marks, or service names owned or registered by any other company and mentioned herein are the property of their respective companies. Specifications subject to change without notice.

HAHT Software, Inc. 4200 Six Forks Road Raleigh, NC 27609 USA

(919) 786-5100 (888) 438-4248 (in the USA) (919) 786-5200 (Technical Support)

(4)

About This Book

What’s in this book . . . vii

What’s in this book

The following table summarizes the contents of this book:

Chapter/Appendix Contents

Chapter 1, “Planning Your Installation”

Gives a functional overview of configuring the HAHTsite Application Server. It also describes the various roles a machine can play, and how the Application Server interacts with other components in various configurations.

Chapter 2, “Installing the HAHTsite

Application Server (Windows NT)”

Describes how to install the Application Server in a Windows NT environment.

Chapter 3, “Web server configuration (WinNT)”

Describes how to configure your Web server using the Web Server Utility.

Chapter 6, “Database configuration”

Describes how to configure your Application Server to work with database connections.

Appendix A, “Setting up NSAPI, ISAPI, and the Oracle Cartridge”

Describes how to configure NSAPI, ISAPI, and the Oracle Cartridge for use with the HAHTsite Application Server.

(9)

About This Book

Other HAHTsite products

In addition to the Application Server and Application Server Administrator utility, the HAHTsite family of products includes:

• The HAHTsite IDE, a complete environment for building, publishing, and maintaining Web applications. Web developers use the suite of tools that come with the IDE to create their Web site applications.

• The HAHTsite IP, a subset of the IDE consisting of the features used by page layout artists, graphics designers, and content editors.

Conventions

The conventions used in this book are described here.

HAHTsite Application Server installation directory

The directory into which you install the HAHTsite Application Server is called the Application Server installation directory. This book uses the variable HAHTsiteInstallDir as a placeholder for the Application Server installation directory (e.g., c:\HAHTsite). When you see this variable, you should replace it with the name of the Application Server installation directory on your system.

Here is an example:

1 Copy the files from HAHTsiteInstallDir\bin into the Web server’s CGI-BIN directory.

(10)

Continuation characters in sample code

Some lines of sample code are too long to fit on one line. In that case, this book uses the HAHTtalk Basic line-continuation character (“_”) at the end of a line. Example:

Function Create (instanceHandle As Long, createTime As Integer, _ scopeCount As Long) As Integer

HAHT Software’s commitment to you

We want you to be completely satisfied with your HAHT Software products. If you have questions about HAHTsite, the HAHTsite IDE, the HAHTsite IP, or the HAHTsite Application Server, you can contact HAHT Software in the following ways:

Telephone

• (919) 786-5200 Technical Support (Voice)

• (919) 786-5252 Technical Support (FAX)

• (888) 438-4248 Sales (Voice—in the USA)

• (919) 786-5100 Office (Voice)

• (919) 786-5250 Office (FAX)

Email

• [email protected] General Information

• [email protected] Sales

• [email protected] Support

World Wide Web

• www.haht.com

(11)

(12)

1

Installation

What’s in this chapter ... 2

Machine roles: control, background, and foreground hosts... 2

Control host... 3

Foreground host... 3

Background host ... 4

Other configuration considerations ... 4

(13)

Chapter 1: Planning Your Installation

What’s in this chapter

Before you install the HAHTsite®_{Application Server, you should understand} the various installation configurations and determine the best configuration for your site. This chapter gives a functional overview of configuring the HAHTsite Application Server. It also describes the various roles a machine can play and the way the Application Server interacts with other components in various configurations.

Note - This book deals exclusively with the full version of the

HAHTsite Application Server. If you plan to run both the Developer Edition and the full Application Server on a single machine, be sure to name your full Application Server installation something other than “Default,” as this name would create a conflict with the Developer Edition

installation.

Configuration considerations

Before you begin installing the HAHTsite Application Server, you must decide on an installation configuration for your site. The Application Server can be installed on any combination of one or more machines.

The HAHTsite Application Server’s open-ended, modular design provides for an incredible flexibility of configuration. The Application Server need not reside on the same machine as the Web server, and can be installed on one or more “host” machines depending on your specific needs.

Machine roles: control, background, and

foreground hosts

There are three roles that a host machine can play in an Application Server configuration: control host, background host, and foreground host. Typically, a host machine plays only one of these roles at a time. However, in some configurations, a single machine can play more than one role at a time.

(14)

machines in a configuration are referred to as “hosts.” A host machine may or may not have a Web server installed, depending on the role it is playing in the configuration.

Control host

In each Application Server installation, you must designate one machine as the control host. The control host runs the HAHTsite Application Server and the HAHTsite Administration Server, and must have a Web server installed. The Application Server should always be installed on the control host first. The control host stores configuration information for all of the foreground and background hosts. The master control process, hscontrol, runs on the control host and is responsible for:

• processing and verifying requests from foreground hosts and background hosts

• monitoring and updating the status of all host machines

• notifying the foreground hosts when background hosts or server groups on background hosts start or stop, or are added or removed

• broadcasting admin utility messages to all of the hosts

The Application Server Administrator utility runs on the control host. Because this utility is a Web-based application, it can be accessed from any Internet connected machine, through a Web browser.

Backup control host

In addition to the primary control host, you can define additional backup control hosts. Should the primary control host fail, a backup control host takes over control functions for the cluster until the primary control host becomes available. The primary control host then takes over control host functions.

Foreground host

A foreground host runs the Application Server (including the hsrun process), a Web server, and the HAHTsite “Redirector” process. The Redirector process distributes requests for new application sessions among the configuration’s background hosts.

(15)

This means that the CGI alias used to find hsrun should be the same on all foreground hosts, and if you have ISAPI or NSAPI configured on one foreground host, you should have it configured on all foreground hosts.

Note - Because the HAHTsite applications don’t actually

execute on a foreground host, a foreground host performs no database access, and therefore does not need to have database client software installed, or have data source names

configured.

Background host

A background host runs the HAHTsite Application Server and delivers dynamic pages. You can have one or more background hosts. A background host receives requests for dynamic pages from the hsrun process running on a foreground host.

Note - If your application will be performing database access,

each of your background hosts must have the necessary database client software installed, and any necessary data source name(s) configured.

Other configuration considerations

Application Server configurations vary among sites. In addition to having various combinations of foreground and background hosts, your

configuration can involve machines with different operating systems, and/or a firewall machine.

Heterogeneous configurations

Foreground and background hosts can run different operating systems (NT, Solaris, HP/UX, and AIX) in any combination.

Firewall configurations

Foreground and background hosts can run outside or inside a firewall, in any combination. In most cases, the control and background hosts reside behind the firewall. When you install the Application Server with a firewall, you will

(16)

Load distribution

The HAHTsite Redirector process, hsredir, runs on each foreground host, and distributes requests for new sessions among the background hosts.

Round-robin distribution is used by default. You can optionally specify a relative performance number for each background host. The Redirector then assigns requests to hosts using a weighted distribution, based on performance factors.

For example, if background hosts X, Y, and Z are given relative performance factors of 20, 30, and 50, they will receive approximately 20%, 30%, and 50% of the session assignments. Once a session has been assigned to a particular background host and Application Server process, all dynamic pages for that state ID are run on that host and process.

Once installation is complete, you can use the Application Server Administrator utility to define relative performance numbers for each background host.

Special notes for firewall installations

If you plan to install the HAHTsite Application Server with a firewall, you (or a system administrator at your site) must configure some machine ports before starting the installation procedure.

The firewall needs to have a range of “public” ports that will map to a range of “private” ports on the control and background host(s).

(17)

Each background host must have a range of dedicated ports defined. These ports are used to listen for requests from hsrun on the foreground host(s). The number of ports in the range must equal the number of Application Server processes, plus one. The extra port is set aside for the administrative process hsrexec. The hsrexec process receives requests for new sessions, and must have its own port.

For example, if a background machine is running 10 Application Server processes, and you enter a value of 9000, the server group will listen on ports 9000-9010. You would enter the base port value (9000) in the “Base of private IP port range” field during setup.

The port range on the firewall defines the corresponding range of firewall ports that the firewall maps to the private ports. For example, if you enter 8000, you should configure the firewall to map ports 8000-8010 on the firewall to 9000-9010 on the background host.

The firewall must be configured to allow www.thiscompany.com to access the TCP/IP ports on the inside.thiscompany.com by “tunneling” through the firewall. To do this, you must map a port on the firewall to a port on the

Foreground Background1 Background2 Control 9000 9002 9000 9003 9090 8005 8007 8001 8004 7000 hscontrol 3 processes 2 processes Public Private Firewall www.thiscompany.com inside.thiscompany.com

(18)

IDE or IP machines should reside behind the firewall as well. The transfer URL to the Web server (on the foreground host) must be a URL that can be accessed from inside the firewall. This usually means that publishing will be via FTP or HTTP.

(19)

(20)

2

HAHTsite Application

Server (Windows NT)

Introduction... 10

System requirements ... 10

What the installation program does ... 10

Important! Before You Start the Installation Procedure... 11

Running the setup program ... 15

To install the HAHTsite Application Server components... 15

Completing the installation ... 27

Requesting a new license key (control host only) ... 32

What’s next? ... 33

What other setup tasks do I need to perform? ... 33

To verify installation on foreground and background hosts ... 35

Verifying the installation ... 35

(21)

Chapter 2: Installing the HAHTsite Application Server (Windows NT)

Introduction

This chapter describes how to install and configure the HAHTsite Application Server on one or more Windows NT machines. The directions include special instructions for installing the Application Server on a control host (both primary and backup), foreground host, and background host.

System requirements

If you install the Application Server as a background host, the computer requires at least:

• Windows NT 4.0 • 32 MB RAM

• 15 MB free disk space

The disk requirements are less on the control and foreground machines. The amount of memory used by the Application Server depends on the complexity and number of HAHTsite applications running simultaneously. You should install the Application Server software using the above system requirements as a starting point. Later, you can fine-tune your system using the guidelines in Chapter 5, “Tuning Tips,” in the HAHTsite Application Server Administration Guide.

What the installation program does

(22)

• Creates an installation directory tree (if it doesn’t already exist) with the following subdirectories:

• approot (only on control and background hosts) • audit

• bin

• cgibin (only on control and foreground hosts)

• conf. On the control host, the directory will contain these four subdirectories: ServerGroups, HostComputers, GroupHosts, and ControlHosts.

• doctree (only on control and foreground hosts) • javaroot (only on background hosts)

• lib • logs • program • samples

• sites (only on control and foreground hosts) • userroot (only on background and control hosts)

• Creates a HAHTsite program group containing icons for starting an uninstall utility, a Web configuration utility (only on control and foreground hosts) and the HAHTsite Application Server Administrator utility (only on control hosts).

• Creates configuration files used by the Administrator utility.

• Places the executable file (hsrun and dependent files) for the Application Server in a location where the Web server can find it (only on control and foreground hosts).

• Installs ODBC (only on background hosts).

• Creates an NT service (“HAHTsite 4.0 Controller,” “HAHTsite 4.0 Foreground,” or “HAHTsite 4.0 Background”) to run the HAHTsite Application Server Administrator, the default server group, and any additional server groups that you create.

Important! Before You Start the Installation Procedure

(23)

Item Description

Control host first Do not install the Application Server software on a foreground or background host until you’ve installed the Application Server on the primary control host.

The primary control host should be up and running before you install any foreground or background hosts, unless you plan to install the control and foreground or background hosts at the same time.

CORBA To use CORBA with HAHTsite, you need to install the Visibroker for Java components on at least one background host. For high availability configurations, we recommend you install the Visibroker for Java components on multiple background hosts.

In firewall configurations, you will also need to install the Visibroker for Java components on a foreground host, and use the Visibroker Gatekeeper to route CORBA requests through the firewall.

Determine machine roles

Decide which hosts will perform the control (primary or backup), foreground, and background roles. A host can perform more than one role. For example, you can check both Foreground and Background; or a control host may also serve as either a foreground or background host. The setup program loads different software components on the hosts, depending on what role(s) they perform. For an overview of Application Server configurations, including a description of the host computer roles, see Chapter 1, “Planning Your Installation.”

Note - A server group can have only one primary

control host.

DNS names Determine the DNS names of all host computers that will participate in the Application Server. The setup program displays this information for your verification. Firewall Know whether any Application Server hosts are behind a

(24)

Java Virtual Machine installation

HAHTsite supports the following Java Vitual Machines: • Microsoft

• Sun 1.1.7

• Sun 1.2 (“Java 2”)

All hosts in your installation must use the same Java virtual machine.

Note - If you plan to use the Java 2 VM, see “Special

note on using the Sun Java 2 virtual machine” on page 14.

NSAPI/ISAPI If the NSAPI or ISAPI versions of hsrun are installed, you must also stop the Web server.

Previous Application Server installation

If you intend to overwrite a previous Application Server installation, be sure to stop it prior to running setup. Remote access If you will have HAHTsite IDE and/or IP users (on client

systems) publishing applications to the Application Server on a machine, you will need to grant remote access to those client systems for the following directories:

• The installation directory of the Application Server (on background hosts).

• Your Web server’s document root or doctree directory (on control and foreground hosts).

The installation will only recognize file sharing and FTP remote access methods. In the event that remote access to these directories is not setup before installation or you are using HTTP remote access, you can use the Application Server Administrator utility and the Web Server utility to change the local paths to remote paths following the completion of the installation. For information on using the Web Server Utility, see Chapter 3, “Web server configuration (WinNT).”

A default site definition will be created by the installation process. You may need to customize and verify the site to ensure that all IDE and/or IP clients can publish successfully following the completion of the installation.

(25)

Special note on using the Sun Java 2 virtual machine

If you want to use the Sun Java 2 (1.2) virtual machine for your HAHTsite applications, you will need to perform the following procedure(s) after running setup.

To configure your Application Server to use the Sun Java 2 VM

1 Edit your system PATH to include the following:

d:\jdk1.2\bin;d:\jdk1.2\jre\bin\classic

Where: d:\jdk1.2 is where you installed the JDK 1.2 compiler, d:\jdk1.2\jre is where you installed the Java VM for 1.2.

2 In the HAHTsite Application Server Administrator, click on Language. The

Language Options form appears.

3 Under Java Options, select the radio button for Sun 1.2. 4 Click Save Changes.

5 Still in the HAHTsite Application Server Administrator, click on

Directories. The Directories and Publishing Options form appears.

6 Edit the System Java Class Path as follows:

Replace %INSTALLDIR%\lib\rt.jar with the following: d:\JDK1.2\jre\lib\rt.jar;

Where: d:\jdk1.2\jre is where you installed the Java VM for 1.2.

Note - You must also add d:\JDK1.2\lib\tools.jar; to the Server group services If you have any HAHTsite server groups running as NT

services, stop them using the Services dialog on the Control Panel.

Web server Install your Web server (on the control and foreground machines). The setup program does not require the Web server software, but having the software installed and configured properly enables the setup program to automatically establish the interface between the Application Server and the Web server.

Note - Consider installing the Apache Web server

bundled with the HAHTsite IDE and IP setup program.

(26)

7 Click Save Changes. You can exit the HAHTsite Application Server

Administrator at this time.

Running the setup program

Note - Installation is not complete until you’ve run setup on

each machine in the configuration. You should first run setup on the control host, then on each foreground and background host.

To install the HAHTsite Application Server components

1 Log in to the Windows NT server using an account that has administrative

privileges. If the HAHTsite Application Server is currently installed and running on the server, stop it and any server groups.

2 Insert the HAHTsite Application Server CD-ROM into the appropriate

drive and start the setup program by selecting Run... from the Windows NT Start menu. Type drive:\WinNT\i386\setup.exe, where drive is the drive containing the CD-ROM.

Alternately, go to the Control Panel’s Add/Remove Programs dialog. On the Install/Uninstall tab, click Install and follow the prompts until the setup program starts.

A dialog informs you that the setup program is being prepared. If the setup program does not find a HAHTsite license in the system registry, the Software License Agreement dialog appears.

(27)

3 If the Software License Agreement is displayed on your screen, click Yes to

accept the terms of the license. If you click No, the setup program will be terminated.

(28)

5 Enter the Serial number found on the back of the HAHTsite Application

Server’s CD jewel case, and click Next.

Note - If you do not have a Java virtual machine (Java VM)

installed on this machine, or the Microsoft Java VM detected is not the most recent version, setup asks you if you want to install the Microsoft Java VM at this time. HAHTsite 4.0 does not require the Microsoft Java VM, but it is recommended because of its significant performance benefits. Click Yes, and follow the resulting installation instructions.

(29)

7 Select this host computer’s role(s) by selecting one or more check boxes.

Your selection will determine which Application Server components the setup program installs on this machine. Click Next.

Note - The installation is not complete until you’ve installed

the Application Server software components on all machines in the configuration.

• If this machine will be either a primary or backup control host, jump to Step 9 on page 19 to continue the installation procedure.

• If this machine will be a foreground or background host, the Setup Options screen appears.

(30)

8 Select one of the two setup options by clicking the option’s button. The

options are:

9 If there is a previous HAHTsite 3.1 or 4.0 Application Server installation on

this machine, setup asks you whether you want to overwrite a previous installation.

• If you click No, jump to Step 11 on page 20.

• If you click Yes, setup provides a list of previous installations.

Option Description

Typical Select Typical to install all Application Server software.

Custom Select Custom to perform a selective installation, or if you plan to use CORBA with your HAHTsite applications.

(31)

10 Select the radio button for the installation you want to overwrite, and

click Next. Jump to Step 13 on page 23.

11 Select an installation name.

Type a unique name for this Application Server installation in the Name field, and click Next. The Select Directory For Application Server 4.0 dialog appears.

(32)

Verify the installation directory, or click browse to select an alternate. Click Next to proceed with the installation.

If you have not set FTP or file sharing access for the selected directory, a warning appears to remind you that you will need to do so after the installation is complete.

Click Ok to dismiss the warning.

• If you selected Typical in Step 8, jump to Step 13 on page 23.

• If you selected Custom in Step 8, the Select Options to Install screen appears.

(33)

The Components box lists Application Server components. The checkbox beside each component is checked if the component is selected: click the box to select or exclude a component. Click the component name to see a description of the component in the Description box. Below the

Description box, the space requirements for the component, and space available, are displayed.

If you select ODBC Drivers, and then click the Change button, the Select Sub-components Dialog appears.

(34)

13 The firewall configuration screen appears.

Specify your firewall configuration. Select the radio button that describes your Application Server configuration, and Click Next.

• Select the first radio button if your site does not use a firewall. Jump to Step 15 on page 24.

• Select the second radio button if this machine will reside inside the firewall and one or more machines in this distributed configuration will reside outside the firewall.

• Select the third radio button if this machine will reside outside the firewall, and one or more machines in this distributed configuration will reside inside the firewall. Jump to Step 15 on page 24.

If you selected “This machine is inside a masquerading firewall AND...,” the Firewall Address screen appears.

(35)

14 Specify the firewall’s public address. Enter the public DNS name for your

firewall machine in the Public Firewall Address field. Click Next. The Administrative host information screen appears.

15 Specify the machine’s name and DNS address. If you are installing a

control host, specify the control port. Click Next.

• If you are installing a foreground or background host, jump to Step 17 on page 25.

(36)

16 Specify the master administrator.

Enter the master administrator’s username in the Username field.

Note - At this point, configuration for the control host is

complete. Go to “Completing the installation” on page 27.

17 The Control Host information screen appears.

(37)

Note - If this foreground host resides outside a firewall, and the

control host resides inside a firewall, you must provide the firewall name and port number that are mapped to the control host.

When you click Next in the Control Host Information dialog, the Master User ID dialog appears.

18 Specify the master user ID, password, and domain for the control host. (If

the control host is a UNIX server, the Domain field can be left blank.) Click Next.

Note - At this point, configuration for the foreground host is

complete. Go to “Completing the installation” on page 27.

The List of Server Groups screen appears (for background host installations only).

(38)

19 Select the server group to which you want this background machine to

belong. You can select only one server group. You can use the

Administrator utility to include other server groups on this background host.

At this point, configuration for the background host is complete. Complete the installation using the procedure that follows.

Completing the installation

(39)

Select the name of the program folder in which the Application Server program icons will be installed. You may select the default folder, choose an existing folder from the list, or type in a new folder name.

If you are installing on a background host, jump to Step 4 on page 31. Static Web server detection begins (on control and foreground

installations only).

If no static Web servers are detected, the Web Server Information dialog appears (see “Manual...” in the table on page 29).

The Web Server Detection – Static Alias screen appears.

2 Use the fields on the Web Server Detection – Static Alias screen to specify

static Web server settings. The fields are described below:

Field Description

Web Server Select a Web server from the list of available Web servers.

(40)

Click Next. Dynamic Web server detection begins (on control and foreground installations only).

If no dynamic Web servers are detected, the Web Server Information dialog appears (see “Manual...” in the table on page 31).

The Web Server Detection – Dynamic Alias screen appears.

Web Server Static Alias Shows the static alias location assigned to the Web server selected above.

Manual... If your Web server was not detected, click Manual... to enter the Web server information manually. The Web Server Static Information dialog appears.

If you do not supply this information, you may encounter problems during installation since setup attempts to make uninformed decisions about your web server configuration.

(41)

3 Use the fields on the Web Server Detection – Dynamic Alias screen to

specify dynamic Web server settings. The fields are described below:

Field Description

Web Server Select a Web server from the list of available Web servers.

Web Server Virtual Host

Select a virtual host computer from the list of hosts known to setup.

Web Server Dynamic Alias

Shows the dynamic alias location assigned to the Web server selected above.

(42)

Click Next.

4 File installation begins. As the software loads, the setup program displays

progress bars.

If your ODBC driver manager is currently in use, you will see the following warning dialog.

If you see this warning, and you plan to use the sample application that Manual... If your dynamic Web server was not detected, click

Manual... to enter the Web server information manually. The Web Server Dynamic Information dialog appears.

If you do not supply this information, you may encounter problems during installation since setup attempts to make uninformed decisions about your web server configuration.

(43)

“Adding an ODBC data source” on page 612 of the HAHTsite IDE and IP User’s Guide. Note that the data source must be called “HAHT_Intro40.”

5 View License Reminder (on control host installation only).

If you are installing on a control host, the User License Count dialog appears.

This dialog is intended to remind you that the Application Server will use a default license key that allows only five concurrent active user sessions. In order to increase the licensed number of active sessions, you must request a permanent license key from HAHT Software.

6 Complete the installation.

At this point, you are given the choice of reading the release notice. If you say no (or after you read and close the release notice), the Setup Complete dialog may appear if any DLLs could not be immediately updated because they were is use.

Indicate whether or not you want to reboot your computer now so the DLLs can be updated, then click Finish.

Requesting a new license key (control host only)

To request a new license key immediately after installation, go to the HAHTsite Program Group (in the Windows Start menu) and select How to Request a License Key. The following page is displayed in a Web browser.

(44)

You can click the [email protected] link to send an email request for a new license key to HAHT Software. To ensure security, the license key will be returned to you via email.

Optionally, you can click the HAHTsite Application Server Administration link to start the Application Server Administration utility. For more information about using the Administration utility, requesting a license key, and upgrading your user license count, see “Managing License Information” in the HAHTsite Application Server Administration Guide.

What’s next?

This section identifies any setup tasks that you still need to perform and directs you to a procedure for each task.

What other setup tasks do I need to perform?

The following table identifies the setup tasks that you must perform after the initial installation:

If... Then You Need to... Go to This Section

• Your Web server was not installed at the time of the installation. Or:

• Since installation, you’ve installed an additional Web server that you would like to use with HAHTsite.

After installing your Web server, start the Web Server utility from the HAHTsite program group. (In a distributed

configuration, this applies only to the control host and the foreground host.)

“Running the Web Server Utility” in the HAHTsite Application Server Administration Guide.

(45)

Any of your HAHTsite applications use databases (unless you plan to use only flat-file ODBC drivers).

Set up connectivity to an ODBC data source. The setup program installs ODBC, but you will not be able to use a database with your HAHTsite applications until you connect to an ODBC data source. This task needs to be performed on both the client and the server side. “Database Configuration” in the HAHTsite Application Server Administration Guide.

You allow HAHTsite IDE and/or IP users on client systems to publish applications to the Application Server.

Make sure the following directories are accessible via either file sharing, FTP, or HTTP transfers. • The installation

directory of the Application Server. • The Web server

document root or doctree directory A default site definition is created by the installation process. You may need to customize and verify the site to ensure that all IDE and/or IP clients can publish successfully.

Chapter 3, “Web Server and Database

Configuration” in the HAHTsite Application Server Administration Guide.

(46)

Note - Be sure to set FTP or file sharing access for the

installation directory if it was not done prior to installation.

Verifying the installation

When you install the Application Server in a distributed configuration, starting the Administrator utility verifies a successful installation on the control host.

To verify installation on foreground and background hosts

1 Start the Administrator on the control host, as explained in “Getting

Started with the Administrator” in Chapter 2 of HAHTsite Application Server Administration Guide.

2 Select the Host Computers button and verify that the green status

indicator is lit for all foreground and background hosts.

This verifies that the foreground and background hosts are successfully communicating with the control host.

Removing the Application Server

You installed a background host in a distributed configuration.

Configure one or more Distributed Server Groups to run on the background host. The Distributed Server Group(s) must be explicitly included on each background host. Also, the paths or URLs to use to publish dynamic components to the Server Group must be defined for each

background host.

Chapter 2, “Maintaining Server Groups” in the HAHTsite Application Server Administration Guide.

You plan to use a Sun Java VM to debug Java projects.

Install the Sun JDK on your background host.

(47)

1 Use the HAHTsite Application Server Administrator’s Applications option

to ensure that no server groups are in use.

2 Use the Application Server Administrator utility to stop all HAHTsite

server groups.

3 Use the Control Panel’s Services utility to stop any active NT services for

HAHTsite.

4 Select Start-> Programs-> HAHTSite Server-> Uninstall the HAHTsite

Application Server.

A confirmation dialog asks you to verify that you want to remove the program and all of its components.

5 Click Yes to uninstall the Application Server.

You can also remove the Application Server with the Add/Remove Programs procedure on the Control panel.

(48)

3

configuration

(WinNT)

Introduction... 38 About site configuration files ... 38 Using the Web Server Utility (Windows NT)... 39 Starting the Web Server Utility ... 39 What the Web Server Utility detects ... 41 Static page aliases... 41 CGI aliases... 42 To set up an interface to a detected Web server ... 42 To set up an interface to an undetected Web server... 44 Adding hsrun to a Web server’s CGI scripts directory ... 46 To copy hsrun to a Web server’s CGI scripts directory ... 46 To modify a configuration ... 47 To remove a configuration ... 48

(49)

Chapter 3: Web server configuration (WinNT)

Introduction

This chapter describes procedures that may be required to configure the HAHTsite Application Server with Web servers.

About site configuration files

When you install a foreground or control HAHTsite Application Server component on a machine, the HAHTsite installation program creates site configuration files that describe the interface between the Application Server and a Web server.

The Application Server side of this interface includes information about where the HAHTsite IDE/IP should publish static pages (to the Web server’s static page directory) and an alias to the Web server’s CGI directory (which contains the Application Server’s hsrun program files).

When the installation program runs, it (among other operations):

• Locates the Web server’s static page directory (the place where the Web server looks for static pages) and copies the pages needed by the HAHTsite Application Server Administrator utility to that directory. • Locates the Web server’s CGI directory (the place where the Web server

looks for executable programs) and copies the hsrun program files to that directory.

• Configures the URL Path to the Web server’s CGI directory.

• Sets up methods for transferring files from the IDE to the Web server and the Application Server.

This information is stored in the site configuration files listed in the following table:

File Type Description

CGI Alias (.hca) Contains information on how to build a URL pointing to hsrun. (This is the program that the Web server executes to route requests for dynamic pages to a HAHTsite Application Server.)

(50)

Using the Web Server Utility (Windows NT)

By default, the site configuration files listed in the table above are located in a host machine’s HAHTsiteInstallDir\sites directory.

Note - Although the site configuration files are stored in

Windows INI-style format, it is strongly recommended that you not edit the files “by hand.”

As shown in the table, .hsg files are managed by the Application Server Administrator utility, and .hst files are managed by IDE/IP site management dialogs.

You should edit .hca and .hdr files with the HAHTsite Web Server Utility (Web Server Utility). Here are some situations where you would want to use Web Server Utility:

• You installed a new Web server after installing a HAHTsite Application Server.

• You made changes to the configuration of the Web server you use with the Application Server.

• You want to customize the interface between a Web server and the Application Server, or remove an interface to a Web server that you no longer use.

Starting the Web Server Utility

You can start the Web Server Utility from the HAHTsite program group or from the HAHTsite installation directory

(HAHTsiteInstallDir\program\wsutil.exe).

Server group (.hsg) Created and updated by the Application Server Administrator utility.

Site definition (.hst) Created and updated by IDE/IP site management dialogs. These files store references to the .hsg, .hca, and .hdr files.

(51)

been previously added. The following figure shows the main dialog on an Application Server host with interfaces to a WebSTAR server and a Microsoft Internet Information Server.

The following table summarizes the functions of the utility’s five main buttons:

Button Function

Add Auto-Detected...

Display how detected Web servers are configured, along with the corresponding Application Server settings needed to accommodate that configuration. Optionally, save the displayed Application Server settings to .hca and .hdr configuration files.

Add Web Server... Set up an interface to Web server components that Web Server Utility does not detect, or add new components to an existing Web server.

Add HSrun... Place the HAHTsite hsrun programs into a Web server’s CGI directory.

Modify... Modify one or more Application Server settings of an existing interface.

(52)

If you’re building an interface to a newly installed or modified Web server, click Add Auto-Detected. This causes Web Server Utility to search the Registry for installed Web servers and display the results of the search in the Add Detected Web Server dialog. If the Web server you want to use is listed, proceed to the next section.

If your Web server does not appear, exit from the Add Detected Web Server dialog (click Cancel) and proceed to “To set up an interface to an undetected Web server” on page 44.

What the Web Server Utility detects

When Web Server Utility detects a Web server, it displays two types of entries in the Add Detected Web Server dialog: the Web server’s static page aliases and its CGI aliases.

Static page aliases

A Web server’s static page alias maps a URL to a file-system directory. When given a URL to a static page, the Web server uses the information in its static page alias to locate the file specified in the URL.

When you select a static page alias in Web Server Utility’s Add Detected Web Server dialog and click Add, Web Server Utility creates a new .hdr site configuration file. The .hdr file contains information that the HAHTsite

(53)

CGI aliases

A Web server’s CGI alias maps a URL to a program file. When given a URL to a CGI program, the Web server uses the information in its CGI alias to locate the program specified in the URL.

When you select a CGI alias in Web Server Utility’s Add Detected Web Server dialog and click Add, Web Server Utility creates a new .hca site configuration file. The .hca file contains the information the HAHTsite IDE/IP needs to build a URL to the HAHTsite Application Server’s hsrun program.

If you have Perl scripts or other program files that you want to publish to a Web server’s CGI directory, check the Add as Static box. Web Server Utility will create a new .hdr file, which will enable you to publish, from the HAHTsite IDE/IP, your program files to the Web server’s CGI directory.

To set up an interface to a detected Web server

Here are the recommended steps for setting up a configuration for a detected Web server and a HAHTsite Application Server.

1 Click and expand the Web server you want to use.

A typical Web server directory tree includes:

• A single directory whose name is the same as that of the host. • Under this directory, a list of the Web server’s static page and CGI

(54)

To examine a component that you may want to add, click to select the item and then click Properties.... For example, if you click /cgi-bin in the preceding figure and click Properties..., a dialog like the one shown below appears. (The fields in this dialog are read-only.)

The dialog in Figure 3-4 indicates that, on the host “barney,” the Netscape FastTrack administrator has created an alias named cgi-bin pointing to the HAHTsite directory d:\hahtsite\cgibin. The URL field shows the URL that points to this HAHTsite directory.

The following is an example of the dialog’s Port tab:

The Port tab indicates that the Netscape FastTrack server on Barney uses port 80 and searches directory d:\hahtsite\doctree for static files. The Web Server tab (not illustrated) displays the name and revision of the Web server.

3 After inspecting the information, click OK to return to the Add Detected

Web Server dialog.

(55)

If Web Server Utility identifies the component as a CGI directory, the checkbox “Add as Static” asks whether static pages should be published to this destination. Where not relevant, the checkbox is dimmed out. In most cases, you should accept the default (no).

If you have Perl scripts or other program files that you want to publish to a Web server’s CGI directory, check the Add as Static box. Web Server Utility will create a new .hdr file, which enables you to publish program files from your HAHTsite project to the Web server’s CGI directory.

Repeat these steps for all expanded items that you want to add. (The Add button is dimmed out if Add is not a relevant action.)

Clicking Add saves the Application Server configuration information you have inspected into the appropriate .hca and .hdr configuration files.

During inspection, if you see a configuration problem (for example, an incorrect URL to the Web server’s CGI directory), you can use Modify (see “To modify a configuration” on page 47) to change the Application Server’s configuration as needed to accommodate the Web server’s configuration. Alternatively, you can change the Web server’s configuration, using the Web server’s administration tool the run the Web Server Utility again.

To set up an interface to an undetected Web server

Here are the recommended steps for setting up an interface to an undetected web server:

1 If Web Server Utility does not detect your Web server, click Add Web

(56)

In this dialog, you can browse for and select Web server directories, construct URLs and aliases, and define methods for transferring information between the Web server and Application Server.

2 In the Name field, enter a name to identify this particular Web server

interface. This name will appear in the Web Server Utility’s main dialog.

3 From the Web Server Type list box, select the Web server’s type.

4 The Browse URL field contains a URL that points to the Web server’s static

(doctree) directory; change it as needed.

(57)

6 In the Protocol list box, select the method that will be used to transfer files

between the Web server and the Application Server: File Copy, FTP, or HTTP.

Note - The Web Server Utility specifies, but does not set up, the

transfer method. Thus, File Copy may require a shared directory, while FTP requires you to set up an FTP site. Web Server Utility does not set up these methods.

7 In the Path field, enter the Web server’s doctree directory.

This is the place where the Web server looks for HTML files. If you do not know the name of the directory, click the Browse box on the right of the field.

8 In the OS Type drop-down box, select the Web server host’s operating

system: Windows NT, Windows 95, or UNIX.

9 If you selected the FTP transfer protocol, you can optionally add a

Username and Password that will be used to logon to the FTP server when a project is published from the IDE/IP. You can also specify the number of retries if a file transfer fails.

If you do not specify a username and password, the IDE/IP user will be prompted to enter these values at publish time.

10 Click OK to return to Web Server Utility’s main dialog.

Note - In most cases, you will add only one transfer location

for a static page alias. However, you can add multiple transfer locations if, for example, you have a mirrored Web site or are using a router that can fetch pages from multiple locations.

Adding hsrun to a Web server’s CGI scripts directory

The HAHTsite hsrun program routes requests for dynamic pages to the Application Server. The URLs for HAHTsite applications include the location into which a Web server looks for the hsrun program. This location is typically a Web server’s CGI bin or scripts directory. Optionally, you can create, with the Web server’s administration utility, an alias to the HAHTsite installation directory’s CGI bin directory (which is, by default at

HAHTsiteInstallDir\cgibin.)

To copy hsrun to a Web server’s CGI scripts directory

(58)

2 Enter a name for the Web server in the Name field, and select its type from

the Web Server Type drop-down box.

3 The Browse URL field contains the URL that points to the Web server’s

CGI scripts directory: change this URL as required.

4 In the cgi-bin Directory field, enter the pathname of the Web server’s CGI

scripts directory,

or, Click the browse button on the right side of the field if you do not know the path.

5 Click OK to copy all the hsrun program files from HAHTsiteInstallDir\cgibin to the selected location.

To modify a configuration

You change configuration values from Web Server Utility’s main dialog. To do that:

(59)

To remove a configuration

You delete configuration values from the Web Server Utility main dialog.

1 Select the line for the value you want to remove and click Delete. 2 When prompted, click Yes to confirm that you want to delete the item.

(60)

4

HAHTsite Application

Server (UNIX)

Introduction... 50 System requirements ... 50 What the installation program does ... 51 Important! Before you start the installation procedure ... 52 Running the setup program ... 53 License information... 67 What’s next? ... 68 Java debugging setup for Solaris ... 71 Java debugging setup for HP/UX ... 71 Java debugging setup for AIX... 71 Connecting to an ODBC data source ... 72 Using the flat-file ODBC drivers ... 73 Editing .dbenv.conf... 73 Viewing the site definition page ... 74 Configuring your Web server after the installation ... 75 Verifying the installation ... 76 Removing the Application Server from your system ... 77

(61)

Chapter 4: Installing the HAHTsite Application Server (UNIX)

Introduction

This chapter describes how to install and configure the HAHTsite Application Server on a UNIX server.

The HAHTsite Application Server software is available for Solaris 2.5.1 or later, HP/UX 10.20 or later, and AIX 4.2.1 or later.

System requirements

The HAHTsite Application Server requires at least:

• A workstation or server with Solaris 2.5.1 or later, HP/UX 10.20 or later, and AIX 4.2.1 or later.

• 64 MB physical RAM. Swap space or virtual RAM should be a multiple (by at least four) of physical RAM.

• 45 MB of free disk space.

• Any Web server that supports CGI 1.1 or greater.

• JDK 1.1.2 or greater (with native threads) is required on AIX and HP/UX to enable server-side Java in HAHTsite applications and must be installed separately. As of the writing of this document, JDKs for these platforms could be downloaded from www.ibm.com/java/sitemap.html or

www.hp.com/go/JAVA respectively. (The Java Runtime Environment is distributed with the Application Server for Solaris.)

• If you install ODBC 3.0, you will need an additional 26 MB of free disk space (typically in /opt/odbc).

The amount of memory used by the Application Server depends on the complexity and number of HAHTsite applications running simultaneously. You should install HAHTsite using the above system requirements as a starting point. Later, you can fine-tune your system using the guidelines in the HAHTsite Application Server Administration Guide.

(62)

What the installation program does

The installation program does all of the following if you install the Application Server onto a single host. If you install the Application Server in a distributed configuration, the program does what is appropriate for each host type, as indicated.

• Creates an installation directory tree if it doesn’t already exist: • approot (on background and control hosts only)

• bin (on background, foreground, and control hosts) • cgibin (on control and foreground hosts only)

• conf (on background, foreground, and control hosts). On the control host, the directory will contain these four subdirectories:

ServerGroups, HostComputers, GroupHosts, and ControlHosts. If HAHTsite authentication is used, file hspasswd is also added. • logs (on background, foreground, and control hosts)

• sites (on foreground and control hosts only) • userroot (on background and control hosts only)

• Creates configuration files used by the Administrator utility (on background, foreground, and control hosts).

• Places the executable file (hsrun and dependent files) for the Application Server in a location where the Web server can find it (on control and foreground hosts).

• Sets the user and group file ownership for the Application Server (on background, foreground, and control hosts).

• If you install the software as root, sets the User ID and Group ID that are used to start the Application Server automatically at system start-up (on control host only). If you install as an account other than root, you must start the Application Server manually.

• Configures your database environment.

• Installs ODBC if you do not already have ODBC installed (on background hosts only). Copies the odbc.ini RC file from the ODBC directory to the users’s login directory. Sets the user and group ownership of the ODBC files.

• Configures your Web server to use NSAPI (if the Web server supports NSAPI) and to use standard CGI (on control and foreground hosts only).

(63)

• Installs and configures the HAHTsite Application Server Administrator utility (on the control only).

• Logs the information displayed during the installation to a file named install.log in the installation directories of the Application Server and ODBC (on background, foreground, and control hosts).

Important! Before you start the installation procedure

Before you start the installation procedure, you should:

• Install your Web server (on the control and foreground hosts, if you’re installing into a distributed configuration). The setup program requires the Web server software to be installed in order to establish the interface between the Application Server and any Web servers. You have the option of reconfiguring the Web server later, by running the Web Server utility (wsutil) from the shell.

• The Web configuration utility will discover or build, for any installed Web server:

• The path to its CGI scripts directory and any alias for the directory • The URL path to the Web server

• The path of the Web server’s doctree directory

• If the Application Server has been installed previously in the same installation directory, stop it. If the NSAPI version of hsrun is installed, you must also stop the Web server.

• If you are going to build HAHTsite applications that use a vendor-specific relational database, you need to know the correct system-specific settings for the environment variables listed below. The setup program configures the environment variables for you if you supply the values during the installation. Otherwise, you can configure the environment variables after the installation (see “Editing .dbenv.conf” on page 73).

• Oracle — ORACLE_HOME (the base directory used by Oracle to locate its binary files and the correct instance of Oracle).

• SQL Server/System 10.x or 11.x — SYBASE (the home directory where SQL Server/System 10.x or 11.x is installed).

• Informix — INFORMIXDIR (the home directory where Informix is installed) and INFORMIXSERVER (the server name where Informix is installed. This parameter is required for Informix).

(64)

Before starting to install the Application Server in a distributed configuration, you should:

• Know the TCP/IP names and addresses of all host computers that will participate in the distributed Application Server configuration. The setup program displays this information for your verification.

• Know whether any Application Server hosts are behind a firewall. If so, know their private IP addresses.

• Decide which hosts will perform the control, foreground, and background roles. (For an overview of distributed configurations, including a description of these host computer roles, see Chapter 1, “Planning Your Installation.”) The setup program loads different software components on hosts depending on what role(s) they perform.

Running the setup program

If you are installing into a distributed configuration, note:

• Installation is not complete until you’ve run setup on each host in the configuration. Follow this sequence:

• Run setup on the control host.

• Make sure that the control host is up and running, then run setup on each foreground and background host.

This section describes how to run the setup program. The setup procedure is broken down into the following parts:

1 Starting the installation script 2 Following the installation script

Note - The procedures do not show all of the informational

text that appears on the screen during the installation. Information displayed during the installation can be found in the log files named install.log in the installation directories of the Application Server and ODBC.

Starting the installation script

1 Log in with the login account that you want to use for the installation. 2 Insert the CD-ROM into the appropriate drive. At the UNIX prompt type:

(65)

The subdirectory structure on the CD is as follows: • solaris/sparc

• hpux/version_number • aix/version_number

(where version_number is the version of the operating system under which the release was built—for example, aix/4.x).

3 Change directory to the appropriate subdirectory (above) and start the script by typing:

setup.csh

Following the installation script

1 The setup script displays the license agreement, with the following

prompt:

Do you accept all the terms of the license agreement[RETURN=NO]? Type “yes” to accept the agreement, or press Return to accept the default, no, and cancel the installation.

2 Setup displays a warning about unauthorized reproduction of this

software, and prompts you to see if you want to continue the installation. Would you like to continue the installation of HAHTsite

Application Server [RETURN=YES]:

Press Return to accept the default, yes, or type “no” and press Return to cancel the installation.

######### Select installation location for HAHTsite #########

3 Next, setup asks for the parent directory for the installation. The

installation program will create a directory called HAHTsite under the specified directory.

Enter parent directory to install HAHTsite. [RETURN=/default]: Press Return to accept the default, or type an alternate directory and press Return. If the specified directory does not exist, setup will create it for you. The parent directory /specified/ does not exist...

@@@@@@@@ Info: HAHTsite parent directory created @@@@@@@@

4 Setup now checks for any previous Application Server installations on this

machine. If none are found, jump to Step 8. Otherwise, continue to the next step.

(66)

#### A Previous Application Server Already Installed #### A previous Application Server installation has been found installed at /InstallDir/HAHTsite.

Do you want to overwrite the previous installation[RETURN=NO]: Press Return to accept the default, “No,” or type “y” to overwrite the previous installation. If you choose to overwrite the previous installation,

jump to Step 8. If you choose “No,” continue to the next step.

6 Enter the name that you would like to associate with this Application

Server installation.

#### Application Server Installation Name ####

Please enter Installation and Initial Server Group Name. [RETURN=webapps]:

Press Return to accept the default, “webapps,” or type a server group name and press Return.

7 Select a parent directory for the application server. The Application Server

base directory /HAHTsite will be created within the parent directory you choose.

#### Select Directory For Application Server #### Parent destination directory?

[RETURN=/InstallDir/InstallName]:

Press Return to accept the default, or type an alternate directory and press Return. If the specified directory does not exist, setup will create it for you.

8 Setup now checks to ensure there is enough space available on the disk for

the installation.

###Checking for available disk space for HAHTsite#### When setup has verified sufficient disk space is available for the

installation, it prompts you for your HAHTsite Application Server serial number, found on the CD jewel case.

Enter serial number:

Enter the serial number and press Return.

If the serial number is accepted, continue on to the next step.

9 Choose the role(s) (control host, foreground host, background host) that

you wish this server to play in the distributed configuration. If you are unfamiliar with the definitions of these roles, read the text displayed by

HAHTsite Application Server Installation Guide

HAHTsite Application Server

Installation Guide

Server

Installation

Guide

release 4.0

Notice

Trademarks

What’s in this book

Other HAHTsite documentation

Other HAHTsite products

Conventions

HAHTsite Application Server installation directory

Continuation characters in sample code

HAHT Software’s commitment to you

Telephone

Email

World Wide Web

1

Installation

What’s in this chapter

Configuration considerations

Machine roles: control, background, and

foreground hosts

Control host

Backup control host

Foreground host

Background host

Other configuration considerations

Heterogeneous configurations

Firewall configurations

Load distribution

Special notes for firewall installations

2

HAHTsite Application

Server (Windows NT)

Introduction

System requirements

What the installation program does

Important! Before You Start the Installation Procedure

Running the setup program

What’s next?

Verifying the installation

Removing the Application Server

3

configuration

(WinNT)

Introduction

About site configuration files

Using the Web Server Utility (Windows NT)

Starting the Web Server Utility

What the Web Server Utility detects

Adding hsrun to a Web server’s CGI scripts directory

4

HAHTsite Application

Server (UNIX)

Introduction

System requirements

What the installation program does

Important! Before you start the installation procedure

Running the setup program