HAHTsite Application Server Administration Guide

HAHTsite Application Server Administration Guide

Application Server Administration Guide release 4.0

Notice Copyright 1999 HAHT Software, Inc. All Rights Reserved March 1999 MN05-C-00-400-00 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 Rd, 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. All other tradenames are trademarks or registered trademarks of their respective companies. Specifications subject to change without notice. Portions Copyright 1992-1996 Summit Software Company. This product includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/). Inprise, Visibroker, and Visibroker for Java are trademarks or registered trademarks of Inprise Corporation. IBM and IBM-AIX are registered trademarks of International Business Machines Corporation. UNIX is a registered trademark exclusively licensed through X/Open Company, Ltd. Sun, Solaris, Java, and JavaScript are trademarks or registered trademarks of Sun Microsystems, Inc. Microsoft, Windows, Windows NT, Visual Basic, VBScript, Active X, and SQL Server are trademarks or registered trademarks of Microsoft Corporation. DG and DG/UX are U.S. registered trademarks of Data General Corporation. Any other product names, trademarks, tradenames, service marks, or service names owned or registered by any other company and mentioned herein are the property of their respective companies. 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)

Contents About This Book What s in This Book......................................... ix Other HAHTsite documentation............................... x Other HAHTsite products..................................... x Conventions............................................... xi HAHTsite Application Server installation directory............. xi Continuation characters in sample code..................... xi HAHT Software s commitment to you........................... xi 1 Introducing the HAHTsite Application Server What s in this chapter....................................... 2 Functional overview......................................... 3 HAHTsite Application Server architecture........................ 6 Performance.............................................6 Scalability..............................................6 High availability.........................................8 Manageability..........................................11 Deployment flexibility...................................12 Application Server editions................................13 Application Server configurations...........................14 Administrative overview..................................... 19 Application Server components............................19 Application Server group components.......................19 What is the Administrator utility?............................. 21 HAHTsite Application Server processes......................... 23 hsrun.................................................23 hsredir................................................24 hsrexec................................................24 hsserver...............................................24 iii

Contents hsadmsrv..............................................25 hscontrol and hsradmin..................................25 Session Objects and StateIDs................................. 26 How the Application Server is Licensed......................... 27 2 Administering the HAHTsite Application Server Getting started with the Administrator utility.................... 30 Starting the utility.......................................30 Logging in.............................................31 Selecting server groups and operations.......................32 Distributed server groups.................................... 36 Configuring the Application Server s SNMP interface...........39 Menu Bar buttons.......................................... 42 Exiting from the Administrator............................43 Administering hosts, server groups, and Administrator accounts..... 45 Maintaining host computers...............................46 Maintaining server groups................................50 User account authentication...............................53 3 Performing Administrative Tasks Directories................................................ 59 Directories and publish parameters.........................59 FTP parameters.........................................63 Runtime Options.......................................... 65 If you enter invalid parameters on the Runtime options form....73 Language options.......................................... 75 Logging options........................................... 77 Auditing options........................................... 81 Statistics................................................. 84 Current statistics........................................85 Cumulative statistics.....................................88 History................................................89 iv

Contents Sessions.................................................. 90 Services.................................................. 92 Application services tasks.................................92 Applications.............................................. 95 View log files.............................................. 96 Analyzing log files.......................................98 Access control............................................ 100 Admin rights............................................. 103 Changing the master administrator account.................104 Creating the HAHTsite password file....................... 105 Maintaining the HAHTsite password file.................... 106 HAHTsite username and password syntax................... 108 Setting an initial master administrator password (UNIX)....... 108 Changing authentication methods......................... 109 Assigning administrative rights............................109 License information....................................... 112 Upgrading the number of active session licenses................ 113 Configuring email information for warning messages............ 114 4 Other Administrative Procedures Introduction............................................. 118 Manually starting administration services...................... 119 Distributed Application Server configuration................... 120 hscontrol............................................. 120 hsredir............................................... 120 hsradmin............................................. 120 Starting HAHTsite Application Server Installations............121 Changing the Application Server s user/group ownership (UNIX) 122 Defining the Application Server s environment............... 122 Changing the UID/GID of the server group s configuration file.. 123 5 Tuning Tips Introduction............................................. 126 v

Contents Selecting a hardware configuration for the Application Server...... 127 Web server performance considerations..................... 127 Configuring Application Server processes and threads............ 129 Can you use multi-threading in the Application Server?........ 129 What controls the number of processes and threads?.......... 129 Guidelines for the process/thread configuration.............. 130 Analyzing performance problems............................ 132 High communication time............................... 133 High page queue time................................... 133 High page run time..................................... 133 A HAHTsite Application Server Error Messages Introduction............................................. 136 hsserver error messages..................................... 137 Customizing your hsserver error messages................... 137 Redirecting a user when an application times out............. 138 Returning a static page.................................. 138 Automatically redirecting the user......................... 138 Appending the log file entry to the hsserver error message...... 139 hsrun error messages...................................... 142 B Setting up NSAPI, ISAPI, and the Oracle Cartridge Introduction............................................. 146 Setting up NSAPI.......................................... 147 Windows NT.......................................... 147 UNIX................................................ 148 Setting up ISAPI for IIS 3.0.................................. 151 Setting up ISAPI for IIS 4.0.................................. 152 Setting up the Oracle Web Application Server................... 155 Configuring the Administrator as an NSAPI, ISAPI, or Oracle application. 156 vi

Contents C Creating Redistributable Applications Introduction............................................. 158 General procedure........................................ 159 Creating the redistributable application....................... 160 Delivering the application.................................. 162 Creating an installation script............................. 162 Advanced installation script notes......................... 164 About the.ini file......................................... 165 D Configuring the Application Server to Use DES Encryption What is DES?............................................. 168 Triple DES and the HAHTsite Application Server................. 169 vii

Contents viii

About This Book This book describes how the HAHTsite Application Server works and how it interacts with the other components of HAHTsite. The book also tells Web site administrators how to configure, administer, and tune a HAHTsite Application Server. Unless otherwise noted, the information in this book applies to UNIX and Windows NT 4.0. What s in This Book The following table summarizes the contents of this book: Chapter/Appendix Chapter 1, Introducing the HAHTsite Application Server Chapter 2, Administering the HAHTsite Application Server Chapter 3, Performing Administrative Tasks Chapter 4, Other Administrative Procedures Chapter 5, Tuning Tips Contents Introduces the HAHTsite Application Server and describes how it fits into the family of HAHTsite products. Describes how to use the Administrator utility to configure and administer the HAHTsite Application Server. Describes configuration and monitoring procedures that you can perform with the Administrator utility. Describes administrative procedures that are not part of the Administrator utility. You perform them from the operating system of the Application Server host. Describes the resources that the Application Server uses and the factors that you should consider in tuning your Application Server. ix

About This Book Chapter/Appendix Appendix A, HAHTsite Application Server Error Messages Appendix B, Setting up NSAPI, ISAPI, and the Oracle Cartridge Appendix C, Creating Redistributable Applications Contents Describes the error messages that the HAHTsite Application Server displays when an error occurs at runtime, and explains how these error messages can be customized. Describes how to configure NSAPI, ISAPI, and Oracle s Web Application Server for use with the HAHTsite Application Server. Describes how to create redistributable, or shrink wrapped, HAHTsite applications. Other HAHTsite documentation Other documentation shipped with the HAHTsite Application Server includes: HAHTsite Application Server Installation Guide Online help for the HAHTsite Application Server 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. x

