Serving WebObjects
To a large extent, WebObjects needs little attention once it is installed. However, there are certain basic administrative tasks that you’ll need to know, such as how to install applications and start them up. In addition, you’ll probably be concerned about your site’s performance somewhere along the line, and you’ll need to know how to determine an application’s response times and what you can do to improve the response times.
This document contains information that a WebObjects system administrator needs to know. It begins by providing essential background information on WebObjects HTTP adaptors and how they are used to start WebObjects applications. Then it describes how to perform one-time setup of an application called Monitor, which you use to perform many of the necessary administrative tasks. After you read these first two sections, you can learn what the basic administrative tasks are and how to perform them.
Table of Contents
WebObjects HTTP Adaptors
Configuration Files
Adaptor Modes
Installed HTTP Adaptors
Setting Up the Monitor Application
Starting Up Monitor
Initial Monitor Setup
Administrative Tasks
Installing Applications
Starting WebObjects Applications
Monitoring Application Activity
Performance Testing
Improving Performance
Periodically Shutting Down the Application
Load Balancing
Increasing the Listen Queue Depth
Installing and Configuring NSAPI Adaptors
Installing and Configuring the ISAPI Adaptor
Starting Up Multiple Monitor Instances
Related Topics
Other WebObjects documents might be of interest to system administrators:
•Installation Guide: Includes system requirements, compatibility information, and location of the WebObjects Home Page. (The
3
Serving WebObjects
Installation Guide is printed and included with the WebObjects CD-ROM or can be downloaded from NeXTanswers; it is not online).
•Post-Installation Instructions: Describes how to verify the installation and troubleshoot if WebObjects applications do not run.
WebObjects HTTP Adaptors
A key part of WebObjects administration is dealing with adaptors. This section provides a little background material on what a WebObjects HTTP adaptor is, how it works, and how you can configure it to suit your needs.
A WebObjects HTTP adaptor (called WebObjects adaptor or sometimes HTTP adaptor) routes client requests processed by an HTTP server to WebObjects applications and returns the response to the server, which sends it back to the client. WebObjects makes available several adaptors, of which only one can be active with a particular server at a time. Every transaction with a WebObjects application uses the currently active adaptor.
However, the relationships between adaptor and application are (potentially) many-to-many. Multiple instances of the same WebObjects application can run on the same machine or a variety of machines and communicate with the same adaptor. In addition, multiple HTTP servers can be running on the same machine or on different machines; each server can have its own adaptor, each with its own constellation of application instances. Although there can be only one active HTTP adaptor per HTTP server, an application can concurrently communicate with other types of adaptors, such as an adaptor that uses Distributed Objects or a secure-socket adaptor.
There are two general types of HTTP adaptors:
•The CGI adaptor, an executable file named WebObjects or WebObjects.exe which resides in the host HTTP server's “cgi-bin” directory. This adaptor is available on all supported platforms. It is generic in that it works with any HTTP server conforming to the Common Gateway Interface (CGI).
•API-based adaptors, that is, adaptors based on APIs specific to particular web server. Three NSAPI adaptors, all based on the Netscape Server API (2.0, 2.0.1, and 3.0), are available on all supported platforms except Mach. A WebObjects adaptor based on Microsoft’s Internet Information Server API (ISAPI) is also supported. The API-based adaptors have a performance advantage over CGI adaptors in that the associated server can dynamically
4
WebObjects HTTP Adaptors
load the adaptor; servers using CGI adaptors, on the other hand, spawn a new adaptor process for each request and kill the process after the response is provided.
When WebObjects is installed, the CGI adaptor is made active by default. To use an API-based adaptor, you must specifically activate it. Activating the API-based adaptor deactivates the CGI adaptor for a particular server. See “Installing and Configuring NSAPI Adaptors” and “Installing and Configuring the ISAPI Adaptor” for further details.
Configuration Files
WebObjects HTTP adaptors use configuration files to locate WebObjects application processes. There are two types of configuration files: public and private.
•The public configuration file is
NeXT_ROOT/NextLibrary/WOAdaptors/Configuration/WebObjects.conf. (NeXT_ROOT is defined at system installation time.) This file tells the adaptor what applications are (or should be) running and allows the adaptor to balance transactions among different instances of the same application. You create the public configuration file using the Monitor application as described in the section “Initial Monitor Setup” in this guide.
In general, you want one public configuration file per site. That means if you have multiple machines running WebObjects, you should access all WebObjects applications through a single machine that is running the HTTP server and that contains the public configuration file.
If you have multiple HTTP servers running on a single machine, they all share the public configuration file. If you want each server to have its own configuration file, you can install one WebObjects.conf file in each server’s configuration directory.
•A private configuration file is also named WebObjects.conf and is located in the temporary directory of the system (/tmp for Mach, Solaris, and HPUX platforms or the directory specified by the TEMP environment variable on the Windows NT platform). If the WebObjects adaptor cannot find the public configuration file or if it cannot find the requested WebObjects application in the public configuration file, it searches the private configuration file.
A new private configuration file is created automatically any time a WebObjects application is started and a private configuration file doesn’t exist. The adaptor contacts only one instance of an application
5
Serving WebObjects
in the private configuration file; if you manually start HelloWorld and it’s already been started, the entry for HelloWorld in the file is overwritten. (The old process will continue to run, but cannot be contacted.) The adaptor also cannot contact a remote instance of an application using the private configuration file.
The contents of the private configuration file are essentially the same as those of the public configuration file, except that the contents are stored as C structures and so cannot be directly modified. This file should only be modified by the WebObjects adaptor itself.
Adaptor Modes
All WebObjects adaptors route incoming requests to WebObjects applications in one of three modes:
1.Load-balancing between concurrent instances of the same application specified in the public configuration file
2.Choosing an application from the private configuration file
3.Autostarting an application
The active adaptor tries to contact the requested application by going through the modes in the preceding order.
Load Balancing: When the client request tries to contact an application, the active WebObjects adaptor first checks the public configuration file for an application matching the specification in the URL. Load balancing typically occurs only for the first request of a session if the application stores state in the server.
Afterwards, the application resolves the URL so that page navigation will always occur in the context of the same application. But if the application stores state on the page or in cookies, true load balancing will be performed for each request.
Private Configuration File: If the adaptor cannot find a public configuration file, it attempts to resolve the URL against entries in the private configuration file. If the adaptor finds a matching entry but cannot contact it (for example, the application has been stopped), the adaptor deletes the “dangling” entry from the private configuration file and autostarts the application.
Autostarting: If there is no public configuration file and the adaptor fails to find an application matching the client’s request in the private configuration file, it tries to start the application itself. The adaptor first searches in specific locations in the document root of the HTTP server and then in NeXT_ROOT/NextLibrary/WOApps for a WebObjects application (one with a .woa extension) that matches the specification in the request URL. If it finds one, it invokes the WODefaultApp
6
WebObjects HTTP Adaptors
executable, or if the application is compiled, it invokes the executable in the application wrapper itself. This invocation starts the application on the HTTP server machine and registers it in the private configuration file, thereby allowing the adaptor to contact the new application instance. If the adaptor cannot find the requested application (for example, there’s a typo in the URL), it returns a list of the applications it can find.
Note that if the public configuration file
NeXT_ROOT/NextLibrary/WOAdaptors/Configuration/WebObjects.conf exists, no applications are ever autostarted. Also note that adding applications to the Monitor as described in the section “Initial Monitor Setup” creates the public configuration file. Thus, if you are using the Monitor application, autostarting is disabled.
Installed HTTP Adaptors
When WebObjects is installed, the following adaptors are put in NeXT_ROOT/NextLibrary/WOAdaptors along with source code. Note that only the CGI adaptor is installed on Mach, since neither Netscape’s nor Microsoft’s servers have been ported to this platform. Also, no ISAPI binary file is installed on Solaris or HP-UX platforms (only source code).
The following table summarizes the adaptors provided with WebObjects.
|
Server |
NextLibrary Location |
Executable |
CGI |
many |
WOAdaptors/CGI |
WebObjects[.exe] |
|
|
|
|
NSAPI2 |
Netscape 2.0 |
WOAdaptors/NSAPI/2.0 |
WebObjects-NSAPI.dll |
|
FastTrack (httpd) |
|
or |
|
Enterprise (https) |
|
WebObjects-NSAPI.so |
|
|
|
|
NSAPI2.0.1 |
Netscape 2.0.1 |
WOAdaptors/NSAPI/2.0.1 |
WebObjects-NSAPI.dll |
|
FastTrack (httpd) |
|
or |
|
Enterprise (https) |
|
WebObjects-NSAPI.so |
|
|
|
|
NSAPI3 |
Netscape 3.0 |
WOAdaptors/NSAPI/2.0 |
WebObjects-NSAPI.dll |
|
FastTrack (httpd) |
|
or |
|
Enterprise (https) |
|
WebObjects-NSAPI.so |
|
|
|
|
ISAPI |
Microsoft Internet |
WOAdaptors/ISAPI |
WebObjects-ISAPI.dll |
|
Information Server |
|
|
|
IIS 1.0 |
|
|
|
IIS 2.0 (NT Server 4.0) |
|
|
|
IIS 3.0 (NT Server 4.0) |
|
|
|
Peer Web (NT WS 4.0) |
|
|
|
|
|
|
7
Serving WebObjects
Setting Up the Monitor Application
You can perform many essential administrative tasks using a WebObjects application named Monitor. Monitor helps you create a public configuration file, start and stop applications, perform load balancing, and set up applications for optimal performance. Before you can use Monitor, you need to perform some initial setup. After that, you can use it to easily administer your own WebObjects applications.
Note: Previous versions of WebObjects distributed Monitor as an example application. To use Monitor, you had to recompile your applications using a special version of WOApplication. This WOApplication class is incompatible with the Monitor application distributed in WebObjects 3.5. If you want to be able to Monitor these existing applications, you’ll have to recompile them on WebObjects 3.5.
Starting Up Monitor
To start up Monitor on Windows NT, choose Monitor from the WebObjects program group in the Start menu.
To start up Monitor on any other system, do the following:
1.Open a command shell window.
2.Enter these commands:
>cd /NextLibrary/WOApps/Monitor.woa
>Monitor
The Monitor application launches in your default web browser and displays this screen:
8
Setting Up the Monitor Application
Which Copy of Monitor Should I Use?
If you have multiple machines running WebObjects, you can administer them all from a single instance of Monitor on a single machine. It’s recommended that you use the copy of Monitor that’s installed on the same machine as your HTTP server and WebObjects adaptor. This is because the main purpose of the Monitor is to maintain the public configuration file (WebObjects.conf), which the WebObjects adaptor uses to find running instances of WebObjects applications. The best way to achieve sharing of the WebObjects.conf file is to have your HTTP server and Monitor run on the same machine. The alternative—having Monitor on a separate machine— would require that the two machines share a file system through network access.
Monitor can communicate with WebObjects applications running on remote hosts; however to launch applications on remote hosts it uses a lightweight daemon named MonitorProxy. For example, the following figure shows a WebObjects site spread across four machines. One machine contains the HTTP server, and the other three machines contain WebObjects applications. You would run the Monitor application on the machine containing the HTTP server. That Monitor application would use the MonitorProxy daemons on the other three machines to launch applications. All other communication goes directly between Monitor and the WebObjects application.
9
Serving WebObjects
Starting Up MonitorProxy
As mentioned in the previous section, if you have a multiple machine configuration, you need to run Monitor on one machine and run MonitorProxy daemons on the other machines. You can start up MonitorProxy daemons the same way you start up Monitor:
To start up MonitorProxy on Windows NT, do the following:
1.Navigate to the directory NeXT_ROOT/NextLibrary/WOApps/Monitor.woa in the Explorer.
2.Double-click MonitorProxy.exe.
To start up MonitorProxy on any other system, do the following:
1.Open a command shell window.
2.Enter these commands:
>cd $NEXT_ROOT/NextLibrary/WOApps/Monitor.woa
>MonitorProxy
You probably want to set up your system so that MonitorProxy starts up at system boot time.
Note: If you’re running Monitor on a Solaris or HP-UX machine, you must start up MonitorProxy on that machine as well. As you’ll learn later, Monitor requires the local MonitorProxy to start up applications on Solaris and HP-UX.
10
Setting Up the Monitor Application
Initial Monitor Setup
In normal operation, when you start up Monitor, all of the WebObjects applications on your site are displayed under the Declared Apps heading, and the right frame shows information about the application you select. (Or if you set it up properly, you’ll see a login panel and after you log in you’ll see all of your WebObjects applications.) However, the first time you’ve started the Monitor, no applications are displayed. You need to configure the Monitor for use on your site.
Click here to configure the
Monitor application.
To configure the Monitor application, do the following:
1.Click the Options button.
The right frame shows configuration information.
2.Look at the first section of the Configuration options. They should look like this:
Make sure each option has the appropriate setting as described below:
11
Serving WebObjects
Local host name
The name of the server Monitor is running on.
Admin user name
Protects the Monitor from being used by all users except the one specified here. If you enter a user name in this field and that user’s password in the “Admin password” and “Admin password again” fields, Monitor runs in a protected mode. When you restart Monitor, it displays a login page instead of the typical first page.
Admin password
If you entered an administrator name, enter the administrator account’s password here.
Admin password again
Repeat the administrator password here.
The second set of options affects the configuration file. Make sure each option has the appropriate setting as described below:
Primary WebObjects.conf path
The location of the public configuration file. Most of the time, this should be set to NeXT_ROOT/NextLibrary/WOAdaptors/Configuration. (You only need to change this if you move the configuration file.)
Additional public paths
If you have more than one server and each server has its own public configuration file, click the Add Path button and specify the location of the other configuration file(s). Servers can share the configuration file in
NeXT_ROOT/NextLibrary/WOAdaptors/Configuration, so usually this setting is not necessary.
Dedicated Monitor WebObjects.conf path
The location of a configuration file used only by Monitor. This file is used only if you want to start multiple instances of Monitor, which is rare. See “Starting Up Multiple Monitor Instances.”
The third set of options displays default setting for each application that you’ll add to the Monitor. Make sure each option has the appropriate setting as described below:
12
Setting Up the Monitor Application
WebObjects executable name
The executable that you want to use as the default executable for all applications you add to Monitor. By default, this is set to WODefaultApp or WODefaultApp.exe.
Path to executable
The path to the executable name you specified in the field above.
Application cycling
Default settings for the periodic shutdown of applications. For more information, see “Periodically Shutting Down the Application” in this guide.
The fourth set of options you rarely have to change. They are used to build the WebObjects application URLs that you use when you click an application’s hyperlink to access one of its running instances.
HTTP server host
The host name of your HTTP server.
Adaptor key
The name of your WebObjects adaptor. Usually, this is WebObjects or WebObjects.exe. If you use the NSAPI adaptor or ISAPI adaptor, you may have to change the name here.
Protocol name
Should normally be set to http.
3.Click the Save Changes button at the bottom of the page to record your changes.
4.In the Main Menu area, click the Add button.
13
Loading...