Administrator's Guide
CHAPTER 8
The Novell exteNd Application Server provides Web server integration (WSI) modules that allow you to integrate the application server within your existing Web server framework. This chapter includes these topics:
The WSI modules are provided as an enhancement to the Novell exteNd Application Server. The WSI modules are not included when you install the Novell exteNd Application Server from the product CD. If you want to use the WSI modules, you must obtain them from the Novell developer Web site at: developer.novell.com/ndk/wsi.htm. Install and configure them as instructed.
For NetWare users The Apache WSI is automatically installed and configured during NetWare installation. The NetWare installation generates a configuration file called AgWSI.conf that includes a basic Apache WSI setup; Apache's httpd.conf file references the AgWSI.conf file. So you do not need to download the WSI modules from the developer Web site.
A WSI module extends the URL namespace of your existing Web server directory structure by forwarding requests for a specific URL (or set of URLs) to an application server that services the requests. It works like this:
When a WSI module receives a request for a specified URL, it opens an HTTP connection to an application server and forwards the request to it.
The application server services the request and returns the response to the WSI.
There is no direct communication between the browser and the application server; all calls pass through the WSI. To improve response time, you can configure the WSI to pool connections to the application server.
The following five examples show how a WSI might be used in a corporate network.
In the first four examples, the WSI module forwards a client request for the URL http://www.ABC.com/daytime/schedule.html to http://sssw.ABC.com/daytime/schedule.html (the URL address of the client does not change).
The final example shows a configuration where different client requests are forwarded to different application servers.
Example 1: Web server with one application server In this simple scenario, the WSI module forwards requests from a Web server to a single application server:
NOTE: There are many ways to set up your environment. In each of the following four examples, for example, you could position your database behind the inner firewall. Positioning the corporate database outside the DMZ helps protect your database.
Example 2: Web server with clustered application servers Here the WSI module forwards requests from a single Web server to a cluster of application servers (this approach increases database access and reduces the risk of the application server becoming a single point of failure):
Example 3: Multiple Web servers and application servers Here multiple WSI modules are configured to forward requests to multiple application servers. This approach is more reliable for handling a large volume of requests:
Example 4: Hardware dispatcher for load balancing Here again multiple WSIs forward requests from multiple Web servers to multiple application servers. Now the largest volume of requests can be more reliably processed—because of multiple servers at the front and back ends and the use of dispatcher load balancing at both ends:
Example 5: Web server with multiple application servers Here a WSI module is set up with multiple configurations, allowing requests to be routed to different application servers depending on the incoming URL. Requests for abc.com are directed to serv1.myco.com, and requests for xyz.com are directed to serv2.myco.com. For more information, see Directing requests to multiple application servers.
Before you install, configure, and enable the WSI modules, note that:
The WSI will not work with application servers configured to require client certificates for authentication.
The WSI module cannot forward a client certificate from the browser to the application server. Because the WSI opens a new HTTPS connection to the application server, the WSI would need to access the private key of the client certificate to use the client certificate for this connection. However, the private key is not available—because it is securely stored by the browser on the client machine. Since the WSI cannot send client certificates to the application server, the WSI will not work with an application server configured to require client certificates for authentication.
The WSI module must be installed on the same machine as the Web server.
For clustered application servers, the WSI requires a third-party hardware dispatcher to securely redirect requests to application servers through one port in the firewall.
Since the application server's software Dispatcher (SilverDispatcher) load-balances server clusters by redirecting URLs ( instead of masking them), the WSI modules supplied with the application server do not work with SilverDispatcher.
The WSI configuration file (AgWSI.conf) must be in the same directory as the WSI module, since the WSI reads the configuration file when the Web server starts.
To run WSI modules and maintain separate log files for both IIS and iPlanet, you should create separate directories to store the WSI DLL and the shared library file with an associated AgWSI.conf file.
If you are not running both IIS and iPlanet WSI modules on the same machine, you do not need to create separate directories.
You can run the application server remotely—you do not need to run the application server from the Web server machine.
The download of the WSI modules from the Novell developer Web site includes readme files that describe how to create a basic WSI configuration.
For NetWare users For NetWare users, the Apache WSI is installed, configured, and enabled using a set of default directives.
This section describes how you can customize the default configurations by adding other directives to the WSI configuration files. It includes information on:
To configure and enable the Apache WSI module, you add a set of directives to the Apache server's httpd.conf file, or add the directives to a separate configuration file that the httpd.conf file includes. The directives you choose determine how the WSI functions: what URLs it processes; what application server (and port) processes the URL; and whether the WSI uses connection pools, SSL, and so on.
For NetWare users If NetWare users want to use the installed settings, no action is needed. For information about other directives, see Appendix D, "WSI Directives Reference".
Add an Apache LocationMatch directive, specifying the URL you want managed by the WSI. It should look something like this:
<LocationMatch /Root_URL_to_Forward>
where /Root_URL_to_Forward is the URL you want the WSI to forward to the application server.
To forward all URLs to the application server, specify:
<LocationMatch />
Within the LocationMatch element (on the next line), add the Apache SetHandler directive and specify wsi-handler—for example:
<LocationMatch /myURL> SetHandler wsi-handler
Specify the WSI's type of connection to the application server—pooled or nonpooled.
For more information, see Connection pooling for the Apache WSI.
The WSI module allows you to direct different client requests to different application servers:
To direct different client requests to different application servers for the Apache WSI, you define multiple LocationMatch sections. Each LocationMatch section contains the directives that define the requests and the application server to which they are redirected. For example:
<LocationMatch URL1> WSIHost host1 WSIPort port1 </LocationMatch> <LocationMatch URL2> WSIHost host2 WSIPort port2 </LocationMatch>
Here all URLs beginning with URL1 will be directed to host1:port1, and all URLs beginning with URL2 will be directed to host2:port2.
To direct different client requests to different application servers for the IIS or iPlanet WSI, you define multiple sections in an AgWSI.conf file. Each configuration section is labeled with a SECTION statement and contains the statements that specify which requests are redirected to which application server. Each section must contain all statements listed as required in AgWSI.conf file reference.
In addition, your Web server might be multihoming—hosting more than one host name. Using the WSI.host statement, you can configure the WSI to forward requests based on the request's host name (and optionally port). If a section does not have a WSI.host statement, the request host header is ignored and only URL matching is used as a filter. For more information, see WSIHost.
For each incoming request to the Web server, the WSI searches all the configuration sections until it finds a match based on the host name and port in the request header (if specified by WSI.host) and the URL of the request. The request is then forwarded to the application server specified in that section.
Sample configuration file directing to different application servers The following shows a configuration file with three sections that specify two different Web server host names and direct requests to two different application servers. The sample also shows how to configure the WSI so that specified URLs can be accessed only through a secure (HTTPS) connection:
SECTION=WWW_ABC_COM# Redirect all URLs for www.abc.com to serv1.myco.com # HTTP requests will be forwarded to port 80 on the application server # HTTPS requests will be forwarded to port 443 on the application server WSI.host=www.abc.com WSI.root.dir=/AgISAPI SilverServer.host=serv1.myco.com SilverServer.http.port=80 SilverServer.https.port=443 SilverServer.urls=/ Connection.http.max=100 Connection.https.max=100 Connection.idle.time=25SECTION=WWW_XYZ_COM_SECURE# Redirect URLs starting with /db1/approot/secure # for www.xyz.com to serv2.myco.com # only from HTTPS (secure port) (SilverServer.http.port is set to 0) WSI.host=www.xyz.com WSI.root.dir=/AgISAPI SilverServer.host=serv2.myco.com SilverServer.http.port=0 SilverServer.https.port=443 SilverServer.urls=/db1/approot/secure Connection.http.max=100 Connection.https.max=100 Connection.idle.time=25SECTION=WWW_XYZ_COM_HTTP# Redirect all other URLs for www.xyz.com # to serv2.myco.com on any port WSI.host=www.xyz.com WSI.root.dir=/AgISAPI SilverServer.host=serv2.myco.com SilverServer.http.port=80 SilverServer.https.port=443 SilverServer.urls=/ Connection.http.max=100 Connection.https.max=100 Connection.idle.time=25
The WSI modules use connection pooling to improve response time. Instead of creating and maintaining a connection to the application server for each client connected to the Web server, the WSI reuses its connections to the application server for multiple client connections. The WSI will open new connections to the application server as needed for concurrent request processing. This section includes these topics:
In a basic Apache WSI configuration using nonpooled connections, the WSI creates a new connection for each request, runs the request, then disconnects from the server. You'll specify the application server host (WSIHost) and the application server port directives (WSIPort for HTTP requests or WSISslPort for HTTPS requests). A nonpooled connection LocationMatch directive would look like this:
<LocationMatch /myApp> SetHandler wsi-handler WSIHost alaska WSIPort 10080 WSISslPort 10043 </LocationMatch>
When you define a connection pool, the WSI gets a connection from the connection pool for each request, runs the request, then returns the connection to the pool. The WSI saves the overhead of creating and closing connections.
To define a connection pool, you specify the connection pool attributes using a WSIConnPool container element—then within the LocationMatch directive, you specify the name of the connection pool (WSIConnPool).
First you need to create a WSIConnPool container (directly before the corresponding LocationMatch container). Here's an example:
<WSIConnPool cp01> WSIHost alaska WSIPort 10080 WSISslPort 10443 WSIMaxConns 100 WSIMaxSslConn 50 </WSIConnPool> <LocationMatch /SilverStream40> SetHandler wsi-handler WSIConnPool cp01 </LocationMatch>
You can specify an idle timeout for the connections in the connection pool using the WSIIdleTimeout directive. If not specified, the idle timeout is set to 10 minutes. The WSI checks for idle connections at intervals specified by the WSICleanupInterval directive. These directives are per connection pool and have default values if not specified.
The IIS and iPlanet WSI modules maintain separate connection pools for HTTP and HTTPS protocols. To ensure that these connection pools do not use up too many system resources, the WSI periodically scans the pools and closes any connection that has not been used between scan cycles.
Connections have the following states:
|
State |
Description |
|---|---|
|
Connected |
Connection is busy and active |
|
Inactive |
Connected but time limit has not expired |
|
Idle |
Not active and idle limit has expired |
|
Not connected |
— |
The WSI periodically runs a background thread to check the connection pools for inactive and idle connections to see which connections are connected but not busy. The WSI thread marks all inactive threads as idle and closes any connections that are already marked as idle. When a connection is marked as idle, that connection is closed based on the connection idle time limit you set (or the default of 25 minutes). The interval starts when the WSI module is loaded, not when the connection was created.
A connection needs to remain inactive for two scan cycles before it is disconnected. For example, if the specified connection idle time limit is set to 15 minutes, an inactive connection will be disconnected sometime between 15 and 30 minutes after becoming inactive (because the WSI may not start pooling until the middle of an existing interval). If an idle connection is used during the time interval between the scan cycles, the connection goes back into the connection pool marked as inactive.
Specifying connection pooling values You can specify the connection pooling values using three directives in the AgWSI.conf file: Connection.http.max, Connection.https.max, and Connection.idle.time.
Because of variations in server platforms, architecture, and third-party security providers, you may need to be aware of certain security considerations when using the WSI:
If you secure your Web site using the Microsoft Windows NT LAN Manager (NTLM) authentication, the WSI default header settings will not work. After authenticating incoming requests, IIS adds an NTLM HTTP authentication header to each request. Because the NTLM HTTP authentication header is not supported by the application server, incoming requests will be rejected unless you configure the WSI module for IIS in one of the following ways:
Replace all authentication headers with the ones set by the AgWSIUser utility.
Remove the NTLM HTTP authentication headers from all requests sent to the application server. Setting WSI.auth.NTLM.remove in the AgWSI.conf file to true allows users' requests to be successfully forwarded to the application server once NTLM headers are removed. For more information, see WSI.auth.NTLM.remove.
AgWSIUser is a command-line utility that generates the WSI.auth.user statement that is needed in AgWSI.conf to define a WSI user and password. The AgWSIUser utility encrypts the user name and password in a form the WSI can read.
For more information, see WSI.auth.user.
AgWSIUser username password
If your password is blank, just enter the user name. You can enter any valid user. The AgWSIUser utility prints the corresponding WSI.auth.user statement in the command window.
Paste the generated statement into the appropriate section of the AgWSI.conf file. (If you are not using sections, paste it anywhere in the file.)
At startup, the WSI module will decrypt the user name and password and generate an HTTP authentication header that it will add to every request it forwards to the application server.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...