About This Book 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 (for example, 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. If you installed the Application Server in c:\hahtsite, you would copy the files from c:\hahtsite\bin. 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: xi

About This Book 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 info@haht.com General Information sales@haht.com Sales support@haht.com Support World Wide Web www.haht.com xii

Introducing the HAHTsite Application Server 1 What s in this chapter...2 Functional overview...2 HAHTsite Application Server architecture...4 Performance...4 Scalability...5 High availability...7 Manageability...10 Deployment flexibility...10 Administrative overview...17 What is the Administrator utility?...19 HAHTsite Application Server processes...20 Session Objects and StateIDs...23 How the Application Server is Licensed...25 1

Chapter 1: Introducing the HAHTsite Application Server What s in this chapter This chapter gives a functional and administrative overview of the HAHTsite Application Server. The functional overview describes how the Application Server interacts with other HAHTsite components in different configurations. The administrative overview describes administrative features and the processes that make up the Application Server. 2

Functional overview Chapter 1: Introducing the HAHTsite Application Server The HAHTsite Application Server provides a high performance, highly scalable, and highly reliable mechanism for enabling browser-based access to a variety of enterprise data stored in relational databases, ERP systems, or other legacy systems. Using the HAHTsite IDE, Web developers create content and business logic, then deploy and manage the application. Together, the HAHTsite Application Server and HAHTsite IDE are a complete platform and development tool for Web enabling the enterprise. HAHTsite applications are developed with the HAHTsite IDE or a subset of the IDE, the IP. Web developers use the IDE or IP to design and build Web applications and publish them to a HAHTsite Application Server, where the applications are executed and made available to the Web browsers of the application s users. A HAHTsite server cluster consists of one or more host computers running TCP/IP, a Web server, and a HAHTsite Application Server. The Web server can be any standard Hypertext Transfer Protocol (HTTP) server capable of executing Common Gateway Interface (CGI) programs and providing static Hypertext Markup Language (HTML) pages to Web browsers. For example, the Web server may be one of those available from Netscape, Microsoft, O Reilly & Associates, or Apache. Applications developed with the IDE usually include dynamic as well as static pages. The Web server processes requests for static HTML pages, but sends requests for dynamic pages (requests containing program statements in HAHTtalk Basic or Java) to the Application Server. In this way, the Application Server works in conjunction with the Web server to make possible the advanced function and high performance of HAHTsite applications. The Web server and Application Server communicate via one of several versions of a program, hsrun. The IDE ensures that the URL for dynamic pages instructs the Web server to execute hsrun. Execution of hsrun links the Web server to the right Application Server process, sends the request to that process, gets back the results, and returns the results to the Web server, which then returns them to the requesting Web browser. A special feature of the Application Server is that it maintains the state of a HAHTsite application. At the time the Application Server receives an initial request from hsrun, a unique StateID identifying the user and application instance is generated. Subsequent pages pertaining to the same user and application instance are tagged with the StateID and matched with the same Application Server instance. (See Session Objects and StateIDs on page 23 for information on how StateIDs are generated.) 3

Chapter 1: Introducing the HAHTsite Application Server StateIDs facilitate the sharing of information among pages and make it easier to use a database. For example, a HAHTsite application user can logon to a database and move from one Web page to another without having to reconnect to the database. The Web server alone, by contrast, does not retain information about pages that it processes. This statelessness of standard Web applications makes the sharing of information among pages difficult and the use of a database inefficient. Application Server component interactions The following figure illustrates how the HAHTsite Application Server cooperates with a standard Web server at a HAHTsite location. The following is a summary of the HAHTsite application runtime interactions: A user s browser sends a request, in the form of a URL, to the Web server s HTTP layer. The HTTP layer passes the URL to the Web server program. If the request is for a static (HTML) page, the Web server program retrieves the page and sends it back to the HTTP layer, which forwards the page back to the user s browser. 4

Chapter 1: Introducing the HAHTsite Application Server If the request is for a dynamic page, the Web server passes the URL, which can include arguments, to the HAHTsite Application Server through the interface layer, hsrun. The Application Server reads the (optional) arguments that are passed with the URL, then executes the page s code to assemble the dynamic page on-the-fly. To assemble a page, the Application Server can access files on the server, files on the network, or tables in a database management system, or it can execute other programs. When the Application Server has assembled the dynamic page (in the form of HTML), it sends the assembled page to the HTTP layer. The HTTP layer sends the page back to the user s browser. 5

Chapter 1: Introducing the HAHTsite Application Server HAHTsite Application Server architecture As enterprise-class middleware, the HAHTsite Application Server is designed to meet enterprise-class requirements for: Performance Scalability High availability Manageability Deployment flexibility Performance The primary architectural goal of the HAHTsite Application Server is performance measured as its rate of delivering dynamically generated Web pages. Web applications are by nature intended to serve large numbers of concurrent users, so application servers must be fast and efficient in serving requests if they are to be deployable at the enterprise level. The HAHTsite Application Server supports applications written in HAHTtalk Basic or in Java. HAHTtalk Basic is fully syntax compatible with Visual Basic, but it is compiled, giving it a large speed advantage over comparable systems that interpret VBScript or JavaScript from source at runtime. For executing Java code, the HAHTsite Application Server works with standard Java Virtual Machines (VMs) from Microsoft and Sun, including associated Just-In-Time (JIT) compilers. The Application Server is designed for minimum interprocess communication. Requests from browsers go to a standard Web server, and then are routed directly to the proper Application Server process via standard Web server interfaces such as CGI, or for best performance, NSAPI, or ISAPI. Each Application Server process contains all of the facilities necessary to service the request, and does not require communicating with another process or another computer. Scalability The HAHTsite Application Server is designed for scalability into the tens of thousands of concurrent users. Scalability is achieved by replicating Application Server components across multiple processes and computers so that the replicated components can operate in parallel to serve more users. The 6

Chapter 1: Introducing the HAHTsite Application Server result is an Application Server Cluster with one or more computers cooperating to serve users. A cluster contains three types of logical hosts: Foreground hosts Background hosts Control hosts In smaller configurations, two or more of these types can be run on the same computer. Foreground host A foreground host runs each Web server in the cluster. Multiple Web server systems, each running the foreground software, may be used to increase the cluster's capacity to serve user requests and to provide redundancy in case of a system failure. The foreground software is lightweight. It works with the control host to perform load balancing, but otherwise simply redirects the user's request to the appropriate background host. Background host The background hosts do the actual work of servicing the user request. The background host contains the HAHTtalk Basic or Java VM that executes the application logic and that connects to backend data sources. As a result of executing the application logic, the background host generates HTML that is returned to the foreground and the Web server for delivery to the end user's browser. Multiple background hosts can be used in a cluster to increase performance and to provide redundancy in case of a system failure. Control host The control host is comprised of the Cluster Membership Manager and various administrative functions. The Cluster Membership Manager is responsible for knowing at any given point in time which computers are active in the cluster. When a computer leaves the cluster due to a failure or phased shutdown, or (re)joins the cluster as a new member, the Membership Manager coordinates the transition and informs other cluster members of the change. The control host's administrative functions include managing the licensed user count, keeping performance statistics, and running the Application Server Administrator application. A cluster contains a primary control host, and optionally, one or more backup control hosts to provide redundancy in case of a failure. Once a user session is created, new requests in that session can be handled by any Web server on any foreground host. Because there is no communication between replicated foregrounds or replicated backgrounds, adding a new 7

Chapter 1: Introducing the HAHTsite Application Server foreground or background host produces nearly linear scalability, even with a significant number of hosts. The HAHTsite Application Server allows extremely large numbers of users to be supported efficiently. Consequently you can easily add additional computers to handle additional load without having to redesign your application. The HAHTsite Application Server uses dynamic, weighted, load balancing to ensure that user sessions are evenly distributed across the background hosts. Dynamic means the load balancing module uses actual load information from each background host at the time the decision is made not just a preset algorithm. Weighted means that each background host can be assigned a performance factor that biases the load balancing algorithm so that background hosts of different hardware performance can be mixed in the same cluster. For example, a 4-way SMP computer can be assigned a performance factor of 40 while a 2-way computer is assigned a performance factor of 20. With this weighting configuration, the load balancing module will tend to assign twice as much load to the 4-way computer. High availability High availability systems are designed to minimize downtime by using redundancy to route around a failure. User operation may be disrupted briefly a few seconds to a minute or two but never for hours or days as could occur with an unenhanced system. The HAHTsite Application Server includes a number of features to ensure the availability of a HAHTsite cluster. They include: the ability to define multiple foreground, background and control hosts; eliminating single points of failure online reconfiguration of many settings without server group restart; providing the administrator with extra flexibility implementation of high availability features without degrading system performance The replication architecture of the HAHTsite Application Server allows each software component to run on multiple computers or hosts providing high availability in addition to performance and scalability. In a fully configured cluster, if a computer fails, other computers running the same component pick up the load. If a foreground host in the cluster fails, the frontend router can direct traffic to other foreground hosts, and operation continues unaffected. If a background host fails, other background hosts continue operating. Sessions on the failed host are lost and must be restarted, but are directed to one of the remaining good background hosts along with 8

Chapter 1: Introducing the HAHTsite Application Server any new sessions. If a control host fails, the cluster includes one or more backup control hosts that assume the administrative and management functions. All of the HAHTsite Application Server hosts can be replicated for highavailablity (HA): control host (backup and primary) background host foreground host The HAHTsite Application Server provides application isolation by configuring clusters with one or more independent server groups. A server group consists of one or more processes running on the background hosts and servicing user requests. Applications are deployed to a particular server group, and execute only in the processes that make up that server group. By deploying different applications to different server groups, isolation is ensured. If an application should fail and cause abnormal termination of a process, other applications running in other server groups are isolated from the failure. Server group processes are monitored. If a process should abnormally terminate due to an application error, the termination is detected and the process is automatically restarted (though any user sessions running in that process are lost). This high availability feature ensures that the server group keeps running without operator intervention in spite of an occasional application error. In summary, the HAHTsite Application Server takes a broad, system approach to high availability. Cluster configurations provide redundancy with no single point of failure. Failures are automatically routed around by reconfiguring the cluster. But the Application Server also explicitly addresses the broader issues of system maintenance and upgrades that can often have as much effect on availability as recovery from failures. The online management features, phased shutdown option, and parallel installation capabilities eliminate causes of downtime that occur if these issues aren't addressed. Overview of host failure processing Background host failure - If a background host fails, the active control host detects the failure typically within about 15 seconds and ensures that new work requests are not sent to the failed background. However, sessions active on the failed background are lost. When the background is restarted, the active control will recognize this fact, and ensure that new session requests are routed to the background. 9

Chapter 1: Introducing the HAHTsite Application Server Active control host failure - When the active control host fails, the failure is detected by the other hosts. A backup control will take over management of the cluster (if there are multiple backup controls defined, an arbitration mechanism determines which one will become active) and the foreground and background hosts will connect to the new active control. Foreground host failure - If a foreground host fails, the active control host will detect that fact, but take no additional action; when the foreground host is restarted, the active control will begin forwarding the host load information for so it can route new session requests correctly. 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. Primary vs backup control Note - For clarity, whichever control host is managing the cluster is designated as active in this section. There is one important difference in functionality between the backup and primary control hosts: when the backup control is active, you cannot change the cluster configuration. (For example, you can t add a server group or change parameters for existing server groups.) When running the HAHTsite Application Server Administrator while a backup control host is active, the administrator can review current server group settings, current session information, license information etc all the information that can be read while the primary control is active. In addition, existing server groups can be stopped or started. Since the backup control host needs to be able to run the HAHTsite Application Server administration utility, it must have a Web server installed. Like the primary control host, the backup control host can be installed on a machine hosting foreground or background functions. It is possible, although not very useful, to install a backup control on the same host as the primary control host (using a different install directory). Configuration changes made on the primary control hosts are propagated to backup control hosts via a mirror transfer. In essence, a copy of the configuration files (those in the conf directory) are sent to each backup control host that is running. This transfer is done both when a backup control host starts and initially connects with the active primary host, and whenever 10

Chapter 1: Introducing the HAHTsite Application Server the configuration (server group or license information) is changed. The mirror transfer protocol has some important implications: Make configuration changes when all backup controls are running, to ensure all backups have the latest configuration Once a backup control has a current mirror copy of the primary control host configuration, you can continue operations without the running the primary control host. For example, with all the machines in a cluster down, you can run an application by starting all the cluster s hosts except the primary control. (The backup control host takes over.) A backup control host cannot manage cluster operations until it has connected to the primary control host at least once (to get its initial mirror copy of the control host s configuration) On-the-fly configuration changes HAHTsite also allows the administrator to change many server group parameters without taking the server group down. The ability to do a soft server group shutdown on a node also provides considerable flexibility. The application itself can be re-published without restarting the server group. By replicating host functions, and using the online reconfiguration features, HAHTsite administrators should be able to provide continuous service even in the face of scheduled machine maintainance or unplanned host outages. Manageability The HAHTsite Application Server is easily managed for performance and availability in a corporate environment. Basic management functions are performed with the Application Server Administrator, which is itself a HAHTsite application that runs in a browser. Consequently, the Administrator runs on any platform that supports a browser, and it can run remotely from any location with browser access to the control host even over a modem line from home. One instance of the Administrator manages the Application Server across all computers that make up a cluster. Access to the Administrator is controlled by username and password, which may be kept in a HAHTsite specific access control list, or which may piggyback off the underlying operating system's username/password authentication. Authentication may be applied at the server group level so that different operators can manage only their own server groups. 11

Chapter 1: Introducing the HAHTsite Application Server Deployment flexibility The HAHTsite Application Server has the deployment flexibility to be used in enterprise environments with a variety of different computer systems and network configurations. Businesses often have standard choices for operating systems, Web servers, databases, development languages, and networks. Enterprise class middleware, such as application servers, should operate in the existing environment and not require the introduction of non-standard components. The HAHTsite Application Server can be deployed on Microsoft Windows NT for Intel, Sun Solaris for SPARC, Hewlett-Packard HP-UX, and IBM AIX. Different architectures can be used in any combination in a single heterogeneous cluster. For example, the foreground hosts can be on Sun Solaris while the background and control hosts are on Windows NT. In more exotic configurations, backgrounds can be of different architectures in the same cluster. The Application Server normalizes network traffic to a common byte-order so that differing architectures communicate with each other correctly. In smaller configurations, foreground, background, and control components can all be deployed on the same computer to minimize hardware requirements for development or test configurations. The Application Server can operate across a firewall for security in an application deployed over the Internet. The foreground, background, and control hosts can run on either side of the firewall as dictated by the application. With multiple foregrounds, one foreground can be deployed outside the firewall for Internet access and another foreground inside the firewall for Intranet access, allowing an application to be accessed by employees and non-employees without violating security guidelines. The Application Server connects with other parts of the Web application infrastructure using standard interfaces. It can be used with any Web server via the standard CGI interface. With Microsoft IIS or Netscape Enterprise Server, ISAPI or NSAPI interfaces can be used for higher performance. The Application Server supports the use of persistent connections by the Web server for higher performance as specified in the HTTP/1.1 standard. Changing the configuration of the Application Server does not require any changes to Web applications that it runs. The platform, replication, and configuration of foreground, background, and control hosts does not affect the application. At most, the application may need to redeployed using the HAHTsite IDE s one button publishing feature. Changes in the Web server and the usage of CGI, NSAPI, or ISAPI are also accommodated by simply republishing the application. 12

Chapter 1: Introducing the HAHTsite Application Server HAHTsite works with any browser. It requires no plug-ins or other software on the browser, and it does not require the complexity of a Java execution environment in the browser. It is at home with browsers running on Windows 3.1, Windows 95/98, Windows NT, Macintosh, or Unix workstations. Applications running in the Application Server can make use of features that are available in newer browsers, but the choice is entirely up to the application designer and is not dictated by HAHTsite. Consequently the HAHTsite Application Server is appropriate for applications accessed over the Internet where any possible browser may be used, and it is appropriate in a corporate intranet where a standard browser is used. The Application Server offers language flexibility. The bundled Virtual Machines execute HAHTtalk Basic or Java code, and Basic code can call into Java code. Java code executes using standard virtual machines from Microsoft or Sun (JDK 1.1.x or 2.x). You can make the choice on a per-server group basis so that one application might run with the Microsoft Java VM while another application executes with the Sun Java VM. HAHTtalk Basic or Java code can call out to code and API s written in other languages through native integration services supplied by the Application Server. Application Server editions There are two versions of the HAHTsite Application Server, one for the development environment only and one for production environments. The Developer Edition is provided with the HAHTsite IDE so that Web developers have a complete development and testing system for their HAHTsite applications, and is not licensed for use in a production environment. It runs as a desktop application on a Web developer s Windows 95 or Windows NT workstation, and is documented in the HAHTsite IDE and IP User s Guide. Note - 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. The information in the remainder of this manual applies only to the full HAHTsite Application Server. To execute HAHTsite applications in a production environment, a site needs the HAHTsite Application Server, which is sold separately from the IDE. The Application Server is available for Windows NT and UNIX (Solaris, HP-UX, and IBM AIX) platforms. On Windows NT, the Application Server runs as a service 13

Chapter 1: Introducing the HAHTsite Application Server with one or more multi-threaded processes. On UNIX, it runs as one or more multi-threaded daemon processes. The Application Server is a per-concurrent-user licensed product. The Application Server can be installed on the same computer as the Web server, or on several, separate host computers. Concurrent users are counted across all hosts in the cluster. Application Server configurations One of the most important responsibilities of a HAHTsite administrator is configuring the site to deliver the best performance for each application served to Web browsers. Administrators must be able to combine multiple systems to meet the scalability demands of applications. The distributed architecture of the HAHTsite Application Server lets administrators configure it to support even the most demanding performance requirements supporting a large number of concurrent users with good response times for dynamic page requests. The Application Server Administrator utility assists administrators in achieving high performance by allowing configuration of Application Server parameters such as the number of processes. In addition, the Application Server Administrator provides usage and performance statistics as the application is running. Performance is not the only issue for many sites. You may also be concerned with: Security - The ability to limit access to sensitive information, whether to an entire Web site, or to specific pages therein. High-availability - focused on making the service available to the user as much of the time as possible. In the event of a fault, the user may notice some interruption of service, but will always be able to reconnect to the service and use it again either immediately or within a sharply bounded period of time. The HAHTsite Application Server can be configured to meet any or all of these needs. Basic Application Server configurations The following figure shows an Application Server operating on a single host. In the figure, page requests from the user s Web browser are sent to the Web server. Requests for static pages are handled by the Web server and the static HTML page is returned to the user s Web browser. Requests for dynamic pages are forwarded to the HAHTsite Application Server, which processes the information passed with the URL, accesses any database or external resource 14

Chapter 1: Introducing the HAHTsite Application Server needed to create the dynamic page, and passes the page back to the Web server, which then forwards it back to the user s Web browser. Functionally, this configuration is identical to a multi-machine configuration. The next figure shows a standard Application Server configuration using two host computers, where the Web server is installed on only one of them, the foreground host, and the Application Server runs alone on a separate 15

Chapter 1: Introducing the HAHTsite Application Server background host. In this configuration, the Web server and Application Server communicate via TCP/IP across the network. Configurations with one foreground host can run the Web server on a public host computer and the Application Server inside an optional firewall (not shown). This is a good choice for small sites that serve both public and private applications, or applications with public and private elements. The figure on the following page shows a basic high availability configuration. In this model, there are multiple Web servers, fronted by a load-balancing router that makes them all appear as a single IP address. The Web servers are coupled to redundant background hosts running the HAHTsite Application Server. One of the background hosts doubles as the cluster s control host managing communications among the Application Server elements. The other background host acts as a backup control host and takes over if the primary control host fails. 16

Chapter 1: Introducing the HAHTsite Application Server This configuration gives a site administrator several levels of control over application performance and security. For example: The workload of executing HAHTsite applications is shared among a variable number of host computers. The host computers can be assigned different priorities, such that highcapacity computers (those with more or faster processors, more memory, or access to special hardware) receive a larger share of the workload. The foreground host computers can be located in a public area, while the background hosts can be located behind a security firewall. The intelligent router divides the incoming workload among the Web servers running on the foreground host computers. 17

Chapter 1: Introducing the HAHTsite Application Server Each Web server distributes its share of the workload among the Application Servers running on the background hosts, based on each computer s capacity. Each Application Server subdivides its share of the work among the optimal number of processes based on the capacity of the computer. The modular nature of a HAHTsite server allows you to easily configure your server hardware to meet your exact requirements. Modifying the basic server to achieve high security, high availability, or both, is simply a matter of how many hosts you configure, and their placement relative to your firewall. The previous example shows a simple high security (HS), high availability (HA) configuration. By providing redundant foreground, background, and control hosts (primary and backup) along with a router to direct traffic to and from the Web servers, you can reduce the possibility of a critical fault to near zero. Adding a firewall to the configuration, and placing the control hosts safely behind it turns this into a high security configuration. The following table shows what elements are required to create the specific type of server you need. Hardware Configuration Foreground Hosts Background Hosts Control Hosts Router Firewall Base 1 1 1 no no Base + HA >1 >1 >1 yes no Base + HS 1 1 1 no yes Base + HA + HS >1 >1 >1 yes yes 18

Administrative overview Chapter 1: Introducing the HAHTsite Application Server The tasks of Application Server administration include: starting and stopping the server configuring it to work smoothly with the Web server and with the operating system tuning it for performance monitoring and upgrading (if necessary) concurrent user license counts Application Server components The Application Server is not implemented as a single process, but as a group of independent, cooperating processes. This implementation makes the Application Server scalable and adjustable to particular site capacities and application characteristics. A server group consists of one or more processes running on the background host(s) and servicing user requests. Applications are deployed to a particular server group, and execute only in the processes that make up that server group. The server group is the primary unit of Application Server administration. A HAHTsite administrator accesses the cooperating processes that comprise an Application Server at the server group level as a single entity. Thus, to start, stop, or otherwise configure an Application Server, an administrator performs these actions on the server s group a one-step operation. Without server groups, starting and stopping an Application Server would require multiple steps, and performance tuning would be difficult and error-prone. Application Server group components The processes of an Application Server group are distributed among three types of host computers: Foreground Host - Runs the Web server and a subset of the Application Server (the Application Redirector) Background Host - Runs the main portion of the Application Server (the processes that execute dynamic pages) Control Host - Manages communications among the Application Servers (running on the background hosts) and Application Redirectors (running on the foreground hosts). A backup control Host, when configured, takes over all control host functions if the primary control host fails during processing. 19

Chapter 1: Introducing the HAHTsite Application Server The foreground, background, and control host (primary, backup) roles can be performed by separate computers, or these roles can overlap. Thus, an administrator at a site with four server computers might install a Web server and Application Server on each of the four, and install the control software on one of them. Here s how the process framework is normally established: The control host starts hscontrol as part of its boot sequence. Each foreground host, as part of its boot sequence, starts hsredir, which connects with hscontrol on the control host and gets the foreground host s configuration information. Each background host, as part of its boot sequence, starts hsradmin, which connects with hscontrol on the control host and gets the background host s configuration information. When a server group starts The hsradmin process running on each background host starts an hsrexec child process. The hsrexec process, in turn, starts the configured number of hsserver processes for the server group on that background host. Debugging processes start as needed, and run on the appropriate background host computer as children of hsrexec. When an IDE developer publishes an application to an Application Server group, dynamic pages are sent to each of the group s background hosts. 20

Chapter 1: Introducing the HAHTsite Application Server What is the Administrator utility? The Administrator is the tool you use to configure, administer, and monitor the HAHTsite Application Server. Functions performed from the Administrator utility include: setting runtime performance parameters setting up Publish destinations for IDE developers starting and stopping server groups monitoring runtime statistics of applications defining logging options monitoring and upgrading concurrent user license counts A site has one master administrator and, optionally, one or more group administrators. The master administrator can administer all groups. Conversely, a group administrator only has access to one or more server groups. The HAHTsite Administrator is username and password protected. Responsibilities of the master administrator include the setting up of server groups and server group administrators. The Administrator runs only on the control host. At startup, the control host starts hscontrol, which starts the child process hsadmsrv. All concurrent Administrator sessions run as separate StateIDs under this single hsadmsrv process. Management of a HAHTsite Application Server cluster can be conducted online while the cluster is serving users. Most operations in the Application Server Administrator tool take effect immediately without having to stop and restart the Application Server. For example, server groups can be stopped and started, timeout values can be changed, process and thread counts can be increased, log files can be managed, license keys can be installed, and performance statistics can be viewed without interrupting service to users. Cluster transitions can be initiated under operator control. For example, a background host can undergo a phased shutdown. User sessions already on the background host continue running and complete normally, but new user sessions are directed to other background hosts. When no sessions are running on the designated host, the shutdown occurs. Using phased shutdown, individual computers in a cluster can be temporarily removed from the cluster in order to perform hardware or software maintenance such as installing a service pack. After maintenance service is complete, the background host can re-join the cluster. The load balancing module realizes the new background host is present with no load, and so allocates new user sessions to this 21

Chapter 1: Introducing the HAHTsite Application Server background host until the cluster load is rebalanced. By cycling through each host in turn, maintenance can be performed on an entire cluster with no interruption of user service. A server group can also undergo phased shutdown. Existing user sessions are allowed to continue executing, but no new user sessions are accepted. This feature allows entire applications to be shutdown without abrupt termination of any users. Chapter 2, Administering the HAHTsite Application Server, explains how to use the Administrator to perform these procedures. 22

Chapter 1: Introducing the HAHTsite Application Server HAHTsite Application Server processes The following sections describe the roles of the processes that make up the HAHTsite Application Server. hsrun The hsrun executable comes in five forms: hsrun - a low-overhead Common Gateway Interface (CGI) program. Because CGI is a standard supported by all HTTP servers, this version of hsrun will work with any Web server. hsrunns.dll - a Netscape Server Application Program Interface (NSAPI) shared library program. This version works on both UNIX and Windows NT platforms with a Netscape version 2.x (or NSAPI-compliant) Web server. hsrunns30.dll - an NSAPI shared library program. This version works on both UNIX and Windows NT platforms with a Netscape version 3.x Web server. hsrunisa.dll - an Internet Server Application Program Interface (ISAPI) shared library program. This version works, on Windows NT platforms only, with Microsoft s Internet Information Server (IIS, versions 3.0 and 4.0) or with ISAPI-compliant Web servers. hsrunora.dll - an Oracle Cartridge version, for use with Oracle s Web server Because they integrate hsrun into the Web server process, the NSAPI, ISAPI and Oracle Cartridge versions offer improved performance compared to the CGI program, which the Web server executes as a separate child process. hsrun has these responsibilities: Parse incoming URLs to determine the kind of operation being requested. Acquire, for new instances of applications, new StateIDs and their server process assignments from the hsrexec program, or from the hsredir/hsrexec combination. Decode incoming StateIDs to determine which hsserver process is running an application. Report errors by sending error pages to the user s browser. 23

Chapter 1: Introducing the HAHTsite Application Server Decode and parse form fields and package them for use by an hsserver program. (The GET and HEAD methods pass form fields in the QUERY_STRING environment variable, whereas, the POST method passes them in the stdin stream.) Process the environment variables and package them for use by a hsserver program. These environment variables can provide additional information about the Web server, the user, the browser, etc. Connect to the assigned hsserver, send the packaged request packet to the hsserver, and wait for a reply packet. hsrun reads the reply and sends the reply through the Web server to the user s browser. Upload multi-part forms. hsredir hsredir receives and answers requests from hsrun for new StateIDs. Also, by using administrator-assigned priorities reflecting the capacities of the background hosts relative to one another, hsredir selects the background host to use. hsrexec hsrexec controls a server group s hsserver programs. hsexec has the following responsibilities: start the configured number of hsserver processes when the server group is started stop the hsserver processes when the server group is shut down restart the hsserver processes if they terminate due to an error receive from hsredir requests for new StateIDs, return the StateIDs (hsredir also selects the computer to use) assign new applications to a particular hsserver process listen for connection requests from client debug sessions start a copy of hsdebug to handle each client debug session hsserver The hsserver processes, which provide the runtime environment for HAHTsite applications, execute the HAHTtalk Basic or Java code that generates an application s dynamic pages. 24

Chapter 1: Introducing the HAHTsite Application Server hsserver runs as a single-threaded or multi-threaded process. (Sometimes the processes must be limited to one thread to accommodate ODBC or underlying database drivers that are not thread-safe.) In the course of executing HAHTtalk Basic or Java code, hsserver server processes do one or more of the following: manage the states that hsrexec assigns to it insert, update, or delete information in a file or database create or delete files or databases create, delete, and manipulate URL links in HTML files saved on the server send or receive mail interact with other programs on the server provide facilities, such as the application timeout, to manage applications in the unique environment of the Web provide extensible mechanisms for authors to create new widgets using HAHTtalk Basic or Java code hsadmsrv hsadmsrv is a special version of hsserver that includes additional code supporting the operations of the Administrator utility, which is a HAHTsite application. hscontrol and hsradmin hscontrol starts on the control host, usually when the control host boots. hscontrol provides the interprocess communication paths for cross-computer communications. The hsradmin process starts on each background host, usually when the computer boots connects with hscontrol on the control host, and acts as a router for configuration information and administration commands starts hsrexec on each of the group s background hosts when a server group is started 25

Chapter 1: Introducing the HAHTsite Application Server Session Objects and StateIDs An executing instance of a HAHTsite application is a session object. When the HAHTsite Application Server receives a request to execute a HAHTsite application for the first time, it allocates a new session object (on a peruser/per-application basis). The session object becomes the executing application s container. Each session object (a running HAHTsite application) is uniquely identified by a StateID. The string that represents the StateID is never reused the string is designed to be completely unique. The Application Server generates an application s StateID when it allocates the user session s session object. The Application Server knows that it is receiving a request to execute a HAHTsite application for the first time, when it processes a URL that has no segment for StateID, HAHTpage, HAHTmap, or HAHTfile. Here is an example showing how a StateID appears in a typical URL: After it generates a StateID for an application, the Application Server propagates the StateID in a browser cookie or as part of the URL, depending on the Web developer s specification when he or she publishes the project. If the StateID is passed as part of the URL, the Application Server adds the StateID to the URL of the first dynamic page generated by the application s starting entry point. From that point on, the Application Server propagates the StateID through the application s pages by including the StateID in relative URLs. If the Application Server s CGI-BIN program (hsrun) processes a URL and sees a segment for a HAHTpage, HAHTfile, or a HAHTmap, but does not find a StateID, hsrun checks for a cookie. The session object and its associated StateID persist for as long as the Application Server maintains an application session. The session exists until the application explicitly stops, an application time-out occurs, or the server is stopped. (The Web requires a time-out mechanism since users can abandon the session and move on without any notification.) When a time-out or a stop occurs, the StateID is purged. Resources such as memory are released for reuse by other session objects. 26

Chapter 1: Introducing the HAHTsite Application Server How the Application Server is Licensed The HAHTsite Application Server includes a mechanism that limits the number of concurrent users (StateIDs) that may access an application cluster. An Application Server cluster is a group of one or more machines that host the Application Server software and connect to a common control Host. When the licensed number of users is exceeded, the Application Server will return a customized error message. The number of concurrent user licenses is stored in a license key. License keys are obtained from HAHT Software, and are stored in the Application Server Administrator. The section titled Upgrading the number of active session licenses on page 113 contains information about upgrading license keys. 27

Chapter 1: Introducing the HAHTsite Application Server 28

Administering the HAHTsite Application Server 2 Getting started with the Administrator utility...30 Starting the utility...30 Logging in...31 Selecting server groups and operations...32 Distributed server groups...36 Configuring the Application Server s SNMP interface...39 Menu Bar buttons...42 Exiting from the Administrator...43 Administering hosts, server groups, and Administrator accounts...45 Maintaining host computers...46 Maintaining server groups...50 User account authentication...53 29

Chapter 2: Administering the HAHTsite Application Server Getting started with the Administrator utility The HAHTsite Administrator is the tool you use to administer the HAHTsite Application Server. It is implemented as a HAHTsite application. When you start the Administrator, the HAHTsite Application Server serves the application to your Web browser. Your browser may be running on the same computer as the Application Server, or on a remote system, and the Application Server you are administering may run on a Windows NT or UNIX platform. In all of these cases, the Administrator looks and works the same. Note - The Administrator requires a browser that supports frames. If you re running any version prior to Netscape 2.x or MSIE 3.x, you will need to upgrade. Starting the utility You can start the Administrator from your Web browser. It doesn t matter whether your browser is running on the machine (UNIX or Windows NT) where the Application Server is installed, or on a remote machine. All you need to know is the URL of the Administrator utility s login page. The default location of the login page in the Application Server s installation directory is: doctree/hsadmin<installationname>/hsadmin.html where <InstallationName> is the name you chose for your Application Server installation. So, to administer the Application Server for an installation named TEST, the URL for the login page would be: http://server_domain_name:port/hsadmintest/hsadmin.html where server_domain_name is the name by which the machine is known on the Web or intranet, and port is the port number of the port on which the http service is running. This value is optional if the port number is the default, 80. Otherwise, you must specify the port number. Tip - Save the URL of the login page as a bookmark. From any Windows NT computer on which the Application Server is installed, you can also start the Administrator from the HAHTsite program group: select Start > Programs > HAHTsite Server > HAHTsite App Server Administrator. (You 30

Chapter 2: Administering the HAHTsite Application Server must be working on the Control host computer to start the Administrator in this way.) If you have more than one Application Server installation on the machine, the Start menu will contain an Administrator option for each installation. The installation Name is noted in parentheses. Be sure to start the Administrator tool for the Application Server installation you wish to administer. Logging in When you start the Administrator, the Login form appears. The Login form prevents unauthorized use of the Administrator. Enter the requested login information, and click Login. Notes: The Domain text box does not appear if the Application Server you are administering runs on a UNIX platform. On NT the field appears even if your site is not using domains. If it is not relevant, leave it empty. The Administrator may use the same login account file as the operating system, or it may store valid Administrator accounts in a separate file. If you have an operating system account, check with the master HAHTsite administrator to find out whether to enter the same login information for the Administrator as for the operating system. If you are the master administrator, initially login using the account specified during installation of the Application Server. Then see User account authentication on page 53 for a discussion of your options for controlling Administrator access. 31

Chapter 2: Administering the HAHTsite Application Server Selecting server groups and operations You launch most administrative operations from the Administrator utility s main page. The main page differs slightly, depending on whether you are the master administrator or a group administrator. The figure below shows the Administrator main page for a group administrator who has administrative responsibility for the default server group, AppServer4033. Server Groups Toolbar Server Groups Area Display Area Menu Bar The main page is divided into four sections: a server groups area, server groups toolbar, menu bar, and a display area. The server groups area lists all server groups to which an administrator has access. 32

Chapter 2: Administering the HAHTsite Application Server There are three columns of information: The left column (no heading) contains a box indicating the currently selected server group: bright yellow means selected. One, and only one, group will always be selected. To select a different group, you can either click this box, or the server group name, in the appropriate row. The NAME column contains the names of server groups. Group administrators see the groups to which either the master administrator, or another group administrator, has given them access. The STATUS column uses three colored bars to indicate a server group s status, as follows: Status indicator Meaning Use Green (left) running Click this status indicator to start the associated group, or to cancel a phased shutdown that is currently in progress. Yellow (center) phased shutdown in progress none Red (right) stopped Click this status indicator to stop the associated group. The Menu Bar contains buttons you click either to end the current administrative session, or to perform an operation on the currently selected 33

Chapter 2: Administering the HAHTsite Application Server server group. The administrative actions on the Menu Bar apply to the currently selected server group. Until you select an operation, the display area is blank. When you click a button on the Menu Bar, either a message or form appears in the display area. The Refresh View button updates the list of servers and their status. For example, if, after starting the Administrator utility, the administrator of group webapps were assigned administrative responsibility for another server group named OrderEntryApp, clicking Refresh View would update the list of server groups. To shutdown a server group 1 In the server groups area, click on the red (right) status bar for the server group you want to stop. If the server group is not in use (has no active sessions) the Red indicator lights to indicate that the server group has been shutdown. (You are done with this procedure.) If the server group is in use (has active sessions), you will see the following screen: 2 Select a radio button to specify how the shutdown will proceed. 34

Chapter 2: Administering the HAHTsite Application Server Radio button Stop the Server Group immediately, terminating all active user sessions. Allow active user sessions to remain active up to... Description Select this radio button to terminating all active user sessions and stop the server group immediately. Select this radio button to provide current users with a grace period, (in seconds) after which the shutdown will occur. 3 Click YES. If you chose the second option above, the yellow status bar lights while sessions remain active on the server group. This status bar darkens and the red status bar lights when either the last active session ends or the grace period passes. 35

Chapter 2: Administering the HAHTsite Application Server Distributed server groups The figure below shows the Administrator s server groups area with two distributed server groups, AppServer4033 and AppServer4033b. With many server group configurations, the work of executing an application is distributed among two or more host computers. Clicking on the + icon in the second column of the server groups area reveals a list of those hosts that participate in the serving of that group s applications. All site hosts (defined by the master administrator) are listed. To include a host in the processing of the currently selected group, click the check box to the right of the host s name. When you include a host, the group host list changes as indicated below. 36

Chapter 2: Administering the HAHTsite Application Server The Status column on the right indicates whether group software is started (green box) or stopped (red box) on a host. Click the host s row in the Status column to start or stop the group software on an included host. To start and stop the group software on all hosts currently included in a distributed server group, you have two choices: From the distributed server group view, you can click in the Status column. Clicking a green rectangle starts the distributed group, while clicking a red rectangle stops it. 37

Chapter 2: Administering the HAHTsite Application Server From the distributed server group/host view, you can click the Start All and Stop All buttons. The box on the left of group and host names indicates the current selection. In the figure above, the distributed group (AppServer4033) is selected: its box is yellow. If you click the box to the left of the host name, its box turns yellow, indicating that host is the current selection. At any given time, one and only one item (server group or host) is selected, and buttons on the Menu Bar apply to the current selection. For example, if you click Runtime on the Menu Bar with the group webapps selected, the action sets a default for all included hosts of the group. If you click Runtime with the host selected, the action overrides the group default on that host. The group default is overridden for an item only if you enter data for the item. Suppose you do the following with the AppServer4033 server group illustrated above: 1 Select distributed server group AppServer4033 2 Click Runtime 3 Enter 10 as the number of processes 4 Select a AppServer4033 host 5 Click Runtime 6 Enter 20 as the number of processes 7 Start the AppServer4033 group 38

Chapter 2: Administering the HAHTsite Application Server Twenty hsserver processes for AppServer4033 will be started on your selected host while 10 hsserver processes will be started on host4033. But if you omit steps 4 through 6, 10 hsserver processes will be started on both server group hosts. Configuring the Application Server s SNMP interface The HAHTsite Application Server can be configured to interface with SNMP (Simple Network Management Protocol). SNMP is a widely-used network monitoring and control protocol that lets you remotely manage a computer network by polling and setting values and monitoring network events. To achieve this, SNMP allows for the following operations: Get Set Trap SNMP is composed of the following 3 elements: 1 The Management Information Base (MIB) is the hierarchical data definition for the managed objects and how they are accessed. 2 The Agent runs on each Managed Node implementing the MIB. 3 The Manager is software that runs on the Network Management Station used to control and observe the managed nodes. The HAHTsite MIB defines the SNMP implementation for Enterprise ID 3335 (HAHT Software). The HAHTSite SNMP Agent generates traps only. Each HAHTSite Process (eg., hsserver, hscontrol) is capable of generating traps. Traps are generated for each severe error that is logged to the HAHTsite error log. 39

Chapter 2: Administering the HAHTsite Application Server To enable SNMP trap generation for your HAHTsite Application Server 1 Click DISTRIBUTED ENVIRONMENT in the server groups area of the HAHTsite Application Server Administrator. The Cluster form appears. 2 Configure SNMP settings using the fields under the SNMP Options heading on the Cluster form. The fields are described below. Field Enable SNMP Trap Generation for Severe Errors SNMP Community Name IP Addresses of SNMP Trap Destinations Visigenic VisiBroker for Java Options Description Check this box to instruct the Application Server to generate the SNMP traps when severe errors occur. Enter the name of the SNMP community configured for SNMP at your site. Enter one or more IP addresses for systems running SNMP monitors to receive the traps. reserved for future implementation 40

Chapter 2: Administering the HAHTsite Application Server Note - These settings affect all Application Server processes on all of the Control Hosts, Foreground Hosts, and Background Hosts participating in the Application Server cluster. 3 Click SAVE CHANGES to implement your SNMP settings. 41

Chapter 2: Administering the HAHTsite Application Server Menu Bar buttons The following table lists the names of the Menu Bar buttons, describes the button s purpose, and notes where the procedure is explained in the chapter. Click this button... Directories Runtime Language Options Auditing Options Logging Options Access Control Log Files Admin Rights Statistics Sessions Services Applications To... set up the interface between the Application Server and the IDE. (See Directories on page 59.) configure server groups. (See Runtime Options on page 65.) set Java- and HAHTtalk Basic-specific Application Server parameters. (See Language options on page 75.) select the kinds of information that you want to audit for a server group. (See Auditing options on page 81.) set up the level of detail to capture about server groups. (See Logging options on page 77.) configure options that control how the Application Server enforces access control. (See Access control on page 100.) view log files for server groups. (See View log files on page 96.) specify additional administrators for server groups. (See Admin rights on page 103.) view information about currently active server groups. (See Statistics on page 84.) view detailed information about all of the currently active sessions, or terminate selected sessions. (See Sessions on page 90.) define, start, or stop application services, that is application components that provide services via CORBA to other HAHTsite applications or CORBA clients. (See Services on page 92.) view summary information about the applications that are currently active. (See Applications on page 95.) 42

Chapter 2: Administering the HAHTsite Application Server Click this button... License Info Help Exit To... view License Information form, which allows you to monitor license statistics, update the number of concurrent user licenses, and configure the Application Server to send warning messages about license counts. (See License information on page 112.) read context-sensitive Administrator documentation extracted from this manual end a session with the Administrator. (See Exiting from the Administrator on page 43.) Exiting from the Administrator Stopping your browser does not stop the Administrator. To end an Administrator session, click Exit. We recommend that you exit from the Administrator as soon as you ve concluded the intended work for a session. You can easily start another session, as explained at the beginning of this chapter. If you leave your workstation without exiting from the Administrator, an unauthorized person might gain access to the Administrator. This is true even though you may have left your browser at another location. By using the browser s Back button, an intruder might return to an Administrator page and resume your session. If you stop your browser without first clicking Exit, your session will remain active for five minutes, then will time out. In this case, there is no way to return to a session that hasn t yet timed out. If you start a new session before the timeout period has lapsed, the abandoned session will still be running. The next section gives details and notes possible unintended consequences of stopping your browser without exiting from the Administrator. Concurrent administration and timeouts Multiple administrators can use the Administrator utility simultaneously. If an administrator of a server group has open a form that includes a Save Changes button, other administrators of the same group cannot access the form until the first administrator clicks Save Changes or Cancel, or changes operations. This locking prevents conflicts in updates. Separate locks are used for each server group administrators of different server groups do not block each other. 43

Chapter 2: Administering the HAHTsite Application Server If the Administrator utility remains idle for five minutes, it times out. The timeout prevents a user from locking out other users for too long. If the utility times out, you will see messages like the one shown below when you try to perform an operation. To resume administration activities after getting such messages, restart the Administrator. 44

Chapter 2: Administering the HAHTsite Application Server Administering hosts, server groups, and Administrator accounts This section describes procedures that can only be performed by the master administrator. At initial installation, perform these procedures: Determine who the group administrators are and what they see when they start the Administrator utility. After initial installation, perform the procedures on an as-needed basis. When you log in as the master administrator for the first time, the Administrator main page will look like this: 45

Chapter 2: Administering the HAHTsite Application Server Maintaining host computers Select the host computer maintenance functions by clicking Host Computers on the server group toolbar. You can now view a list of all foreground and background hosts participating in this installation. The Create, Copy, and Delete buttons on the server group toolbar, and the buttons on the Menu Bar, refer to host computers. (When server groups is selected, these same buttons refer to server groups.) Click on a host computer s name, or click OPTIONS to display the Host Computer Configuration form. Field This host will run a Web server and hsrun Description This checkbox is selected if this host is a foreground machine. (read-only) 46

Chapter 2: Administering the HAHTsite Application Server Field This host will run application servers Operating System Type Relative performance of server host (0 for roundrobin allocation) Public DNS address Host is private (behind firewall) Private IP address Description This checkbox is selected if this host is a background machine. (read-only) Note that a host may have both foreground and background software installed on it, and may serve both roles. This checkbox indicates whether this host runs Windows NT or one of the supported UNIX operating systems (read-only). For round-robin scheduling (all host computers are of equivalent capacity and should share the workload equally), accept the default (0) for each host computer. If the host computers are of unequal capacity, enter for each an integer that expresses its capacity relative to that of the others. Displays this host s IP address, in dot-format, or a DNS name associated with the host s IP address. This checkbox is selected if this host is located behind a security firewall. Displays this host s private IP address, if the machine is located behind a firewall. Click Save Changes to save any changes made to the configuration information. The Options Confirmation page appears in the Display Area. Removing a Host To remove a host, first you must stop all server groups that use it. (See Selecting server groups and operations on page 32.) You ll get an error message if you attempt to delete a host that is being used by an active server group. 47

Chapter 2: Administering the HAHTsite Application Server Once you ve stopped all server groups that use the host computer, select the host, and click Delete. A confirmation message appears. Click DELETE to confirm. Doing so removes the host from server groups that were using it, and makes the host unavailable to any subsequently created server groups. To abort the deletion, click RETURN. Viewing or changing the control host s configuration A Control host s configuration (primary or backup) is set during installation of the Application Server. To inspect or configure a control host, click Control Host, then Options. 48

Chapter 2: Administering the HAHTsite Application Server Field Public DNS address Public IP port (outside or no firewall) Host is private (behind firewall) Private DNS address (required if host is private) Private IP port (inside firewall) Encrypt control packets between hosts Host is Primary control host Description Displays the DNS name associated with the host s IP address if this host is not behind a firewall Displays the IP port number if this host is not behind a firewall This checkbox is selected if this host is located behind a security firewall. Displays the DNS name associated with the host s IP address if this host is behind a firewall Displays the IP port number if this host is behind a firewall Check this box to use encryption to safeguard messages sent between hosts. This checkbox is selected if this host is the primary control host. 49

Chapter 2: Administering the HAHTsite Application Server If you change any control host information, reboot the control host, and then each foreground and background host. Changes do not take effect until you do this. If you change the control host s Public DNS address or port number, it may be necessary to reinstall the Application Server on all other host machines. Assigning host computer relative performance During execution of a HAHTsite application, the Application Server applies a scheduling algorithm, whereby host computers with greater available capacity receive a larger share of the workload. You should gain an understanding of each host computer s available computing capacity, and assign the host an integer that expresses its computing power compared to that of the others. Consider the following factors when assigning relative performance. Include a host computer s number of processors processor architecture, including but not limited to clock speed memory utilization for tasks other than serving HAHTsite applications to Web browsers If you want the host computers to share the workload equally, assign the same number to each. Note that this is the default. If you want a given host computer to receive a larger share of the workload, assign it a larger number relative to the others. Maintaining server groups IDE programmers publish their applications (projects) to sites. In turn, a site points to a server group. Creating server groups required by the Application Server site is the primary responsibility of the master administrator. This section describes how to create, copy, and delete server groups. These are functions that only you, the master administrator, can perform. Site definitions are explained in the HAHTsite IDE and IP User s Guide. Server groups that you create here can be selected by IDE users when they define sites. Once created, server groups may be configured either by you (the master administrator), or by group administrators whom you designate. While the master administrator has full administrative access to all server groups at a site, group administrators see only the group(s) to which they have been given access. Group administrators with write access can perform all administrative 50

Chapter 2: Administering the HAHTsite Application Server functions, including granting group administrative privileges to others. Group administrators with read access can monitor groups to which they have been given access but cannot change information or grant access to others. After creating server groups, if you want to delegate administrative responsibility for any groups, see User account authentication on page 53 for a discussion of how Administrator utility accounts are defined. Then, use the Administrative Rights form as explained in Admin rights on page 103. Creating a server group With the SERVER GROUPS button selected on the server groups toolbar, all server groups area buttons (CREATE, COPY, DELETE) refer to server groups. (When HOST COMPUTERS is selected, these same buttons refer to host computers.) 1 Click CREATE. The Create Server Group Form appears. 2 In the Server Group Name field, enter a name for the group. When you click CREATE, a confirmation screen appears. 3 Use any of the Menu Bar buttons to configure the new group, or click RETURN to see an updated list of server groups. 51

Chapter 2: Administering the HAHTsite Application Server Note - Server group creation is not complete until the group is configured: you, or a group administrator, may have this responsibility. To configure a group, use the Directories, Runtime, and Logging Options forms. These procedures are explained in Chapter 3, Performing Administrative Tasks. Using Copy and Delete If a server group you want to create is similar to an existing server group, you can save time by using Copy, which duplicates the configuration of the original. Then you (or an assigned group administrator) can modify the new group s configuration as needed. Copying a server group To duplicate a server group, select it from the Server Group List and click Copy. Then enter a new server group name and click Copy. (See Creating a server group on page 51.) Deleting a server group 1 To remove a server group, select and stop the group. 2 Click Delete. A delete confirmation message appears. 3 Click Delete to confirm. Note - If the server group is active, you will be notified. In this case, you probably should not confirm the deletion without warning its users. If you do, the users will receive no advance notice, and any database transactions in progress will be rolled back. Deleting a server group stops it (if necessary) and removes its name from the list of server groups. 52

Chapter 2: Administering the HAHTsite Application Server User account authentication The HAHTsite Application Server supports two mechanisms for verifying logins to the Administrator utility and for starting debugging sessions on the Application Server host: Operating-system authentication - Login information entered on the Administrator login form (see Logging in on page 31), and by IDE programmers when starting debugging sessions, is verified against the operating system account file. HAHTsite authentication - Login information is verified against a separate password file in the HAHTsite installation directory, HAHTsiteInstallDir/conf/hspasswd. If this file is not present on the Application Server host, the operating-system method is used. Except for the special case of the master administrator account, access to server groups is controlled by the Admin Rights form (see Admin rights on page 103) rather than by the login file. When you, or a group administrator, use the Access Rights form to give an administrator access to a server group, you enter a username. The authentication method in effect at the time determines whether this name refers to an entry in the operating-system or the HAHTsite password file. For example, if you choose operating-system authentication, users with accounts in the operating-system account file will be able to start the Administrator. However, unless you have given them access to one or more server groups, they will be unable to perform any administrative procedures. Deciding which method to use: pros and cons If most group administrators and site developers already have login accounts on the Application Server host, operating-system authentication is simpler. To delegate server group administration or debugging privileges, all you have to do is enter the person s username on the Access Rights form. The user will already know how to log in. By contrast, choosing HAHTsite authentication in this case requires you to create and maintain the HAHTsite password file, including assigning usernames and passwords and providing this information to the users. However, where most administrators and developers do not already have operating system accounts, this advantage in simplicity is nullified. With HAHTsite authentication, there is no requirement that a group administrator or IDE programmer have login access to the operating system: administrative procedures (except for those described in Chapter 4, Other Administrative Procedures ) may be performed remotely from the user s browser. Adding HAHTsite administrators or IDE programmers to the 53

Chapter 2: Administering the HAHTsite Application Server operating system password file potentially gives them access to the operating system. Conversely, operating-system privileges do not give a user any HAHTsite access privileges, which are controlled by the Access Rights form of the Administrator utility. Thus, maintaining a HAHTsite password file may be simpler than modifying the operating-system file, while having fewer security consequences. HAHTsite authentication provides basic, no-frills security. Operating-system authentication has the potential of providing more sophisticated security (e.g., password aging), but whether or not this is possible depends on local circumstances. Also, if the operating-system imposes a security feature such as account expiration, selecting this method entails an added maintenance burden compared to the HAHTsite method: when a group administrator s username expires, you ll have to grant access rights under the new username. Note - In both methods, login information is encrypted before being transmitted. You can use either operating-system or HAHTsite authentication, but the mechanism you choose applies to all Administrator utility and debugging sessions at your site. You cannot use the two methods concurrently. You can also switch between methods: see Changing authentication methods on page 109. Other advantages and disadvantages, discussed in the following two sections, differ somewhat depending on whether the Application Server is installed on a Windows NT or UNIX computer. Read the section that applies. Also, note that the phrase installer of the Application Server indicates the installer of the Application Server on the Control host. the host computers that participate in the serving of HAHTsite applications may be a mixture of Windows NT and UNIX computers. If this is the case at your site, read the section that applies to the operating system of the Control host. Windows NT authentication The installer of the Application Server specifies the username that you (the master administrator) must use when starting the Administrator for the first time. The name entered by the installer must be that of an existing Windows NT user account. In order to start the Administrator utility initially, you must 54

Chapter 2: Administering the HAHTsite Application Server know that name, its corresponding password, and (if your site uses domains) the domain name. Operating-system authentication is the default. After the initial login, you can switch to HAHTsite authentication. You can also change the username of the master administrator that was specified by the installer, whether or not you switch to HAHTsite authentication. If you decide to switch to HAHTsite authentication, you ll have to create and maintain a password file. (See Admin rights on page 103.) UNIX authentication The installer of the Application Server specifies the username that you, the master administrator, must use when starting the Administrator for the first time. Whether the Administrator utility searches the operating system password file or the HAHTsite password file for this name may depend on how the installer logged in prior to starting installation. If the installer logged in as root (or used su to switch to root prior to starting installation), the setup dialog includes this prompt: Do you wish to use native operating-system authentication (return=no)? The installer may reject the default (HAHTsite authentication) in favor of operating-system authentication. In this case, the name previously specified by the installer as the master administrator must be a valid UNIX login account. In order to start the Administrator utility initially, you must know that name and its corresponding password. If the installer did not login as root, the default method (HAHTsite authentication) is specified: there is no opportunity, at time of installation, to select operating-system authentication in this case. With the default (HAHTsite authentication), you start the Administrator utility initially by entering the username specified by the installer and a null password. Then, assuming you want to use the HAHTsite method, you assign a password to the master administrator account. (See Setting an initial master administrator password (UNIX) on page 108.) With operating-system authentication, the processes that support the Administrator utility must run with root access. With HAHTsite authentication, this is not a requirement. (In UNIX parlance, the Administrator processes need to run as setuid root or with root privileges, so that it can access the shadow password file.) You can switch to operating-system authentication. (See Changing authentication methods on page 109.) 55

Chapter 2: Administering the HAHTsite Application Server 56

Performing Administrative Tasks 3 Introduction...58 Directories...59 Runtime Options...65 Language options...75 Logging options...77 Auditing options...81 Statistics...84 Sessions...90 Services...92 Applications...95 View log files...96 Access control... 100 Admin rights...103 License information...112 Upgrading the number of active session licenses... 114 Configuring email information for warning messages... 115 57

Chapter 3: Performing Administrative Tasks Introduction This section describes configuration and monitoring procedures that you can perform with the Administrator utility. To perform server group tasks, you need to know how to select, start, and stop server groups (and server group hosts if you re administering a distributed Application Server configuration). (See Chapter 2, Administering the HAHTsite Application Server for an explanation of these basic Administrator utility procedures.) 58

Directories Chapter 3: Performing Administrative Tasks Use the Directories form to define application publish destinations and transfer parameters. When an IDE programmer publishes a project to a site, application components are transferred from the developer s workstation to the server group specified in the site definition file. Both the physical location of application software on the Application Server host(s) and the method of transferring the software to the destination are defined using the Directories form. If you re administering a distributed server group, note: If you click Directories with a group selected, the information you enter sets the defaults for each group host. If you click Directories with a server group and a host selected, the information you enter modifies the server group default for that host. If you click Directories with a host selected and see a blank form, this tells you that the group defaults are in effect for that host. Directories and publish parameters The publish operation transfers the components of your application to directories on the Application Server host(s). Use the Directories form to 59

Chapter 3: Performing Administrative Tasks monitor or change these locations. (If you have only read access to a server group, you can only monitor the parameters.) The four Directory paths are physical directories on the server host(s): files are transferred to the first three paths whenever an IDE user publishes to a site. In specifying the default directories for a server group, you can use the %INSTALLDIR% variable to designate the fully-qualified path where the Application Server software was installed on a host. By default, the application root, working, and application java class directories are subdirectories of the installation directory. For example, if an IDE developer publishes a project named OrderEntryApp, software may be copied to these locations on the Application Server host(s): %INSTALLDIR%/approot/OrderEntryApp %INSTALLDIR%/userroot/OrderEntryApp %INSTALLDIR%/javaroot/OrderEntryApp In specifying directory paths, you can use either forward slashes (/) or backward slashes (\). The Administrator will translate as needed to accommodate the underlying UNIX or Windows NT operating system. However, in URL paths, only forward slashes are allowed. 60

Chapter 3: Performing Administrative Tasks When specifying URL paths, you can use the %HOSTIPADDR% variable to refer to a host s public IP address. This variable is especially useful with the distributed server. For example, with a distributed group selected, if you specify this URL for the application root: ftp://%hostipaddr%/approot this URL may be construed to resolve to subdirectory approot of each distributed host s FTP directory. Thus, if a distributed group has two hosts, haht1 and haht2, whose FTP directories are configured as www.haht1.com and www.haht2.com, then the default URL for the group shown above resolves on these hosts to: ftp://www.haht1.com/approot ftp://www.haht2.com/approot The variable %HOSTIPADDR% resolves to the value entered in the Public IP Address field when each host was installed. The three available transfer methods are: file copy: begin the path with \\ file transfer protocol (FTP): begin the URL path with ftp:// hypertext transfer protocol (HTTP): begin the URL path with http:// The method you specify on the Directories form must be set up and supported by the Application Server host s Windows NT or UNIX operating system. These methods are independent of Application Server software, but must be coordinated with the directories where the Application Server and your Web server software reside. 61

Chapter 3: Performing Administrative Tasks Note - You can make changes to the Directories form while the server group is running. Changes to the directories require a restart to take effect. Changes to the Path/URL to Publish here fields will take effect immediately, without restarting the server. If you change the directories of an existing application, the application will fail unless either the developer republishes the application, or you manually copy the application files to the new location. Field Name Application Root Directory Path/URL to Publish here Initial Working Directory Path/URL to Publish here Description Enter the name of the directory to which the dynamic pages of an application published to this server group will be copied; and enter a corresponding path/url that, when joined with other URL components, will give a Web browser access to the application root directory. Note that the path/url can be an absolute path, UNC path name (Universal Naming Convention), or URL. Changes to the directory field require Server Group restart to take effect. Changes to the Path/URL to Publish here field take effect immediately. Server restart is not required. Enter the name of the directory to which any application-specific files or data will be copied when the application is published; and enter a corresponding path/url to the directory. Note that the path/url can be an absolute path, UNC path name, or URL. The working directory is a convenience mechanism that allows application components to save configuration or interim data such that other components can access the data with a simple filename in lieu of a fully-qualified pathname. Changes to the directory field require Server Group restart to take effect. Changes to the Path/URL to Publish here field take effect immediately. Server restart is not required. 62

Chapter 3: Performing Administrative Tasks Field Name Application Java Class Directory Path/URL to Publish here System Java Class Path Description Enter the name of the directory to which any application-specific, server-side Java class files will be copied when the application is published; and enter a corresponding path/url to the class directory. Note that the path/url can be an absolute path, UNC path name, or URL. For HAHTsite applications that use Java, this directory may contain class implementation files needed by the Java application code. Changes to the directory field require Server Group restart to take effect. Changes to the Path/URL to Publish here field take effect immediately. Server restart is not required. Enter the pathname where the Java system classes are installed on each server host. It is presumed that the server classes used by the Java application are compatible with these system classes used by the Java Virtual Machine on the server host(s). You must restart the server for changes to this directory field to take effect. FTP parameters One of the transfer methods available to IDE programmers is FTP. When a publish action is initiated, publish uses FTP to transfer the application to the server host(s). FTP requires the entry of a username and password. The FTP parameters fields allow you to enter default login parameters for the server group. If you enter none, IDE programmers, when publishing to a site that specifies the group, will have to enter an FTP username and password. Field Name Username Description Enter the FTP username for the server group. 63

Chapter 3: Performing Administrative Tasks Field Name Password Retries Description Enter the FTP password for the server group. Enter the number of attempts to try to connect before giving up. Note - Changes to FTP publish parameters take effect immediately, without a server group restart. 64

Runtime Options Chapter 3: Performing Administrative Tasks Use the Runtime options form to tune a server group for performance, or to inspect its configuration. (If you have read access to a group, you can only inspect its configuration.) 65

Chapter 3: Performing Administrative Tasks You can select Runtime options with a host, rather than its group, selected. If you select Runtime options with a host selected and see a blank form, this means the group defaults are in effect for that host. Changes to Runtime options take effect immediately while the server group is running, except where noted in the table below. 66

Chapter 3: Performing Administrative Tasks Each parameter is described in the following table. (For additional information on tuning the Application Server, see Chapter 5, Tuning Tips. ) Field Name Number of Processes Run a separate server thread for each application session Number of Threads (if not separate thread per session) Maximum Debugging Processes Allow Anonymous Debugging Sessions Description Specifies the number of hsserver processes that the Application Server host(s) initiates to run the server group s applications. The default is one process per host; the maximum is 512. Decreasing this parameter requires restart. May be increased without restart. Check this box to run a separate server thread for each application session. Requires threadsafe application. Specifies the number of threads per hsserver process that the Application Server provides to service the server group s applications. The default is one thread per process; there is no maximum. This field is ignored when Run a separate server thread for each application session is checked. Decreasing this parameter requires restart. May be increased without restart. Note - Some software, such as the Microsoft ODBC drivers that use the Jet engine, are not currently thread safe and will not run properly if a process has more than one thread. This includes the Microsoft ODBC drivers for Access, dbase, FoxPro, Paradox, Excel, and text. The INTERSOLV drivers are thread safe. If you are using any driver, DLL, or API that is not thread safe, you should configure only one thread per process. Specifies the maximum number of remote debugging processes that can be active at one time. If this parameter is set to 0, debugging is not allowed. The maximum value for this parameter is 50. The default is 1. Decreasing this parameter will not terminate existing debugging sessions. By default, an IDE user must login with a valid username and password to begin a debugging session. Select this check box to allow anonymous debugging sessions. If this option is selected, any IDE user that can browse a HAHTsite project from the Application Server site can also run a debugging session. (Not available at Host-Specific level.) 67

Chapter 3: Performing Administrative Tasks Field Name Time to wait before restarting failed Application Server (in seconds) Total time to retry failed restarts of an Application Server (in seconds) Preload Applications Description The Application Server executive process (hsrexec) has the ability to automatically restart an hsserver process that has failed. Use this parameter to specify the number of seconds the server waits before restarting a failed process. Generally, you want a short delay to prevent looping that could occur if the system is running out of memory or disk space. The default is 3 seconds. Specify zero for this entry if you do not want to restart the hsserver processes. (Not available at Host-Specific level.) Enter the number of seconds to continue trying to restart a failed hsserver process. If this period lapses before successful restart, the Application Server executive process (hsexec or hsrexec) gives up. (Not available at Host-Specific level.) Check this box if you want to preload into memory all of an application s object files that are referenced by the application s symbol table (.htx or.htx) file. This box is checked by default. Preloading ensures that the application can be replaced (i.e., republished) on the server without affecting copies of an application that are already in use. If this box is not checked, the Application Server loads an application s objects (dynamic pages) as they are referenced. This option should be checked for server groups that are used by HAHTsite authors to deploy and test new versions of applications. For production servers, the option should be checked if you want to update applications at a site without taking the Application Server down and restarting it. (Not available at Host-Specific level.) 68

Chapter 3: Performing Administrative Tasks Field Name Application Timeout Poll Interval Default Application Timeout Interval Description A server group s hsserver process periodically polls its applications to determine whether: Any applications (represented by their StateIds) should be terminated because they have reached their time-out value, defined by the parameter Default Application Timeout Interval. Any applications should be purged from the Application Server s cache because they have been completely idle (have no active StateIds) for the duration of their Idle Timeout period, as defined by the parameter Idle Timeout. Use this parameter to specify the number of seconds between these polls. The default is 10 seconds. (Not available at Host-Specific level.) Specifies the interval to use for timing out applications. If this number of seconds lapses between uses of a peruser/per-application session (a StateId), hsserver terminates the application (the application s StateId expires). The timeout timer restarts each time an application makes a page request. Each StateId is timed independently. A value of -1 means do not time out ever. A value of zero means time out immediately after the current page finishes executing. This parameter sets the default timeout interval for all applications running on a server group. The IDE programmer can, however, override the default by specifying the timeout explicitly in the application using HAHTtalk Basic or Java code to reference the Session object s Timeout property. E.g., calling the Session object s settimeout method with a value of 600 sets an application s timeout property to ten minutes without affecting other applications running in the same server group, which continue to get their timeout interval from this parameter. (Not available at Host-Specific level.) 69

Chapter 3: Performing Administrative Tasks Field Name Default Application BusyTimeout Interval Idle Timeout Description This timeout interval goes into effect when an hsserver process is busy that is, when the number of sessions assigned to the hsserver process is at the limit specified by the runtime option Limit Number of States per Process. By specifying a lower value for this option than for the Default Application Timeout Interval, you can cause sessions to be timed out more quickly when the Application Server is busy. (Not available at Host-Specific level.) Multiple users can share a single copy of a HAHTsite application. Use counts are maintained as each user connects to the application (starts it) and disconnects (terminates or times out). Use the Idle Timeout property to specify the number of seconds a HAHTsite application must be completely unused (no sessions are using the application) before the server group purges the copy of the application from its cache. An application s idle timeout starts when an hsserver process detects that no more StateIds are active for the application (the application s use count is zero). When Idle Timeout seconds are up, the application s code pages are flushed from memory. If a new StateId is started on the application, the use count increments, and the idle timeout is not reset until the use count again goes to zero. (Not available at Host-Specific level.) 70

Chapter 3: Performing Administrative Tasks Field Name Connection Cache Timeout Limit number of sessions per process (0 for no limit) Include partial page output with runtime errors Description Enter the number of seconds that must pass before a cached database connection is closed. Note that the Application Server runs a thread that closes cached connections every 30 seconds. By specifying a timeout value, you are guaranteed that the connection will be cached for at least the number of seconds you specify. The connection may remain open for almost a minute longer, depending on when the connection became inactive. Specifying a non-zero value here automatically turns on database connection caching for a server group. Connection caching means that database connections are reused rather than being immediately closed when they are no longer being used. Connections will be kept open, so they can be used by another connection request. This improves performance by reducing the number of database opens and closes. (Not available at Host-Specific level.) A value entered in this field places a limit on the number of concurrent sessions that can be assigned to each hsserver process. Once this limit is reached for a particular hsserver process, no new sessions will be assigned to that process until one or more of the active sessions times out. However, the "BusyTimeout Interval" goes into affect for that hsserver process. See "Default Application Busy Timeout Interval" above for more details on this. Once the limit on the number of concurrent sessions has been reached for all of the hsserver processes, an error is returned to any user attempting to start a new session. Specifies how the Application Server should behave when it is partially through executing a dynamic page and a runtime error occurs. Here are the settings: If the box is checked, the Application Server displays the error message and the output of a dynamic page that has been generated up to the point where the error occurs. If this box is not checked, the Application Server displays only the error message. 71

Chapter 3: Performing Administrative Tasks Field Name Check Client IP Addresses for Changes Log a warning for pages with a run time greater than this number of seconds Limit on Time for Execution of a Page (in Seconds, use 0 for No Limit) Description The Application Server maintains state across applications by generating a StateId for the application for dynamic pages. The Application Server propagates the same StateId through the application s pages by including the StateId in relative URLs for the duration of the session. To prevent someone from copying a URL with a StateId and posing as a legitimate user, the Application Server encrypts the client IP address of the original sender as part of the StateId. Each time a page is run, the Application Server checks to see if the client IP address of the sender matches the IP address in the StateId. If they do not match, the Application Server does one of the following: If the Check Client IP Addresses for Changes box is checked, the Application Server rejects the connection and logs the occurrence as an error in the hsserver log. This setting is the default. If the box is not checked, the Application Server runs the page and logs the occurrence as a warning in the hsserver log. The occurrence is logged even if you have your Logging Options set to log only errors, and not warnings. (See Logging options on page 77.) Specifies the maximum amount of time (in seconds) that a HAHTsite page can execute before the Application Server generates a warning in the log file. These warnings allow you to identify dynamic pages in a HAHTsite application that are taking a long time to execute. This number should be determined according to the requirements/expectations of your application users. For example, while three seconds may be an appropriate wait time for an average application, an application that contains complex reports might be expected to take a little longer. Specifies the maximum amount of time (in seconds) that a HAHTsite page can use before the system terminates the page. The purpose of this parameter is to prevent a page from looping endlessly. If you set this parameter to 0, no limit is set. This value is set, by default, to 120 seconds (two minutes). 72

Chapter 3: Performing Administrative Tasks Field Name Limit byte size of response pages (0 for no limit) Automatically start this Server Group Username Password Domain (Windows NT only) UNIX Group (UNIX only) Use the above user account for debug sessions only Base of Public IP Port Range for Server Group (0 lets TCP/IP Choose) Base of Private IP Port Range for Server Group (0 lets TCP/IP Choose) Encrypt data Packets between Foreground and Background Hosts Description If you want to limit the size of response pages, enter the maximum number of bytes to allow. Accept the default (0) for no limit. A page that exceeds the limit is treated like a runtime error, as explained for the parameter Include partial page output with runtime errors. Check this box if you want this server group to start whenever the Application Server is started. Optional user name for the account under which to run applications on the Server Group. Optional password for the account under which to run applications on the Server Group. Optional domain name for the account under which to run applications on the Server Group. Optional UNIX group name for the account under which to run applications on the Server Group. Use the above username to start debug sessions only. A username must be specified when debugging Java projects while the App Server is running the Microsoft Java VM. Optionally enter the base of the public IP port range for this group. Relevant only if a foreground or background host is behind a security firewall. Optionally enter the base of the private IP port range for this server group. Check the box if you want foreground hosts to encrypt data prior to sending it to background hosts. Encryption offers increased security at the cost of a small processing overhead. If you enter invalid parameters on the Runtime options form When you save your changes on the Runtime options form, an error message notifies you if any parameters are invalid and tells you that the server group 73

Chapter 3: Performing Administrative Tasks configuration was not updated. For example, setting Maximum debugging processes to 100 yields the following message: If an Invalid value for... message appears 1 Click Edit Values. The Runtime options form appears, displaying the maximum value for the invalid parameter to the right of the parameter s field. 2 Type a new valid value into the field. 3 Click Save Changes. 74

Chapter 3: Performing Administrative Tasks Language options The Language options form provides access to fields used to set HAHTtalk Basic-, Java-, and CORBA-specific Application Server parameters for a server group. The server group Language Options form appears when you select Language Options with a server group selected. Note - If you have read access to a group, you can view the language options but cannot change them. The following table describes the configurable parameters on the Language Options page. Field Name HAHTtalk Basic Extensions Installed Description Specifies the extensions to the HAHTtalk Basic library that you want loaded when the server group is started. The items checked here must be located in the bin subdirectory of the Application Server s installation directory. The options are: Database - database access object Internet - Internet access object (e-mail, ftp, sockets) ADO - Active Data Objects extensions NLS - National Language Support extensions 75

Chapter 3: Performing Administrative Tasks Field Name Maximum Public Space Java Virtual Machine Type Allow application sessions to be started via CORBA Description Sets the maximum amount of global variable space allowed for any HAHTsite application run by this server group. This Application Server value overrides a HAHTsite project s public-space definition if the project s value is larger. A project s public space is defined in the IDE. The maximum value for this parameter is 16 MB. Select either Sun or Microsoft as the Java Virtual Machine type for this server group. The Java Virtual Machine chosen must be installed on all hosts participating in the server group. Check this box to enable remote CORBA initialization of application sessions 76

Logging options Chapter 3: Performing Administrative Tasks Use the Logging Options form to select the kinds of information that you want to log for a server group. (If you have read access to a group, you can inspect but cannot change the logging options.) 77

Chapter 3: Performing Administrative Tasks You can select Logging Options with a host, rather than its group, selected. You can make changes to the Logging Options form while the server group is running. All changes will take effect without restarting the server, except where noted in the following table. The following table explains logging option fields. Field Name Log File Directory Add Error Detail to Error Page Log Severity Level Description By default, a server group s log files are written to the logs subdirectory in the installation directory, stored in the %INSTALLDIR% variable. Accept this default or enter another pathname. Requires restart to implement change. Check this box to append a log file entry for a server error message to the error page sent to the user. Choose one of the listed levels: Log Errors Only Log Errors and Warnings Log Errors, Warnings, and Info Log Debug Messages also Only the selected severity level will be logged. 78

Chapter 3: Performing Administrative Tasks Field Name Log Flush Interval (in seconds) Error Page Directory (Optional) Type of log rotation Time of day to rotate log (time past midnight) Time between rotations of log Description Specifies the number of seconds that information for the log file should be kept in the Application Server s memory buffer before being flushed to the log file (written to the log file and removed from the buffer). Templates for creating customized error messages are provided with the Application Server. If you use this feature, the customized error message is displayed instead of the standard error page when hsserver sends back an error and generates a Web page for the error. The Error Page Directory is the path to the directory that contains any error messages that you have customized. If the Error Page Directory field is blank, hsserver sends back standard error pages. The templates are in the bin subdirectory of the Application Server s installation directory. Here are the file names: HS_debug.html, HS_header.html, HS_page.html, HS_start.html, and HS_state.html. Requires restart to implement change. Choose one of the listed types: No automatic logfile rotation Rename and keep all old log files Rename and keep most recent logfile If you select No automatic logfile rotation, you are responsible for making sure logfiles don t grow indefinitely. You can rotate files on an as-needed basis from the Logfiles form. Enter the number of hours and minutes past midnight when logfile rotation should take place. Enter the logging interval, in hours and minutes. 79

Chapter 3: Performing Administrative Tasks Field Name Enable Statistics Logging Statistics Sampling Interval (in seconds) Description Check this box to enable the creation of a statistics log file for the Server Group. The statistics log file provides a record of the usage and performance of the Server Group over time. Entries are written to the log file at time intervals specified by the statistics sampling interval parameter. The entry for each time interval provides statistics on the application server activity from the time of the previous entry. The statistics log file is created on the control host, and may be viewed in the Administrator utility from the either the Logfiles or Statistics pages. Statistics logging is enabled by default, but may be disabled by unchecking this checkbox. Enter the length of time in seconds for the interval at which entries should be written to the statistics log file. 80

Auditing options Chapter 3: Performing Administrative Tasks Use the Auditing Options form to select the kinds of information that you want to audit for a server group. Audit Logging is an optional logging method that provides a detailed history of the actions performed by users of a HAHTsite application. All input values submitted to dynamic pages as URL fields can be logged, as well as the web server environment variables, and all dynamic HTML page output. 81

Chapter 3: Performing Administrative Tasks Audit logging parameters are defined in the following table: Field Name Enable Auditing Audit Root Directory Auditing Level Description Check this box to enable audit logging (enabling audit logging does not turn auditing on). When this box is checked, auditing can be started by enabling automatic auditing (see below) or by an application invoking the session.startauditing method (which starts audit logging for the application session that invoked it). When this box is not checked, no audit logging is performed even when the Enable Automatic Auditing checkbox is checked or an application invokes session.startauditing. By default, a server group s audit files are written to the audit subdirectory in the installation directory, stored in the %INSTALLDIR% variable. Accept this default or enter another pathname. The audit log files are placed in subdirectories created under this directory. A subdirectory is created for each session with a path of the form: <AuditDirectory>\<StateId>\ For example: d:\hahtsite\audit\tsxpfyqdl9oqfor60nhu8-z- N4 Two audit log files one request file and one response file are created in this directory for each page run. The files are as follows: <PageNumber>.req - the web server environment settings when the page was run and the names and values of the URL fields submitted to the page <PageNumber>.rsp - the HTML output generated by the dynamic page Specify which audit logging files you want created when audit logging is turned on: Audit Input - URL Fields and Environment Variables (env and urlfield) Audit Output - Dynamic HTML pages (results and messages) Audit Input and Output (all audit logging files) This field is ignored unless you check Enable Auditing. 82

Chapter 3: Performing Administrative Tasks Field Name Enable Automatic Auditing Start time each day (HH:MM): (Blank implies midnight) End time each day (HH:MM): (Blank implies midnight) Description Check this box to enable automatic auditing. Automatic auditing takes place according to a preset schedule defined by the following two fields.when checked, the two options that follow control when automatic auditing is performed. This field is ignored unless you check Enable Auditing. Select the start time for automatic auditing. If automatic auditing is enabled and this field is not filled in, automatic auditing will start at midnight each day. This field is ignored unless you check Enable Auditing. Select the end time for automatic auditing. If automatic auditing is enabled and this field is not filled in, automatic auditing will end at midnight each night. This field is ignored unless you check Enable Auditing. 83

Statistics Chapter 3: Performing Administrative Tasks Clicking the Statistics button reveals three statistics category buttons you can use to access specific statistics forms to view statistics about the server groups, or about applications that are running on the selected server group. The three statistics categories are CURRENT - current server group activity statistics (See Current statistics on page 85.) CUMULATIVE - data for all server group activity since startup (See Cumulative statistics on page 88.) HISTORY - displays a logfile of server group activity statistics (See History on page 89.) The server group must be running before you can view any statistics about it or its applications. A message informs you if you ve selected an inactive server group or host. 84

Chapter 3: Performing Administrative Tasks Current statistics Current group activity statistics are updated onscreen once every minute. Note that the displayed figures are for the previous minute. For example, if you open the statistics container between 10:01 and 10:02, you ll see statistics for the interval between 10:00 and 10:01. The display will be updated at 10:02 for the next minute while data for the minute ending at 10:03 is collected. The following table describes each of the items reported on the Current Statistics page for a Server Group: Field Name Sessions active Sessions started Sessions timed out Sessions terminated Description The number of application sessions currently active. The total number of application sessions that have been created on the selected Server Group (since the Server Group was started, or in the last minute). The total number of application sessions that have timed out due to inactivity. The number of application sessions terminated during the previous minute. 85

Chapter 3: Performing Administrative Tasks Field Name Dynamic pages processed Secure static pages processed Errors reported Pages with long run times Description The total number of dynamic pages that have been run on the selected Server Group (since the ServerGroup was started, or in the last minute). The total number of secure static pages that have been run on the selected Server Group (since the ServerGroup was started, or in the last minute). Total number of errors reported The total number of dynamic pages that have had an execution time that was long enough to generate a warning in the Application Server log file. The number of seconds after which a page generates a warning is a runtime option, and can be configured in the Runtime options screen of the Application Server Administration tool. If this number is significant, you should examine the Application Server log files and identify the specific pages that are taking a long time to execute. You should then examine these pages, checking to see if the application code or database access queries that can be optimized for better performance. For the following statistics, the minimum, maximum, and average values are reported: Field Name Pages per completed session Session elapsed time Description The minimum, average, and maximum number of pages that were run on sessions that have been completed (stopped explicitly or timed out due to inactivity). Note that these values will all be 0 until at least one session has been completed after the startup of the Server Group. The minimum, average, and maximum elapsed time for sessions active during the previous minute. 86

Chapter 3: Performing Administrative Tasks Field Name Session run time Session CPU time Pages per process per minute Page run time Page CPU time Description The minimum, average, and maximum seconds of cumulative elapsed time to run all of the pages during an application session. The elapsed time to run a page is measured as the wall clock time that the Application Server takes to run the HAHTtalk Basic to execute the page (and any time the application spends waiting on I/O, database queries, etc.), but does not include the time required to communicate the dynamic page request from the browser to the Application Server over the network or to communicate the response. Only sessions that have completed are considered in this statistic. The minimum, average, and maximum seconds of cumulative CPU time to run all of the pages during an application session. The resolution of the CPU time is in milliseconds, and some simple pages may execute in less than one millisecond, so the minimum reported here may be 0.000. Only sessions that have completed are considered in these calculations. The minimum, average, and maximum number of dynamic pages run on each Application Server process during each one minute interval. To get the average number of pages run on all of the Application server processes, the number reported here would need to be multiplied by the number of Application Server processes configured. The minimum, average, and maximum seconds of elapsed time to run a dynamic page. The elapsed time to run a page is measured as the wall clock time that the Application Server takes to run the HAHTtalk Basic to execute the page (and any time the application spends waiting on I/O, database queries, etc.), but does not include the time required to communicate the dynamic page request from the browser to the Application Server over the network or to communicate the response. The minimum, average, and maximum seconds of CPU time to run a dynamic page. The resolution of the CPU time is in milliseconds, and some simple pages may execute in less than one millisecond, so the minimum reported here may be 0.000. 87

Chapter 3: Performing Administrative Tasks Field Name Page request time on queue Page size (bytes) Description The minimum, average, and maximum amount of time that a request to run a dynamic page has waited in the Application Server s queue because the Application Server process was busy servicing other dynamic page requests. If the average value for this statistic seems large (over 0.1 seconds), you should consider increasing the number of Application Server processes or threads. This allows the Application Server to achieve more parallelism in the processing of dynamic pages. The minimum, average, and maximum number of bytes of HTML generated by a dynamic page. Note that for dynamic pages containing images or image maps, the page size reported here only includes the size of the HTML tags, and not the sizes of the actual images. Cumulative statistics The Cumulative statistics form is identical to the Current statistics form, except that the data displayed is for activity since the server group was started, instead of for the previous minute alone. The display is updated once each minute, at which time data for the most recent one minute interval is added to the previous data totals. 88

Chapter 3: Performing Administrative Tasks History Clicking the History button displays a chronological logfile of group statistics. Field Name Year Month Day Time Host Description year of the entry month of the entry day of the entry time of the entry the host s name For information on the remaining fields on this form, see the related field s description under Current statistics and Cumulative statistics above. 89

Sessions Chapter 3: Performing Administrative Tasks The Active Sessions page provides a detailed list all active sessions running on a Server Group. With this data an administrator can choose the best time to shutdown a server group, or selectively terminate a specific session without shutting down the entire group. The following table describes the fields on the Active Sessions page. Field Name Server Process Application Page Currently Running Description This number identifies the hsserver process to which the session is assigned. The Application column gives the name of the application s symbol table (.htx or.hjx) file. Clicking on the application name link brings up a page that allows an authorized administrator to terminate that active session without shutting down an entire Server Group. The name of any page currently being executed for this session. 90

Chapter 3: Performing Administrative Tasks Field Name Session Username Client IP Address Time Session Started/Last Used Pages Run Run Time CPU Time Description The Session Username will be anonymous unless the application sets the UserName property of the Session object to associate a username with the session. IP address of the client running this session. Start time and time of last activity for this session (hh:mm:ss). The total number of pages run for this session. Total run time for this session The time the CPU committed to run all pages for this session. 91

Services Chapter 3: Performing Administrative Tasks You can configure a CORBA server application to run as an application service, allowing the application s objects methods to be invoked by many clients (either applets or HAHTsite server applications). You can configure an application to act as an application service and manage it using the Application Services form. Application services tasks From the Application Services form you can: specify a list of services to be started when a server group is started explicitly start or stop an application service on demand optionally specify a "required Background Host" on which to run each service (if not specified, the services will be distributed among Background Hosts using the normal load balancing algorithm) An application service is always invoked via CORBA. Services cannot run standard dynamic pages via HTTP and hsrun. Application services are available until explicitly stopped by the administrator. From the Application Services form, you can use the Create, Edit, and Delete buttons to configure the Application Services defined for a server group. 92

Chapter 3: Performing Administrative Tasks To create an application service 1 Click CREATE on the Application Services form. The Create Application Service form is displayed. 2 Complete the form s fields, as described below. Field Application Service Name Application Path Description This field is a name that you give to the application service that will be used in the display on the Application Services form This field specifies the location of the published HAHTsite application s bind file (i.e., the.hjx file for a Java application). The value entered in the field should be the relative pathname to the.hjx file from the server group s application root (approot) directory. For example, if the HAHTsite application to be defined as an application service is a Java application named "MyProect" located in the "MyProject" subdirectory of the application root directory, then the value entered for Application Path (on Windows NT) should be: \MyProject\MyProject.hjx 93

Chapter 3: Performing Administrative Tasks Field Limit Service to Host Description In this field you may optionally specify the name of one of the Background Hosts that is participating in the server group. In this case the Application Service will run only on the Background Host specified. If the server group is down on the specified Background Host, then the Application Service will be down. If no value is specified for this field, then the Application Service can be assigned to run on any of the participating Background Hosts by the Application Server. Furthermore, in the event that the Background Host on which the Service is running is shutdown or abnormally terminates, the Application Server will be able to restart the Service on another running Background Host. 3 Click CREATE. A message appears indicating that the service was successfully created. To edit an application service definition 1 Click EDIT on the Application Services form. 2 Modify the values for Application Path, Limit Service to Host, or both as desired (see above for details on these fields). 3 Click SAVE CHANGES. To delete an application service 1 With the application service selected on the Application Services form, click DELETE. A confirmation screen appears to ensure you intend to delete the service. 2 Click DELETE. A screen appears confirming that the service has been deleted. 3 Click RETURN. To start an application service Click on the green status indicator next to the service you want to start. To stop an application service Click on the red status indicator next to the service you want to stop. 94

Applications Chapter 3: Performing Administrative Tasks The Applications form provides information for all active applications running on a server group. The Application column gives the name of the application s symbol table (.htx or.hjx) file. The other columns give either statistics for all configured hsserver processes on all hosts (with a group selected), or for all configured hsserver processes on a host in the selected server group (with a host and server group selected). 95

View log files Chapter 3: Performing Administrative Tasks Use the Log Files form to view the log files, either in their entirety or selectively. You can also rotate the logfile. When you click Log Files, the View Log Files form appears. You can click Log Files with a host selected, rather than a distributed group. If you do, the form is the same, but the information viewed will be only for the selected host, rather than for the server group. You can choose from the following options on the View Log Files form: View log file of the hsrexec process - specifies that you want to view the log file of the Application Server s executive process (hsrexec). Select this option to see start-up and shut-down messages for the hsserver 96

Chapter 3: Performing Administrative Tasks processes, the runtime parameters that are in effect when an hsserver processes stars, logged messages for hsrexec, and start-up messages for hsdebug. View log files for each of the hsserver processes Specifies that you want to view a log for the hsserver processes configured in Runtime options of the Administrator utility. If you are looking for a logged message, start with this log file, which is generally more useful to administrators than the executive process log. This option shows all of the log files sorted by hsserver process. To go from one log file to the next, click Next Log File. Click Previous to go to the previous log file, or click Return to go back to the View Log Files form. View the last 30 lines of all hsserver process log files Lets you limit, for each hsserver process, the display to the most recent lines. Note - The settings in the Logging Options form of the Administrator utility control the types of messages (for example, warning or error) that are logged. The Log Flush Interval in Logging Options specifies the amount of time that messages for the log file are kept in the Application Server s memory buffer before being flushed to the log file. If the Log Flush Interval parameter is set to a high value, you may not see logged entries immediately. 97

Chapter 3: Performing Administrative Tasks Analyzing log files In addition to the hsrexec and hsserver log files which can be viewed in the Administrator utility, the Application Server creates some other logs files that are not viewable within the Administrator utility. At certain times, it may be useful or necessary to view these log files. These log files are standard text files, and can be viewed with a text editor, such as Notepad, or vi on UNIX. The following table contains a list of log files, file names, and descriptions. Log File FileName Description Control Process Log File Foreground Host Log File hsadmininstallname.hostname. hscontrol.log Example: hsadminsales.thisserver.hscontrol.log hsadmininstallname.hostname. hsredir.log Example: hsadminsales.thisserver.hsredir.log This log file is created by an hscontrol process on a control host. It logs messages that indicate when foreground, background, and backup control hosts start up, connect to the control host, shut down, and disconnect. If a foreground or background host is having trouble connecting to the control host, check for errors in this log file. This log file is created by the hsredir process on a foreground Host in a distributed configuration. If the Foreground process/service appears to be started, but the Administrator utility shows the status as not started, check this log file for errors. 98

Chapter 3: Performing Administrative Tasks Log File FileName Description Background Host Log File hsadmininstallname.hostname. hsradmin.log Example: hsadminsales.thisserver.hsradmin.log This log file is created by the hsradmin process on a background host in a distributed configuration. If the background process/service appears to be started, but the Administrator utility shows the status as not started, check this log file for errors. 99

Access control Chapter 3: Performing Administrative Tasks The Access Control form allows you to define the method of determining access privileges, password verification, or both for all applications published to this server group. Once access control is enabled, you can choose to have access privileges checked against a database repository, or indicate that privileges will be determined by a custom Java implementation. You can also indicate the type of password authentication this server group will use; database repository or custom Java application as above, or using the operating system authentication routine. Field Name Enable Access Control Description Check this checkbox to have the Application Server enforce the application Access Control mechanism restricting access to any pages or secure-static project items unless the user s session has the Privileges required for that item. 100

Chapter 3: Performing Administrative Tasks Field Name Privilege Repository Type Authentication Type Description Select a radio button to specify the type of Privilege Repository. A Privilege Repository refers to a database or some other source for the data describing application users and the privileges granted to those users. The options are None - choose this option if you do not wish to use a Privilege Repository to look up the privileges for users. This allows you to enable and use the Access Control mechanism without having a Privilege Repository. In this case however, any application for which Privilege requirements have been defined must also contain logic to assign privileges to a user's session. Database - choose this option to use a database for the Privilege Repository. The database can be any database accessible from a HAHTsite application (via ODBC or HAHTsite's native database drivers). The database specified must contain the HAHTsite Privilege Repository tables. When you choose this option, you must also specify a Database Connection String. User Defined Implementation - choose this option to implement your own custom method for looking up the privileges for a particular user. In this case, the Privilege Repository access mechanism must be written in Java, implementing the Java classes: UserDefinedGlobalPrivileges and UserDefinedUserProfile. Select a radio button to specify the type of username and password authentication. The options are None - no login verification will occur. (The Application Login widget cannot be used if this option is chosen.) User Defined Implementation - implement custom code for authentication. In this case, the password authentication mechanism must be written in Java, implementing the Java class UserDefinedAuthentication. Operating System Authentication - the Application Server uses the operating system's standard password authentication mechanism. 101

Chapter 3: Performing Administrative Tasks Field Name Connection String (for Database Privilege Repository) Description Specify a database connection string for the specified database privilege repository. 102

Admin rights Chapter 3: Performing Administrative Tasks You can perform five procedures from the Admin Rights form. The first four can only be performed by the master administrator. They are change the master administrator account create the HAHTsite password file maintaining the HAHTsite password file Set the initial master administrator password (UNIX) The fifth, which may be performed by a server group administrator with write access as well as by the master administrator assign administrative rights The following figure shows the Administrative Rights form at a site that does not currently use HAHTsite authentication. This is the form a master administrator will see the first time the Administrator utility is started on a Windows NT system. 103

Chapter 3: Performing Administrative Tasks The following figure shows the Admin Rights form at a site that already uses HAHTsite administration. This is the form a master administrator is likely to see the first time the Administrator utility is started on a UNIX system. Where operating-system authentication is in use, the CREATE HAHTSITE PASSWORD FILE button appears. Where HAHTsite authentication is in use, the ADMINISTER APP SERVER USERS button appears. The forms are otherwise identical. Changing the master administrator account To change the username of the master administrator, first verify that the account name exists in the password file your site uses and that you know the password associated with the username. If you re using HAHTsite authentication, you can use the procedures described on the previous page to make this verification and, where necessary, create a new account for the master administrator. Otherwise, use procedures provided by the operating system for maintaining user accounts. To change the master administrator account After verifying that the new account exists, 104

Chapter 3: Performing Administrative Tasks on the Admin Rights form, enter the new name in the Master Administrator field, and click Change Master Administrator. If the username doesn t exist in the password file in use, the change will fail. Creating the HAHTsite password file To create the HAHTsite password file 1 Click CREATE HAHTSITE PASSWORD FILE. A form for entering the initial master administrator account appears, displaying the username of the current master administrator. 2 In the Password field, enter the password matching this username. 3 In the Confirm Password field, re-enter the same password, and click CREATE HAHTSITE PASSWORD FILE. If the two password entries do not match, an error message will appear. Click RETURN to try again. Once you enter two matching passwords, the HAHTsite password file is created, the master administrator account is added to the file, and a confirmation page with the button ADMINISTER APP SERVER USERS appear. You should click this button now and add accounts for any current server group administrators or developers, as explained in the next section. 105

Chapter 3: Performing Administrative Tasks Note - Once the HAHTsite password file is created, current server group administrators or developers will be unable to log in to the Administrator, or start a debugging session, until you add their usernames and passwords to the HAHTsite password file. If you assign current server group users the usernames and passwords they re accustomed to, they ll be able to log in as before and will have the same privileges. Maintaining the HAHTsite password file The Administer HAHTsite Application Server Users form appears whenever you click the ADMINISTER APP SERVER USERS button. Use the form to add or remove a user, or to change a user s password. To add a user 1 Click the ADD USER button to display the Add New HAHTsite Application Server User Form. 106

Chapter 3: Performing Administrative Tasks 2 Type the user s name and password in the appropriate fields. Retype the password in the Confirm Password field. 3 Click ADD USER. If the Password and Confirm Password fields match, a confirmation message occurs. Click ADMINISTER APP SERVER USERS. If the two passwords do not match, you will be prompted to re-enter them. You cannot complete the action until they match. Note - See HAHTsite username and password syntax on page 108 for a list of restrictions on what you can enter. To change a user s password 1 With the account name selected, click the CHANGE PASSWORD button to bring up the Change User Password Form. 2 Type a new pasword in the Password field, and retype the new password in the Confirm Password field. 107

Chapter 3: Performing Administrative Tasks 3 Click the CHANGE PASSWORD button. If the Password and Confirm Password fields match, a confirmation message appears. Click RETURN. If the two passwords do not match, you re prompted to re-enter them. You cannot complete the action until they match. Note - See HAHTsite username and password syntax on page 108 for a list of password restrictions. To remove a user 1 With the account name selected, click REMOVE. A confirmation message appears. 2 Click RETURN. HAHTsite username and password syntax HAHTsite username and password syntax is the same for UNIX and Windows NT: Both the username and the password are limited to 20 characters. The username is not case sensitive. The password is case sensitive. Colons (:) and quotes (" ") are illegal characters. Setting an initial master administrator password (UNIX) On UNIX hosts, HAHTsite authentication may be set up during installation in one of two ways: The installer was not logged on as root. The installer was logged on as root, but specifically requested HAHTsite authentication. Where HAHTsite authentication (the default) is set up during installation, the master administrator username is the one specified by the installer and the password to use for the initial login is null. The first thing that the Administrator (or installer) should do is assign a password to the master administrator account. To set an initial master administrator password (UNIX) 1 On the Admin Rights form, click ADMINISTER APP SERVER USERS. 108

Chapter 3: Performing Administrative Tasks 2 On the Change Password form, enter a password for the master administrator account. (See Creating the HAHTsite password file on page 105.) Changing authentication methods If, after setting up your site for one authentication method, you decide to switch to the other method, use the Administrative Rights pull-down to compile a list of usernames with any access to all Server Groups. This will allow you to make sure that users who currently have access to Server Groups will have the same access when you ve switched to the other authentication method. The username in the login account file needs to match the username column on the Administrative Rights form. It is particularly important to make sure that the username of the master administrator is a valid login account name in the authentication method you re changing to. If you have been using HAHTsite authentication and you want to change to operating-system authentication, delete the password file (HAHTsiteInstallDir/conf/hspasswd). If the file is not on your system, the utility automatically uses operating-system authentication. If you switch to operating-system authentication on UNIX, you need to change the access mode of the Administrator utility processes so they can access the password file. If your site uses a distributed Application Server configuration, issue these commands from the shell on the Control host (in the HAHTsiteInstallDir/bin directory): chown root hsadmsrv hscontrol chmod 4755 hsadmsrv chmod 4755 hscontrol Assigning administrative rights The Admin Rights operation lets you define one or more administrators for the selected server group. You also grant read or write permissions to each administrator. In addition, the Admin Rights operation lets the master administrator configure the Administrator utility to use HAHTsite authentication to validate logins to the utility instead of operating-system authentication. (For complete details on this feature, see User account authentication on page 53.) 109

Chapter 3: Performing Administrative Tasks Only the Master Administrator and administrators with write access can use this form. Note - You can enter usernames that do not exist in the accounts file (operating system or HAHTsite password file). However, if you do this, the users will not be able to start the Administrator until their names and passwords are added to the appropriate accounts file. To give a user administrative rights to this server group, enter the Username. Then select the type of access: Remove - Check this radio button to remove an administrator s privileges. The administrator will still be able to log in, but will no longer have any access to this server group. Read - Check this radio button to grant read-only rights to the user specified in the Username field. Administrators with read-only rights can read the Directories, Runtime, and Logging Options forms but cannot change any values on them. The Admin Rights form is not accessible at all. 110

Chapter 3: Performing Administrative Tasks All - Check this radio button to grant full administrative access to this server group. A server group administrator with All access can do everything for this server group that the master administrator can, including granting full administrative access to any other user with a login account, and removing access. Remote Debugging Right - Check this box to grant remote debugging rights to the user specified in the Username field. A developer with debugging access can start debugging sessions for applications published to this server group. Login is required: developers, like server group administrators, require login accounts. Note - By itself, debugging access to a server group confers no administrative access. 111

Chapter 3: Performing Administrative Tasks License information Use the Application Server License Information form to view and update active sessions license information. The form appears when you click on the License Information button in the sever groups frame. The top portion of the form displays license information statistics. The License Information form provides the following information about your Application Server license: Field Name Machine Id Licensed Installation Name Description This is a unique string that identifies the machine (the control host in distributed configurations) licensed to run this Application Server. This Application Server will not run on any other machine (unless installed on a foreground or background host). If you make a request to upgrade your number of active session licenses, you will need to provide this Id. If you would like to transfer the Application Server to a different machine, you must contact HAHT Software to request the transfer. This name identifies the Application Server installation. The installation name is (optionally) specified when the Application Server is installed. If you make a request to upgrade your number of active session licenses, you will need to provide the Installation Name (if one was specified). 112

Chapter 3: Performing Administrative Tasks Field Name Licensed Active Session User Sessions Currently Active User Sessions Available Description The number of active sessions that are licensed for this installation of the Application Server. The Application Server keeps track of the number of active user sessions across all Server Groups. When the license limit has been reached, and a user requests a new session, an error page will be returned. The number of user sessions currently active on this Application Server installation across all Server Groups. The number of additional user sessions that can be started before reaching the licensed active sessions limit, i.e., the difference of the two values described above. 113

Chapter 3: Performing Administrative Tasks Upgrading the number of active session licenses You can use the License Information form to enter a new license key string. This is necessary in order to upgrade your Application Server for additional active sessions. The mid-portion of the License Information form displays license key upgrade information. To upgrade your license, you must first obtain a new license key from HAHT Software. License keys can be obtained electronically (via a Web application, accessible through the Request License Key link on the form), or in hard copy form, by contacting HAHT s Sales department. For security reasons, all new license keys will be emailed. Once you receive the new key, enter it in the New License String text box on the License Information form, and click the Save Changes button at the bottom of the form. This installs the new license key immediately - there is no need to restart the Application Server. The statistics displayed on the License Information form will be updated to reflect the new licensed user count. For more information about obtaining a new license key, refer to the following contact information: Email address: apkey@haht.com Phone number: 919-786-5210 114

Chapter 3: Performing Administrative Tasks Configuring email information for warning messages You can choose to have warnings sent via email messages when the number of active sessions nears the number of licensed active sessions. These warnings will alert you of those times when you are close to your number of active session licenses, and users may be denied access. To have the Application Server send these warning messages, you must specify an email address and SMTP host in the License Information form. To find the Warning Message Configuration section, scroll to the bottom of the License Information form. If the Application Server is configured to send warning messages, the first warning message will be mailed when the number of active sessions first reaches 80% of the number of licensed users. Additional messages will also be sent when the percentage first reaches 90%, 95%, and 100%. To avoid excessive email traffic, a warning message will be mailed only the first time the number of active sessions reaches each level. To reset the Application Server, specify a value in the first field. 115

Chapter 3: Performing Administrative Tasks 116

Other Administrative Procedures 4 Introduction... 118 Manually starting administration services... 119 Distributed Application Server configuration... 120 hscontrol... 120 hsredir... 120 hsradmin... 120 Starting HAHTsite Application Server Installations... 121 Changing the Application Server s user/group ownership (UNIX)... 122 Defining the Application Server s environment... 122 Changing the UID/GID of the server group s configuration file... 123 117

Chapter 4: Other Administrative Procedures Introduction This section describes administrative procedures that are not part of the Administrator utility. You perform them, as necessary, from the operating system of the Application Server host. You probably need to log in using an operating system account with administrative privileges. 118

Chapter 4: Other Administrative Procedures Manually starting administration services Server groups, as well as the Administrator utility, require that one or more Administration services (processes) be running. Some or all of these services may start when a system boots. Should the processes stop for any reason, you can restart them manually as explained in this section. If you attempt to start the Administrator and a required administration service is not running, an error message like the one shown below appears. If you get this message, you must start required services. The procedures differ for Windows NT and UNIX. 119

Chapter 4: Other Administrative Procedures Distributed Application Server configuration A number of processes must be running (whether or not any distributed server groups are running) on control, foreground, and background hosts. hscontrol on the control host. To start it, do one of the following: Windows NT: from the Control -> Services panel, start: HAHTsite 4.0 Controller (installname) Where installname is the name of the Application Server installation. UNIX: from HAHTsiteInstallDir/bin, issue this command:./hahtsite -c start hsredir on each foreground host. To start it, do one of the following: Windows NT: from the Control -> Services panel, start: HAHTsite 4.0 Foreground (installname) Where installname is the name of the Application Server installation. UNIX: from HAHTsiteInstallDir/bin, issue this command:./hahtsite -f start hsradmin on each background host. To start it, do one of the following: Windows NT: from the Control -> Services panel, start: HAHTsite 4.0 Background (installname) Where installname is the name of the Application Server installation. UNIX: from HAHTsiteInstallDir/bin, issue this command:./hahtsite -b start When hscontrol starts, it in turn starts a child process hsadmsrv. Administrator utility sessions run on the control host as StateIds of hsadmsrv. When you start a distributed group from the Administrator utility, the following happens on each background host: 120

Chapter 4: Other Administrative Procedures hsradmin starts an hsrexec process for the server group. hsrexec starts the configured number of hsserver processes for the group on that host. Starting and Stopping the Application Server Manually (UNIX) Here s how to use the HAHTsite start-up script to start and stop the Application Server from the command line: 1 Go to the bin subdirectory of the Application Server s installation directory. 2 To start the Application Server, type:./hahtsite start When prompted, enter the password of the user account under which you want the Application Server to run. 3 To stop the Application Server, type:./hahtsite stop Starting HAHTsite Application Server Installations The HAHTsite.tab feature lets you designate specific HAHTsite Application Server installations to start up automatically at system start-up. When the system boots, the system looks in this file to get the names and locations of HAHTsite Application Server installations to start. HAHTsite.tab is only available if you installed the Application Server as root. When you installed the Application Server, the setup program put the file in the following locations: Solaris /var/opt/hahtsite/hahtsite.tab HP-UX and AIX /etc/hahtsite/hahtsite.tab Entering Application Server Installations in HAHTsite.tab For each Application Server installation that you want to have started at system start-up, make an entry in the file. Each entry must be on a line of its own. Each entry must have the following three fields separated by colons: The keyword all. the Application Server s installation directory an autostart flag: y means start. Anything else means ignore the entry. 121

Chapter 4: Other Administrative Procedures Sample Entry in HAHTsite.tab Here is an example of an entry in HAHTsite.tab. Note that this system has two Application Servers installed (probably running two different versions of HAHTsite). ALL:/opt/HAHTsite:Y ALL:/tmp/test/HAHTsite:Y Note - At shutdown, the system shuts down all server groups at the directory location specified in the file, not just the server groups named in this file. Changing the Application Server s user/group ownership (UNIX) If you install HAHTsite in a file sharing environment and you own the files, you can use a common account to give other users access. If you set up a common account, you need to change the UID/GID: in the HAHTsite start-up script. of the configuration file (conf) for each server group. Each change is discussed in the following sections. Defining the Application Server s environment The file.envinfo.conf is created in the Application Server s installation directory by the installation script. This file may be edited to customize the environment under which the Application Server will run. The HAHTsite startup script reads this file to set up the environment. For example, if you want to change the User ID (UID) and the Group ID (GID) that the Application Server uses, you can set these parameters in this file. You can also specify an initial shared library path to use. The HAHTsite startup script will add to the shared library path the HAHTsite lib directory, ODBC libraries, and other database-specific library directories defined by the.dbenv.conf file, so those do not need to be included here. However, if your HAHTsite applications call other shared libraries, the directories containing those libraries should be explicitly listed. On Solaris, you can specify the number of file descriptors available to the Application Server with the DESCRIPTORS environment variable. Below is an example.envinfo.conf file for Solaris (the file would be similar on HP-UX and AIX, except for differences in environment variable names). 122

Chapter 4: Other Administrative Procedures # # File:.envinfo.conf # # Purpose: To define installation unique values that define # the environment. # SYSTEMROOT=/opt/HAHTsite UID=guest GID=guest DESCRIPTORS=1000 LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/myapp/libs export LD_LIBRARY_PATH Changing the UID/GID of the server group s configuration file You must change the UID and GID of the server-group configuration files so that: the HAHTsite Application Server Administrator utility will work. users can perform remote debugging. There is a configuration file (conf) for each HAHTsite server group in the conf subdirectory of the Application Server s installation directory. Use these commands to change the UID and GID, respectively: chown UID conf/* chgrp GID conf/* 123

Chapter 4: Other Administrative Procedures 124

Tuning Tips 5 Introduction... 126 Selecting a hardware configuration for the Application Server... 127 Web server performance considerations... 127 Configuring Application Server processes and threads... 129 Can you use multi-threading in the Application Server?... 129 What controls the number of processes and threads?... 129 Guidelines for the process/thread configuration... 130 Analyzing performance problems... 132 High communication time... 133 High page queue time... 133 High page run time... 133 125

Chapter 5: Tuning Tips Introduction This chapter discusses how to configure and tune the HAHTsite Application Server and the related computing environment to achieve optimal performance for your HAHTsite application. To achieve optimal performance, you need to consider the entire system, how the system is laid out, and also the complexity of your HAHTsite application. This chapter points out the factors that affect performance, but you have to experiment to determine what works best for your site. Perhaps the most important factor in determining the ultimate performance of a HAHTsite application is implementing the application itself in an efficient manner. Since HAHTsite dynamic pages are fully programmable in either HAHTTalk Basic or Java, the efficiency of the programmed code, including the efficiency of access to databases or external systems such as SAP R/3, is a key factor in determining the performance of the application. However, a discussion of techniques for efficient programming in Basic or Java, or efficient database or R3 access is beyond the scope of this manual. Note - Except where noted otherwise, the information in this chapter applies to Windows NT and UNIX. 126

Chapter 5: Tuning Tips Selecting a hardware configuration for the Application Server Choosing an appropriate hardware configuration for the HAHTsite Application Server environment is obviously important to achieving optimal performance. It is also highly application dependent. However, here are some general suggestions that should apply to most sites: Use separate machines for the foreground and background hosts. The background host(s) should be dedicated to running the HAHTsite Application Server; these should be separate systems from database servers, R3 servers, etc. For increased high availability of your application or to support a larger number of concurrent users, configure multiple background hosts. Background hosts, where the application logic is executed by the Application Server typically require significantly more processing power and memory than foreground hosts since the web server is generally returning static pages without much processing requirements. For systems to support large numbers of concurrent users, a highbandwidth network is extremely important. The HAHT Knowledge Base in the Support section of HAHT s web site (www.haht.com) provides an Application Server Sizing Worksheet to help determine more specific sizing recommendations in terms of CPU and memory requirements based on application characteristics. Web server performance considerations This section describes how your Web server setup affects performance. Bandwidth limitations on your Web connection At some point, you will reach bandwidth limits on whatever kind of connection you have to the Web (for example, ISDN or T1 lines). With most Web server software, bandwidth limits determine the number of pages per minute that you can process. If you have reached the bandwidth limits on your Web connection, adding additional memory to your machine is not going to speed up processing. 127

Chapter 5: Tuning Tips How your Web server handles CGI requests How the Web server software handles CGI requests affects performance since the Application Server dispatcher (hsrun) uses this mechanism. Web servers support: Embedded CGI via a server-specific API. Microsoft IIS Web server with its ISAPI interface, and Netscape Enterprise and FastTrack Web servers with their NSAPI interface, fit into this category. Having the CGI embedded avoids the overhead of starting a new CGI process for each dynamic page request. This is, consequently, the fastest category. Piped communication with CGI processes or communication via sockets. Apache fits into this category. A Web server that supports piped communications handles more dynamic pages per minute than one that supports buffered CGI processes. Buffered CGI processes, where all communication between the CGI process and the Web server is handled via disk files. 128

Chapter 5: Tuning Tips Configuring Application Server processes and threads This section provides guidelines for configuring the number of Application Server processes and multi-threading within the Application Server. Can you use multi-threading in the Application Server? Before you begin tuning the number of processes and threads on your Application Server, you need to make sure that other software you call from your HAHTsite applications support the use of multiple threads. For instance, if you have application(s) that perform database access, you may not be able to use more than one thread per process. The Microsoft ODBC drivers that use the Jet engine are not currently thread-safe: they will not run properly if a process has more than one thread. This includes ODBC drivers for Access, dbase, FoxPro, Paradox, Excel, and text. The INTERSOLV drivers are threadsafe. To make sure that an ODBC driver is thread-safe, check with the driver supplier. Furthermore, older revisions of database client libraries from some of the database vendors are not thread-safe, so check the database vendor to ensure that you have recent, thread-safe database client libraries for your operating system platform. If you can t configure multi-threading, you can still configure multiple Application Server processes and should be able to configure and tune the system for good performance, though additional memory may be required as processes have more memory overhead than threads. What controls the number of processes and threads? When you configure the Application Server to run a server group s applications, you specify the number of hsserver processes that the Application Server initiates to run the server group s applications. You also specify whether or not multi-threading should be used, and if multithreading is to be used, whether to use a thread per session or to use a thread pool. Using the thread per session option, a separate hsserver thread is created and dedicated to running each application session. Using this option ensures that a request to process a page for a session is never queued waiting for the processing of another session s page to complete on the thread. Alternatively, thread pooling may be configured rather than using the thread per session option. With this model, you configure a fixed number of 129

Chapter 5: Tuning Tips threads in each hsserver process allocated to processing page requests for all application sessions assigned to that process. With this option, multiple application sessions may be assigned to the same thread. This provides some savings in memory utilization because fewer threads are created, but with the disadvantage that queueing may occur when processing concurrent requests for sessions that are assigned to the same processing thread. Note that using thread pooling with one thread configured is the way to turn off multithreading if your application depends on components that are not thread-safe. On a side note, if you use operating system utilities such as the Windows NT Task Manager and examine the number of threads running in an hsserver process, you will observe that the number of threads in use is larger than the number of processing threads that you have configured. This is because the hsserver process creates several special purpose threads in addition to the processing threads we have been discussing that actually run dynamic pages. Most significantly, there is a thread that receives and dispatches requests to run pages to the appropriate processing thread. This I/O thread also writes the resulting HTML page back to the user s browser (via hsrun and the Web server) so that the processing of new page requests can be overlapped with the I/O to write back the current request, even when just a single processing thread is configured. For information on how to configure the Application Server, see Chapter 2, Administering the HAHTsite Application Server. Guidelines for the process/thread configuration Here are some general guidelines for setting the number of Application Server processes and threads: Always configure more than one Application Server process to minimize the impact of a process failing. If your application and ODBC environment is thread-safe: For most applications, a thread pool in the range of 16 to 32 threads per process should provide excellent parallelism without requiring too much memory. Also configure multiple processes so that the total number of threads (the number of processes x the number of threads per process) is as large as the peak number of simultaneous dynamic page requests expected. For example, suppose you expect to support 1,000 concurrent user sessions with a single background server, and expect that at most 256 of the users would be submitting requests to run dynamic pages simultaneously. In this case you could configure 8 processes with 32 threads each for a total of 256 threads. 130

Chapter 5: Tuning Tips Choose the "thread per session" option if your background server machine(s) has a large amount of memory. This guarantees the maximum level of parallelism, but will require more memory when a large number of sessions are active. If your environment is not thread-safe, do not configure multi-threading. In this case, a larger number of processes should be configured. The number of processes should ideally be large enough to handle the number of concurrent dynamic page requests expected. However, be careful not to configure too many Application Server processes, as there is increased memory usage for each Application Server process configured. In addition, if the CPU on your Application Server system is 100% utilized, increasing the number of processes will not improve performance. A good rule of thumb to begin with is to configure 8 to 10 processes for each CPU processor in your server system. For example, you might configure 32 processes on a 4-processor server. However, the ideal number of processes to configure is application-dependent, and may be tuned using the suggestions outlined below. 131

Chapter 5: Tuning Tips Analyzing performance problems If the page response time experienced by your application users is undesirably high, your Application Server may be having performance problems. Page response time can be defined as the amount of time that passes between a user s request for a dynamic page (when they click on a link or button, for example), and the when the page is actually delivered to the browser. This section discusses how you can use the Application Server statistics and log files to determine the cause of any performance problems. The overall response time experienced when a user requests a dynamic page is comprised of three separate values: the page queue time, the page run time, and the communication time. Each of these values is explained below: Value Page queue time Page run time Communication time Description The time that a request to run a dynamic page waits in the Application Server s queue because the Application Server is busy running other dynamic pages. The minimum, maximum, and average for page queue time are reported in the Application Server statistics. The time it takes to actually execute the dynamic page once the Application Server begins to execute it. The minimum, maximum, and average for page run time are reported in the Application Server statistics. The time required to send the request for a dynamic page from the browser to the HAHTsite Application Server process (through the Web server and hsrun), and the time required to return the resulting dynamic page from the Application Server process back to the browser (through hsrun and the Web server). This value is not measured by the Application Server statistics. When the overall user response time is too high, the first step in analyzing the problem is to determine which of the three components, as listed above, is too high. The average page run time and page queue time can be determined by examining the Application Server statistics. If the average total response time can be measured or estimated, the communication time can be determined by subtracting the page run time and page queue time from the total response time. Depending on which of these 132

Chapter 5: Tuning Tips three values appears unusually high, you should further examine the potential causes of delays, as outlined below. High communication time If the average communication time is significant (more than one second), investigate the following: The network bandwidth may not be sufficient for the network traffic, thereby causing delays. This can be checked with network analysis tools. There may be some delay occurring at the Web server. If you are using the CGI version of hsrun, you may want to consider using the NSAPI, ISAPI, or Oracle WRB API versions of hsrun (if you are using a Web server that supports one of these APIs). Also, if the Web server DNS Lookup is enabled, the Web server may be performing a reverse DNS lookup for each dynamic page request. If so, consider disabling DNS lookups in your Web server, or at least caching DNS lookup results. High page queue time If the average or maximum page queue time is significant (more than 0.1 seconds), check to see if there is some contention for Application Server processes. If the average page run time is also high, reducing the average page run time (discussed below) should reduce the average page queue time. If the average page queue time is still significant, increasing the number of Application Server processes or threads configured should help. High page run time If the average or maximum page run time is longer than desired, identify which dynamic pages in the HAHTsite application have long run times by searching the Application Server log files for warnings. The entry for a page with a long run time will look something like this: 16 Feb 1998 00:54:43 Warning: Run time for page HS_MyDynamicPage greater than 5 seconds (Run Time: 9.563 CPU Time:9.333 StateId: TBKExYQ8f- MivoFAZXI3gdzsLx) To locate these warnings, search for the string, Warning: Run time for page. Look at the values for Run Time and CPU Time in these entries. The CPU time is a portion of the run time. If the CPU time is the majority of the run time, this dynamic page, or the subroutines or services it calls (in process OLE 133

Chapter 5: Tuning Tips servers, DLLs, shared libraries, etc.) are doing a lot of work. If the CPU time is excessive, review the page s code to see if it can be optimized. If the CPU time is only a small portion of the run time, the application is spending time waiting on processing that occurs externally to the application process. For example, the application may be waiting for SQL queries to be executed on a remote DBMS server. If this is the case, check to see if the SQL queries can be written in a more optimal way. If none of the analysis steps described above lead to decreased page run times, you may want to increase the processing power of the hardware being used for the Application Server. Improving hardware may mean adding faster processor(s), moving to multiple processors, or using multiple background hosts in a distributed configuration. 134

HAHTsite Application Server Error Messages A Introduction... 136 hsserver error messages... 137 Customizing your hsserver error messages...137 Redirecting a user when an application times out... 138 Returning a static page...138 Automatically redirecting the user... 138 Appending the log file entry to the hsserver error message... 139 hsrun error messages... 142 135

Appendix A: HAHTsite Application Server Error Messages Introduction This appendix describes the error messages that the HAHTsite Application Server displays when an error occurs at runtime. There are two groups of error messages: those produced by the Application Server s hsserver process. those produced by the hsrun program. The following sections describe each group and the configurable options that are available.

hsserver error messages Appendix A: HAHTsite Application Server Error Messages The table on page 140 contains the text for the standard error messages that hsserver sends to the user s browser. By default, hsserver uses the error messages in hsmsgs40.dll (or hsmsgs40.en_us for UNIX) in the Application Server s bin subdirectory. You can, however, customize these error messages and configure hsserver to look in an alternate directory for the customized messages. Customizing your hsserver error messages HTML templates for creating customized error messages are provided with the Application Server. The template files are located in the background host s bin subdirectory. The template file names are listed in the table on page 140 along with the standard error message text. To customize the error messages, you must copy the templates to an error page directory, edit the text, and then configure hsserver to get the messages from the error page directory. Note - Before you customize your hsserver error message, you should be aware that customized error messages apply on a per-server-group basis. In other words, any error messages that you customize for a server group apply for all applications that run on that server group. You should, therefore, exercise caution in customizing error messages. If you are running more than one application on the server group, you should not put application-specific information in the customized error messages. Use this procedure to customize your error messages on each background host. 1 Create a directory for your error messages. 2 Copy the HTML template files from the bin subdirectory of the Application Server s installation directory to the new directory. 3 Use an editor to edit the template files. 4 In the Error Page Directory field in the Administrator utility s Logging Options, type the full path of the directory containing the customized messages. Note - If the Error Page Directory field is blank, hsserver sends back the standard error messages that are in hsmsgs40.dll. 5 Stop and restart your server group. 137

Appendix A: HAHTsite Application Server Error Messages The next time the error message is sent to the user s browser, the customized text is displayed in the browser. Redirecting a user when an application times out If your end users allow an application to time out, they will see an HTML page with an error message, instead of the dynamic page they requested. This may cause your user some confusion as to how they restart the application. Rather than returning the HAHTsite standard error page to a user, you can redirect a user to a new instance of the application. There are two ways to do redirect a user: Return a static page that contains a link to the first page of the application. Automatically redirect the user to the first dynamic page of the application. Returning a static page Replace the standard error page (HS_State.html) with a page that contains a link back to the first dynamic page of the application. For example, your customized error page might contain text similar to the following: This application has timed out due to inactivity. Click here to start the application again. In this example, the word here is defined as a link to the first dynamic page in the application. This is what the HTML would look like: <HTML> <HEAD> <TITLE>Application Timeout Error Page</TITLE> </HEAD> <BODY> <P>This application has timed out due to inactivity. </P> <BR>Click <A HREF="http://www.myserver.com/cgibin/hsrun/webapps/ MyApplication/MyApplication.htx;start=HS_FirstDynamicPage">he re</a>to start the application again.</p> </BODY> </HTML> Automatically redirecting the user Alternatively, you can create a custom error page that automatically redirects a user back to the first dynamic page of an application. To do this, you must

Appendix A: HAHTsite Application Server Error Messages replace the standard error page (HS_State.html) with a custom error page that includes an HTTP header for the redirection. To create the page, use a standard text editor, such as Notepad, and create a file that contains only the following line, followed by a blank line: Location: URL to dynamic page where URL to dynamic page is the full URL to the first dynamic page in the application, for example: http://www.myserver.com/cgi-bin/hsrun/webapps/myapplication/ MyApplication.htx;start=HS_FirstDynamicPage Note - You must include a blank line after the Location: line. If there is no blank line, the Web server will not recognize the text as a complete set of HTTP headers. This will restart the application with a new StateId, and display the first page of the application to the user. In this situation, the user will not see any error message about the application having timed out. You can optionally pass parameters on the URL to the dynamic page, setting a flag is a user has restarted an application after a timeout. You can then use a arequest.geturlfield and an If-Then statement to add an error message to the first page of your dynamic application. For example, to pass parameters on your URL, add a query string, similar to the following example: http://www.myserver.com/cgi-bin/hsrun/webapps/myapplication/ MyApplication.htx;start=HS_FirstDynamicPage?restart=true To test for the restart flag, you would add HAHTtalk Basic or Java (similar to the following example) to the top of your first dynamic page: If arequest.geturlfield("restart") = "true" then Print "The Application has timed out due to inactivity. Please _ login again. <BR>" Appending the log file entry to the hsserver error message The figure below shows the text of the error message that is displayed in the user s browser. The actual system error is written to the hsserver log file. You 139

Appendix A: HAHTsite Application Server Error Messages can append the log file entry to the error message sent to the user s browser. Here is an example of HS_start.html that shows the log file entry appended. Error Message Log File Entry To append the log file entry to the error message: 1 In the Administrator utility s Logging Options, check the Add Error Detail to Error Page box. 2 Stop and restart your server group. The next time the error message is sent to the user s browser, the log file entry is appended. The following table lists in alphabetical order by filename the hsserver error messages. Template Filename Standard Error Message Text Description HS_access.html HS_debug.html The Application Server reports the following: Access Denied The IDE and the Application Server debugger process are unable to communicate, probably because the Application Server process has terminated due to an error. Report this problem to the site Webmaster along with a copy of the URL that caused this message. This message is generated when you attempt to access a dynamic page for which you do not have the required access rights. This message is generated when you are running a remote debug session and the communication link is failing. This causes the debugger to terminate.

Appendix A: HAHTsite Application Server Error Messages Template Filename Standard Error Message Text Description HS_header.html HS_page.html HS_start.html HS_state.html The page generated by the application had invalid HTML format: the HTTP headers were incomplete or there was no content. This usually indicates an error in the application. Report this problem to the site Webmaster along with a copy of the URL that caused this message. The application had a runtime error while processing this page. Report this problem to the site Webmaster along with a copy of the URL that caused this message. The requested application was not found in the Application Root directory. It may have been published to a different directory. If the problem persists, report it to the site Webmaster along with a copy of the URL that caused this message. The requested application has timed out. Please restart the application by browsing to its home page. This message usually means that an application failed at runtime. The page may have appeared to run normally, so identifying the URL that caused the message is important. This message is generated whenever there is a problem while a page is running. These are often application logic errors. This message is generated any time a new application cannot be started or a dynamic page cannot be run. Typical errors are that the file does not exist or is invalid. This message is generated any time there is a problem with the StateId. The most common cause is that the state has expired. 141

Appendix A: HAHTsite Application Server Error Messages hsrun error messages The table below lists, in alphabetical order by filename, the error messages that hsrun produces. You can customize the hsrun error messages, just as you can customize the hsserver messages, by editing the template files provided, by default, in the foreground host s cgibin directory. For hsrun, however, you cannot specify an error page directory for customized messages. When an error occurs, hsrun looks for the appropriate error message in the directory that contains hsrun (your Web server s CGI-BIN directory). If hsrun can open the template files, hsrun sends the error message in the template file to the user s browser. If hsrun cannot open the template file, hsrun uses the standard error message text in hsmsgs40.dll for Windows NT and hsmsgs40.en_us for UNIX. By default, hsmsgs40 is located in the foreground host s CGI-BIN subdirectory. Note - Your customized hsrun error message will apply to all applications run on any Server Group using that CGI-BIN directory. You should, therefore, exercise caution in customizing error messages. If you are running more than one application on a Server Group, or more than one Server Group shares that CGI-BIN directory, you should not put application-specific information in the customized error messages. For hsrun messages, you cannot append the log file entry to the error message. Template Filename HS_comm.html Standard Error Message Text An error occurred communicating with the Application Server, probably because the Application Server process running this application has terminated due to an error. Report this problem to the site Webmaster along with a copy of the URL that cause this message. Description This message is triggered by inter-process communication errors between hsrun and the Application Server. It is most often caused by a server crash while the page is being processed. It is likely to be a transient problem.

Appendix A: HAHTsite Application Server Error Messages Template Filename HS_map.html HS_server.html HS_License.html HS_url.html Standard Error Message Text The image map coordinates were not passed in the format expected by hsrun. If the problem persists, report it to the site Webmaster along with a copy of the URL that caused this message. This application s Server Group is not running. Report this problem to the site Webmaster along with a copy of the URL that caused this message. The Application Server currently has the maximum number of user sessions allowed by the licence agreement. Please try again later. If this error message persists, report this problem to the site Webmaster. The supplied URL is incorrect. If you entered the URL manually, make sure it is correct. If the URL was generated by selecting an item on a previous page, the page may have an error in it. In this case, report this problem to the site Webmaster along with the URL to the previous page and the item you selected. Description hsrun did not send the image map coordinates in the expected format. When hsrun runs as a CGI process, hsrun expects the coordinates to be passed on the command line. When hsrun runs as an ISAPI or NSAPI extension, hsrun expects the coordinates to be passed in the QUERY_STRING. This message is triggered when hsrun cannot connect to the Application Server for the requested server group. The usual cause is that the server is not running. This message is generated when a user attempts to start an application, and there are no concurrent user licenses (state Ids) available. This message is triggered by any problem with the URL syntax or the expected environment variable information from the HTTP server. For links in published applications, this may indicate a problem in the publish phase. 143

Appendix A: HAHTsite Application Server Error Messages

Setting up NSAPI, ISAPI, and the Oracle Cartridge B Introduction... 145 Setting up NSAPI... 146 Setting up ISAPI for IIS 3.0... 149 Setting up ISAPI for IIS 4.0... 149 Setting up the Oracle Web Application Server...153 Configuring the Administrator as an NSAPI, ISAPI, or Oracle application 153 145

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Introduction This appendix describes how to configure the HAHTsite Application Server for use with three Web server application programming interfaces: the Netscape Server Application Program Interface (NSAPI), the Microsoft Internet Server Application Program Interface (ISAPI), and the Oracle Cartridge. The appendix also explains how to configure the Administrator utility to work with NSAPI, ISAPI, and the Oracle cartridge. Note - The procedures in this appendix explain how to configure the Application Server so that it may work with an NSAPI, ISAPI, or Oracle Web server. The site definition that an application is published to must also specify one of these options: otherwise, the application will run as a CGI application. Site definitions are explained in Chapter 4, Working with Sites in the HAHTsite IDE and IP User Guide.

Setting up NSAPI Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Setting up NSAPI is slightly different on Windows NT and UNIX. This section contains a procedure for each setup. Windows NT This procedure assumes that you ve installed the Netscape server and configured its CGI-BIN alias. Note - You must use a forward slash (/) in the filename strings. 1 Go to the Netscape server s config subdirectory. For example, if the Netscape server software is in c:\programs\netscape\server and the default server is https-httpd-80, you would go to c:\programs\netscape\server\https-httpd- 80\config. 2 Open obj.conf for editing. 3 Find this line: Init fn="load-types" mime-types="mime.types" 4 After the above line, add the following two lines: Init fn="load-modules" funcs="hsmsgsdummyinit" shlib= _ "drive:/hahtsiteinstalldir/cgibin/hsmsgs40.dll" Init fn="load-modules" funcs="pfx2hsrun,run-hsrun" shlib= _ "drive:/hahtsiteinstalldir/cgibin/hsrunns30.dll" where drive is the drive where you installed the Application Server and HAHTsiteInstallDir is the Application Server s installation directory. Note - If you are running a Netscape version 3.5 or 3.6 Web server, add the above line to your obj.conf file, substituting hsrunns35.dll for hsrunns30.dll. These lines load the messages DLL and the NSAPI DLL version of hsrun. 5 In the section <Object name="default">, find this line: NameTrans fn="pfx2dir" from="/cgi-bin" dir="path_to_cgi" name="cgi" 6 Before the above line, add: NameTrans fn="pfx2hsrun" from="/cgi-bin" dir="drive:/hahtsiteinstalldir/cgibin" name= _ "hsrunns30.dll" hsrun="hsrun.hse" 147

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge where drive is the drive where you installed the Application Server and HAHTsiteInstallDir is the Application Server s installation directory. Note - If you are running a Netscape version 3.5 or 3.6 Web server, add the line as above, substituting hsrunns35.dll for hsrunns30.dll. This line causes hsrun to look for its special signature before looking for general CGI scripts. The Application Server returns not found errors if the NSAPI filter line is placed after the CGI filter line. hsrun translates /cgi-bin/hsrun.hse to the path drive:/hahtsiteinstalldir/cgibin/hsrunns30.dll and sets an internal object type to hsrunns30.dll, which tells the Application Server to perform further processing using the object section of that name. 7 At the end of the file (right after the cgi object section), add a new object section as follows: <Object name="hsrunns30.dll"> ObjectType fn="force-type" type="magnus-internal/hsrunns30.dll" Service fn="run-hsrun" </Object> Note - If you are running a Netscape version 3.5 or 3.6 Web server, add the object section as above, substituting hsrunns35.dll for hsrunns30.dll. This section forces the MIME type to a special internal type that goes with the NSAPI DLL. This section also specifies the service function to process the request. UNIX Note - When you install the Application Server, the UNIX setup script performs the configuration described in this section. The information is provided here as reference. This procedure assumes that you ve installed the Netscape server and configured its CGI-BIN directory. Note - The shared-library extensions differ among UNIX platforms (e.g. on HP, the extension is.sl ). This procedure uses Solaris as an example. 1 Go to the Netscape server s config subdirectory and open obj.conf for editing. 2 In the section that contains the load-modules lines, find this line:

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Init fn="load-types" mime-types="mime.types" After the above line, add the following line: Init fn="load-modules" funcs="hsrun-init,pfx2hsrun,run-hsrun" _ shlib="/hahtsiteinstalldir/cgibin/hsrunns.so" Instead of HAHTsiteInstallDir, type the Application Server s installation directory. This line loads the hsrun NSAPI shared library. 3 In the section that contains the "init" functions, add the following line: Init fn="hsrun-init" hsrun-path="/hahtsiteinstalldir/cgibin" Instead of HAHTsiteInstallDir, type the Application Server s installation directory. This routine initializes the hsrun code and specifies the location of the messages file, which is read as a regular file. 4 In the section <Object name="default">, find this line: NameTrans fn="pfx2dir" from="/cgi-bin" dir="path_to_cgi" _ name="cgi" Before the above line, add: NameTrans fn="pfx2hsrun" from="/cgi-bin" _ dir="/hahtsiteinstalldir/ _ cgibin" name="hsrunns.so" hsrun="hsrun.hse" Instead of HAHTsiteInstallDir, type the Application Server s installation directory. This line causes hsrun to look for its special signature before looking for general CGI scripts. The Application Server returns not found errors if the NSAPI filter line is placed after the CGI filter line. hsrun translates /cgi-bin/hsrun.hse to the path HAHTsiteInstallDir/cgibin/hsrunns.so and sets an internal object type to hsrunns.so, which tells the Application Server to perform further processing using the object section of that name. 5 At the end of the file (right after the cgi object section) add a new object section as follows: <Object name="hsrunns.so"> ObjectType fn="force-type" type="magnus-internal/hsrunns.so" Service fn="run-hsrun" </Object> 149

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge This section forces the MIME type to a special internal type that goes with the Application Server s NSAPI DLL. This section also specifies the service function to process the request.

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Setting up ISAPI for IIS 3.0 This section contains a procedure for setting up ISAPI for use with the Application Server. This procedure assumes that you ve installed your IIS server and configured its CGI-BIN directory (usually the scripts subdirectory under your install directory). Note - IIS 4.0 requires a different procedure for setting up ISAPI. If you are running IIS 4.0, see Setting up ISAPI for IIS 4.0 on page 149. 1 Copy hsrunisa.dll and hsmsgs40.dll and hslib40.dll to the scripts subdirectory. 2 Run regedt32. 3 Select HKEY_LOCAL_MACHINE\System\CurrentControlSet\ Services\W3SVC\Parameters. 4 If the key ScriptMap is not present, use Edit... Add Key to create a new key with the name ScriptMap. 5 Select the ScriptMap key. 6 Use Edit... Add Value to add: A REG_SZ type value whose name is.hse (the filename extension associated with the Application Server s ISAPI extension module) A value that is the full path to hsrunisa.dll, for example, c:\msiis\scripts\hsrunisa.dll 151

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Setting up ISAPI for IIS 4.0 This section contains a procedure for setting up ISAPI on IIS 4.0 for use with the Application Server. This procedure assumes that you ve installed your IIS server and configured its CGI-BIN directory (usually the scripts subdirectory under your install directory). 1 Start the Microsoft Console Manager. From the Windows Start menu, select Windows NT Option Pack > Microsoft Internet Information Server > Internet Service Manager. 2 Right-click on the cgi alias and select Properties. The CGI Properties dialog appears. 3 Click Configuration... The Application Configuration dialog appears.

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge 4 Click Add. The Add/Edit Application Extension Mapping dialog appears. 153

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge 5 Click Browse... The Open dialog appears. 6 Select All Files from the Files of type drop-down list at the bottom of the dialog. 7 Locate the HAHTsiteInstallDir\cgibin directory, and select the file hsrunisa.dll. 8 Click Open. The path to hsrunisa.dll is added to the Executable field in the Add/Edit Application Extension Mapping dialog. 9 Type.hse in the Extension field. 10 Click OK to add the mapping. 11 Click OK in the Application Configuration dialog. 12 Click OK in the Properties dialog. Your CGI alias is now set up to use ISAPI when communicating with the HAHTsite Application Server.

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Setting up the Oracle Web Application Server This procedure assumes you ve installed and have some familiarity with the Oracle Web Application Server (Revision 2.1 or higher). 1 Copy the following files into the ows (Oracle Web Server) lib directory: Windows NT - hsrunora.dll hsmsgs40.dll Solaris - hsrunora.so hsmsgs40.en_us 2 Configure hsrun as a cartridge in the Oracle Web Request Broker. Use the Oracle Web Server Manager to configure hsrun as an Oracle Web Application Server Cartridge. Go to the Web Request Broker Administration page of the Oracle Web Server Manager and create a new Cartridge setting the parameters as follows: Set Application Name to "HSRUNORA" or whatever name you d like. Set the Object Path to the path of the hsrunora.dll (or.so) file as copied in step 1. Set the Entry Point name to "hsrun_entry". Set the Thread Model to "P" for Process. Take the default values for the Min and Max number of Cartridge instances (or customize these values if you would like). 3 Create a virtual path called "/hsrunora" that points to the directory to which you copied the files in Step 1. 4 Use the Web Server Utility (WSUtil) to add an hsrun entry for the Oracle version of hsrun by choosing Oracle Web Request Broker Cartridge for Web Server Type. The Browse URL should not include an alias such as cgibin. 5 Create a site that includes the hsrun configuration added in Step 3, and publish your application to that site. 155

Appendix B: Setting up NSAPI, ISAPI, and the Oracle Cartridge Configuring the Administrator as an NSAPI, ISAPI, or Oracle application By default, the HAHTsite Administrator utility runs as a CGI application. If your site uses an NSAPI, ISAPI, or Oracle Cartridge Web server, you can improve Administrator performance by configuring the Application Server to use the same version of hsrun as other applications. Here s how. (If you have a distributed configuration, perform this procedure on the control host.) 1 Configure the Application Server for an NSAPI, ISAPI, or Oracle Web server as explained previously. 2 Go to the hsadmin subdirectory of your Web server s document tree. 3 Make a backup copy of hsadmin.html. (Should something go wrong, revert to the backup file.) 4 Open hsadmin.html and replace hsrun.exe with either: hsrun.hse (NSAPI or ISAPI) hsrunora (Oracle Cartridge) 5 Save and exit.

Creating Redistributable Applications C Introduction... 158 General procedure... 159 Creating the redistributable application... 160 Delivering the application...162 Creating an installation script... 162 Advanced installation script notes... 164 About the.ini file... 165 157

Appendix C: Creating Redistributable Applications Introduction This appendix describes the procedure for creating redistributable HAHTsite applications. Redistributable means that the applications can be deployed without actually being published from the IDE or IP. This allows you to develop HAHTsite applications and distribute them as shrink-wrapped, or ready-to-run, applications. You do not need to provide the application source (the HAHTsite project), and your customers do not need the HAHTsite IDE or IP to deploy the application. A redistributable application differs from a normal HAHTsite application in several ways. In a redistributable application, much of the site information that is normally stored in the.htx or.hjx file is incomplete. This is because the final site information for a redistributable application is unknown. When someone installs a redistributable HAHTsite application, information about the server machine is collected and stored in an INI file. The Application Server uses this INI file to build URLs and fulfill WebApp property and method requests.

General procedure Appendix C: Creating Redistributable Applications Creating and deploying a redistributable application involves a number of discrete steps. You need to develop the application, make the application redistributable, decide how you will deliver the application, and write an installation program (or a set of instructions for manual installations). The general steps are as follows: 1 Create the project. Build the HAHTsite project as you would any normal HAHTsite application. You should always test the application by publishing it to a normal site. 2 Publish the project to a special site. Once the application is ready, you will publish it to a special site that contains a directive to make the application redistributable. 3 Decide how you will deliver the application. In most cases, you will be distributing the application using some type of media. You must determine your delivery method, and ensure that it includes all necessary files (published dynamic and static pages). 4 Create an installation program (or instructions for manual installations). In order to simplify and expedite application deployment, you can write an installation program that automates the process of installing and configuring the redistributable application on the target machine. This can be accomplished using a simple installation script, or using a product such as InstallShield. Detailed information about each of these steps can be found in the remainder of this Appendix. 159

Appendix C: Creating Redistributable Applications Creating the redistributable application Creating a redistributable application is very similar to creating a normal HAHTsite application: you build the project as you would any other project. Once the application has been thoroughly tested, you can create the redistributable version. To create a redistributable application Note - Steps 2 through 4 are optional steps. You can choose not to use the provided setup form, and have your install program perform the configuration. If you do skip these steps, refer to Advanced installation script notes on page 164. 1 Edit the site s.hst file. Add the following lines to the top of the.hst file for the site you are publishing to: [Advanced] IsRedistributableApp=Y The.hst file can normally be found under your HAHTsite installation directory HAHTsiteInstallDir\sites\Masters\MachineName\SiteName.hst, where MachineName is the name of the host machine, and SiteName is the name of the site. 2 Import the file, ShrinkWrapSetupForm.hbs, into your project. This code page can be found in your HAHTsite installation directory, in the \scripts subdirectory. Note - You can choose not to use the provided setup form, and have your install program perform the configuration. If you prefer to do this, you do not need to import ShrinkWrapSetupForm.hbs, and you should refer to Advanced installation script notes on page 164. 3 Add a new page to the project, and name it HAHTRedistSetup.htm(l). 4 Place the following HAHTtalk Basic statement on the page: call HS_SetupForm Note - If you are using your install program to perform configuration, you can leave this page blank for now. Refer to Advanced installation script notes on page 164 for more information about what this page should do.

Appendix C: Creating Redistributable Applications 5 Add another new page, (BlankDynamic.htm, for this example) to the project. This dynamic page will serve as a known entry point into the application. As soon as the HAHTsite Application Server receives the request for this page, it knows that the application is redistributable and calls the entry point, HS_HAHTRedistSetup. 6 Force the page to be dynamic. With the new page selected in the Project window, select Edit > Properties... The Page Properties dialog appears. 7 Select the Publish tab. 8 Select All -> Dynamic from the Promote drop-down list, and click OK. 9 Publish the project. The application will be published as a redistributable application. This means that, instead of complete URLs, the application will contain place holders. These place holders will be resolved to full URLs when the application is installed on the target server. 161

Appendix C: Creating Redistributable Applications Delivering the application Once a redistributable application has been created, it must be distributed and installed. We recommend that you distribute the application on some sort of media, such as a CD or diskette. In addition to an installation program, the media needs to contain the static and dynamic pages for the redistributable application. Copy the published static pages directory (and its contents) and the dynamic pages directory (and its contents) to the media. Creating an installation script In order to automate the installation process for your application, you should create an installation script or program (using a program like InstallShield, for example). The first thing that the installation program must do is copy the dynamic pages directory (and all of its contents) to the AppRoot directory on the target machine(s). The installation script should prompt the installer to specify the location of the AppRoot directory. Note - If the application is being installed in a distributed application cluster (configuration where there is more than one Application Server servicing requests for dynamic pages), the dynamic pages directory may need to be installed in several places. Next, the setup script should spawn a Web browser on the Application Server machine and open a URL for the blank dynamic page that was created in the HAHTsite project. Alternatively, the installation program can prompt the installer to open the browser and enter the URL manually. The URL needs to point to the blank dynamic page on the server machine, for example: http://jimm.support.haht.com/cgi-bin/hsrun/webapps/project1/ _ Project1.htx;start=HS_BlankDynamic When this URL is opened, the installation procedure is turned over to the HAHTsite Application Server. When the first dynamic page of a redistributable application is executed, the HAHTsite Application Server automatically executes a special entry point called HS_HAHTRedistSetup.htm. This setup process creates an.ini file in the application s UserRoot directory and fixes up all URLs for the application. The source code for this setup program is contained in the ShrinkWrapSetupForm.hbs file that you imported into the HAHTsite project. This file contains a routine called HS_SetupForm.

Appendix C: Creating Redistributable Applications Note - You can use this routine as is, or customize it according to your own needs and preferences. HS_SetupForm presents the installer with the following form in the browser: In order to complete this form, the person who is installing the redistributable application will need to know specific information about the target machine s configuration. You should list this information in your documentation, so the installer can gather the needed information before beginning the installation process. The required information is as follows: 1 Location of static pages to be installed Example: c:\project1\staticpages This path must match the path to the pages, exactly as they were published (according to the site definition). 2 Server s StaticURL (URL to document root directory) Example: http://jimm.support.haht.com/ 3 Server s StaticRoot (DOS path to document root directory) Example: c:\netscape\ns-home\docs 4 Server s DynamicURL (URL to the HS cgi files) Example: http://jimm.support.haht.com/cgi-bin 5 Server s HSRun Extension (.hse for NSAPI- or ISAPI-based processing,.exe for cgi-based processing) 163

Appendix C: Creating Redistributable Applications Example: hsrun.exe The installer must complete the form, using this information. Note - If your site definition includes subsites, the Configuration form will contain a section for each subsite. The installer must provide the information listed above (2-5) for each subsite. When the installer clicks the form s Submit button, the information is sent to the SetupForm routine, which creates the.ini file, copies all static pages from the media to the document root directory, and fixes up all URLs. The browser will return a page that says: Welcome to Application Configuration Congratulations! You have successfully setup this application. The application is now ready to run, and can be accessed using a normal URL. Advanced installation script notes If you chose not to use the provided setup form, your installation script must perform some additional configuration steps. The installation program must: Prompt the user for the information collected by the form (StaticURL, StaticRoot, DynamicURL, and HSRunExtension). Note that this information must be collected for each subsite, as well. Spawn a browser and call the BlankDynamic page (as demonstrated earlier in this section). However, in this case, you must also include on the URL (as part of the query string), the information collected by the install program. For example, the URL should look something like this: http://jimm.support.haht.com/cgi-bin/hsrun/webapps/project1/ _ Project1.htx;start=HS_BlankDynamic?StaticURL= _ http://jimm.support.haht.com&staticroot=c:\netscape\ _ ns-home\server\docs&dynamicurl=http://jimm.support.haht.com_ /cgi-bin&hsrunextension=.exe Process the information that is received in the URL. You will need to customize the HAHTRedistSetup.htm page to do this. This page must do the work of the SetupForm subroutine in the ShrinkWrapSetupForm.hbs page (found in your HAHTsiteInstallDir\scripts directory). You can use this subroutine as a starting point for your custom solution.

About the.ini file Appendix C: Creating Redistributable Applications The INI file will be written to the application s UserRoot directory and named appname.ini, where appname is the name of the HAHTsite project. The.ini file will contain the overriding "AppData" values for the application. The format of the.ini file depends on the number of subsites defined in the application. If subsites have been defined, the file will contain a separate section for each subsite. The first section will be labeled "[default]", and all other sections will be named using the convention, "SubSiteN," where N starts at 1. Each section will contain Key/Value pairs for each of the AppData fields. Following is a sample.ini file: ================================================ Sample <Project1.ini> file ------------------------------------------------ [default] StaticURL=http://jim.support.haht.com/ StaticROOT=c:\netscape\ns-home\docs DynamicURL=http://jim.support.haht.com/cgi-bin HSrunExtension=.exe ================================================ 165

Appendix C: Creating Redistributable Applications

Configuring the Application Server to Use DES Encryption D What is DES?...168 Triple DES and the HAHTsite Application Server... 169 To configure DES encryption...169 167

Appendix D: Configuring the Application Server to Use DES Encryption What is DES? The Data Encryption Standard (DES) is a widely-used method of data encryption using a private key. DES originated at IBM in 1977 and was adopted by the U.S. Department of Defense. DES applies a 56-bit key to each 64-bit block of data, providing 2*56 or 72,057,594,037,900,000 possible keys. DES runs in the following modes: Cipher Block Chaining (CBC) increases security by exclusive ORing the previous 64 bit block with the current 64 bit block. This makes the encrypted value of a block context dependent. "Triple DES" applies three keys in succession. The HAHTsite Application Server uses both of these modes to encrypt requests and responses to run dynamic pages and secure statics page between the hsrun module on the foreground host and the hsserver processes on the background hosts. (This feature does not imply encryption of data being sent back to the browser from the web server which can be achieved using SSL.)

Appendix D: Configuring the Application Server to Use DES Encryption Triple DES and the HAHTsite Application Server HAHT offers a version of the Application Server that supports strong encryption of data returned by the Application Server using "Triple DES." This section describes Triple DES and how to configure this version. Note - Availability of this version of the Application Server is subject to U.S. Commerce Department export regulations. Triple DES encryption is not available with the standard Application Server release. Please contact HAHT Software if you are interested in acquiring the version with Triple DES encryption. To configure DES encryption 1 On ALL foreground and background hosts in your Application Server configuration, run from a DOS command line the command "hsdeskey" (found in the "bin" subdirectory of the Application Server s installation directory). The hsdeskey command will prompt you to enter and confirm a password to be used for generating DES keys. The password must contain at least six characters, and the SAME password must be entered on each foreground and background host. 2 In the Application Server Administrator, for each Server Group to use DES encryption, go to the Runtime Options form, and make sure the checkbox labeled "Encrypt data packets between foreground and background hosts" is checked (see Runtime Options on page 65). 3 Restart the Server Group. 169

Appendix D: Configuring the Application Server to Use DES Encryption

Index A access control form 100 password authentication 101 privilege repository 101 active sessions 90 admin rights 103 assigning 109 assigning write permissions 111 read-only 110 remote debugging 111 removing administrators 110 administering a distributed server group 59 administering the Application Server 58 administrator username 110 administrators removing 110 application root directory 62 Application Server Cluster 7 Cluster Membership Manager 7 applications Java class directory 63 assigning remote debugging access 111 write permissions 111 audit logging definition 81 parameters 82 Auditing 81 auditing options 81 B bandwidth limitations of Web connection 127 C CGI buffered processes 128 embedded 128 piped communication 128 tuning considerations 128 Cluster Membership Manager 7 configuring number of threads and processes 129 cumulative statistics 88 current statistics 85 customizing hsrun error messages 142 D debugging admin rights 111 default application timeout interval property 69 DES 168 configure DES encryption 169 Triple DES 169 directories 59 application Java class directory 63 application root directory 62 error page directory 79 working directory 62 DISTRIBUTED ENVIRONMENT button 40 dynamic pages 3 assembling 5 destination 62 E embedded CGI 128 error messages appending log file entry to 139, 142 displaying customized 79 groups 136, 158 hsrun 142 customizing 142 template filename 142 text 142 hsserver 137, 160 customizing 137 specifying error page directory 137 template filename 140 text 140 error page directory 79 hsrun messages, specifying 142 171

Index F hsserver messages, specifying 137 flush interval parameter 79 FTP parameters 63 G GID, changing Application Server s 122 H HAHTsite Application Server administering 58 configuring runtime options 65 functional overview 3 properties maximum public space 76 publishing to 59 relationship to IDE 3 starting manually (UNIX) 121 stopping manually (UNIX) 121 HAHTsite Application Server Administrator 21 access control form 100 admin rights form 103 auditing options form 81 blocking users 44 Cluster form 40 concurrent administration 43 cumulative statistics form 88 current statistics form 85 directories form 59 DISTRIBUTED ENVIRONMENT 40 exiting 43 getting started 30 history form 89 hsadmin process 119 language options form 75 license information form 112 locking users 44 logging in 31 logging options form 77 main page 32 menu bar 42 on-line help button 43 Refresh button 34 remote administration 30 runtime options form 65 server groups area 32 services form 92 sessions form 90 starting 30 statistics 84 stopping 43 timeout 43, 44 view log files form 96 history 89 hosts adding to server group 36 background 7 constructing performance index 50 control 7 Cluster Membership Manager 7 load balancing 8 performance factor 8 foreground 7 selecting 38 starting and stopping 37 tuning 50 types defined 19 hsadmin starting 119 hsadmsrv 25 hscontrol 25 hsdebug logged messages 97 hsmsg20.dll 137 hspasswd 53 hsradmin 25 hsredir 24 hsrexec 24 responsibilities 24 viewing log files 96 hsrun 23 environment variables, processing 24 error messages 142 customizing 142 template filenames 142 text 142 forms 23 parsing URLs 23 StateIDs acquiring new 23 decoding incoming 23 hsrun error messages customizing 142 hsserver 24, 140 customizing 137 error messages 137 hsrexec responsibilities 24 log files 97 172

Index I setting number of processes 67 setting number of threads 67 template filenames 140 idle timeout property 70 initial working directory 62 L language options form 75 license information form 112 load balancing 8 performance factor 8 log files 96 appending entry to error message 139, 142 client IP address entries 72 general 96 hsrexec 96 hsserver processes 97 log flush interval setting 97 parameters error page directory 79 flush interval 79 log severity level 78 rotation of 79 selecting log files to view 96 viewing last 20 lines 97 log flush interval parameter 79 log severity level 78 logging options 77 Login form 31 M maximum public space property 76 N number of processes 67 number of threads 67 O ODBC drivers 67 P password authentication 101 changing methods 109 changing a user s password 107 file, adding users 106 syntax 108 permissions assigning 109 poll interval property 69 preload applications property 68 privilege repository 101 privileges, access 100 processes configuring number 129 publish destinations, defining 59 publish parameters 59 publishing 59 R Refresh button 34 remote debugging 20 admin rights 111 rotation of log files 79 runtime options 65 default timeout 69 idle timeout 70 invalid parameters message 73 number of processes 67 number of threads 67 poll interval 69 preload applications 68 S security mechanisms check client IP address 72 Server Cluster Cluster Membership Manager 7 server domain name 30 server group 19 administrator name 110 assigning write permissions 111 debugging access 111 hosts 19, 36 log file rotation 79 view logs 96 server groups adding 50 changing directory paths 62 copying 52 creating a 51 deleting 52 maintaining 50 173

Index operations 50 performance tuning 65 selecting 32, 38 starting and stopping 32, 37 services 92 application path 93 application service name 93 configuring a CORBA server application 92 creating 93 deleting 94 editing 94 limit service to host 94 managing 92 starting 94 stopping 94 Session objects StateIDs 26 sessions form 90 SNMP 39 enabling trap generation for your HAHTsite Application Server 40 HAHTsite MIB 39 HAHTSite SNMP Agent 39 starting the Application Server automatically 121 the Application Server manually (UNIX) 121 starting/stopping the Application Server automatically 121 StateIDs purging 26 static pages 3 statistics 84 cumulative 88 current 85 historic 89 stopping/starting the Application Server manually (UNIX) 121 U configuring 129 UID, changing Application Server s 122 User Account Authentication HAHTsite authentication 53 operating-system authentication 53 password file 53 verifying login 53 username of server group administrator 110 password file syntax 108 V view log files 96 W Web server how CGI requests are handled 128 write permissions 111 T thread safe drivers 67 threads configuring number 129 timeout, default application interval 69 timeout, idle 70 transfer parameters 59 FTP parameters 63 tuning bandwidth limitations 127 174