Administrator's Guide
APPENDIX D
This appendix includes two sections:
AgWSI.conf file reference (for IIS and iPlanet configurations)
This section describes each configuration setting, specifies which settings are required, and provides defaults and examples. Settings can apply at these levels:
Description
Required. Per directory setting. Must be placed in a LocationMatch directive container.
Notifies Apache that the WSI module will handle any URL that matches the LocationMatch directive.
Example
SetHandler wsi-handler
Description
Optional. Per connection pool setting. Must be placed in the WSIConnPool container.
Defines the time interval (in seconds) that the WSI module will look for idle connections in the connection pool. Connections that have been idle longer than the idle timeout value are disconnected.
Default
300 seconds (5 minutes)
Description
Optional. Per directory setting.
A container directive whose contents define a named connection pool. The default named connection pool name is cp01. You can define multiple connection pools in the same httpd.conf file.
Example
<WSIConnPool cp01> . . . </WSIConnPool>
Description
Required for creating a connection pool. Must be in a LocationMatch container if not using a connection pool.
Specifies the hostname or IP address on which the application server is running.
This directive is ignored if a connection pool is already defined (using the WSIConnPool directive) for the same LocationMatch directive container.
Default
localhost
Example
WSIHost alaska.novell.com
Description
Optional. Per connection pool setting.
Specifies the maximum idle time (in seconds) for SSL and non-SSL connections to the application server.
Default
600 seconds (10 minutes)
Example
WSIIdleTimout 450
Description
Optional. Per connection pool setting.
Specifies the maximum number of non-SSL connections for the connection pool.
Default
20
Example
WSIMaxConns 35
Description
Optional. Per connection pool setting.
The maximum number of SSL connections for the connection pool.
Default
20
Example
WSIMaxSslConns 35
Description
Required if defining a connection pool. Per directory if connection pooling is not specified.
Specifies the application server's HTTP port. This directive is ignored if a connection pool is already defined (using the WSIConnPool directive) for the same LocationMatch directive container.
Default
80
Example
WSIPort 10800
Description
Required if defining a connection pool. Per directory if connection pooling is not specified.
Specifies the application server's HTTPS port. This directive is ignored if a connection pool is already defined (using the WSIConnPool directive) for the same LocationMatch directive container.
Default
443
Example
WSISslPort 10443
Description
Optional. Server-wide setting.
Specifies the level of tracing for the WSI module. Higher values produce more detailed trace information. The WSI module can generate a lot of trace information when set at the higher debug levels. In general, do not set the trace level higher than 3 unless there is a specific reason for doing so. Valid settings are:
Default
3
Data type
Integer
Example
WSITraceLevel 6
Description
Optional. Server-wide setting.
Determines how the WSI module writes trace information to the trace output files. The valid values are:
|
Value |
Description |
|---|---|
|
per-process |
Each Apache process has its own WSI trace output file created in the WSITraceOutputDirectory .with the name agapache.pxxxx.out (where xxxxx is the process ID). |
|
per-request |
A new WSI trace output file is created for each request processed by the WSI module. The output files are created in the WSITraceOutputDirectory with the name "agapache.pxxxxx.ryyyyy.out" (where xxxxx is the process ID and yyyyy is the request number). IMPORTANT: This setting was created for internal debugging purposes only, and should not be used in a production system. |
Default
per process
Example
WSITraceMode per-process
Description
Optional. Server-wide setting.
Specifies the maximum width of modules or function names in WSI trace events.
Default
16
Example
WSITraceModuleWidth 20
Description
Optional. Server-wide setting.
Specifies the file system directory where the WSI module creates trace files.
If specified, it must correspond to an existing directory with write permissions granted to the Apache process.
Default
|
Operating system |
Default |
|---|---|
|
NetWare |
sys:/tmp |
|
UNIX |
/tmp |
|
Windows |
c:\temp |
Description
Optional. Server-wide setting.
Specifies the formatting of the trace event names listed in the WSI trace.
Values are on or off. When set to on, module or function names shown in the WSI trace events are space-padded. This formatting makes trace files easier to read (but larger), because the trace records will line up on the same column.
Default
on
Description
Optional. Server-wide setting.
Values are on or off. When set to on, WSI trace events include timestamps.
Default
on
Description
Optional. Server-wide setting.
Specifies the time interval (in seconds) between iterations of the connection pool watcher facility. The watcher prints information about the connection pool to the trace files located in the WSITraceOutputDirectory.
When 0 is specified, the watcher thread is disabled.
Default
0
Description
Optional. Per directory setting.
Specifies a relative URL that is substituted for the URL fragment specified in the LocationMatch directive.
Example
For example, given the following directives:
<LocationMatch /foo> SetHandler wsi-handler WSIUrl /bar </LocationMatch>
A request for an URL of the form http://foo/whatever_follows will be handled by the WSI module as http://bar/whatever_follows.
If this directive is not specified, the URL substitution is not performed.
This section describes each configuration setting, specifying which settings are required and providing defaults and examples.
Description
Optional.
Connection.http.max is the maximum number of concurrent nonsecure HTTP connections between the WSI and the application server.
Usage
If you have created and specified a WSI.error.url file, users will be notified if the connection pooling limit is exceeded. The WSI reuses socket connections between itself and the application server.
Default
Connection.http.max=100
Description
Optional.
Connection.https.max is the maximum number of concurrent secure HTTPS connections between the WSI and the application server.
Usage
If you have created and specified a WSI.error.url file, users will be notified if the connection pooling limit is exceeded. The WSI reuses socket connections between itself and the application server.
Default
Connection.https.max=100
Description
Optional.
Connection.idle.time specifies how often (in minutes) the WSI scans the connection pools for idle connections.
Default
Connection.idle.time=25
Description
Optional.
SECTION names a configuration section. Each section contains the statements that specify the handling of a set of Web requests by an application server. If you want the Web server to direct different requests to different application servers, use multiple sections in the configuration file.
Usage
Each section must define all required settings. If an optional setting is not defined in a section, it will be given the default value (not the value defined in any other section).
Format
SECTION=label
For the label, enter something informative.
Examples
SECTION=abc_com SECTION=xyz_com
For more info
For more information about the use of configuration sections, see Directing requests to multiple application servers.
Description
Required.
SilverServer.host is the name of the destination application server that services URL requests from the Web server.
Example
SilverServer.host=mysssw.myco.com
Description
Required if the application server HTTP port is not using the default port number for your operating system.
SilverServer.http.port specifies the nonsecure port of the destination application server. Use the value zero (0) to specify that the WSI should not forward any requests coming in on the nonsecure port.
Default
SilverServer.http.port=80
Description
Required if the application server HTTPS port is not using the default port number (443).
SilverServer.https.port specifies the secure port of the destination application server. Use the value zero (0) to specify that the WSI should not forward any requests coming in on the secure port.
Default
SilverServer.https.port=443
Description
Required.
SilverServer.urls specifies which URLs will be forwarded to the application server. You must specify a new setting for each URL root you want forwarded to the application server.
Formats
There are two formats: Simple URL forwarding and URL forwarding with translation (masking).
Syntax:
SilverServer.urls=<Root_URL_to_Forward>
Examples:
SilverServer.urls=/myco SilverServer.urls=/myDb
In the preceding examples, all URLs that begin with either /myco or /myDb will be forwarded to the application server. This includes:
http://myWebServer/myco/Sessions http://myWebServer/myco/Pages http://myWebServer/myDb/myco/Pages/MyPage.html
To forward all URLs to the application server, specify the following:
SilverServer.urls=/
URL forwarding with translation (masking)
Syntax:
SilverServer.urls=<URL_root_at_Web_server>=<translated_URL_root>
Example:
SilverServer.urls=/Pages=/myDb/myco/Pages
The first URL will be forwarded to the application server after the second URL is substituted for it. In this example, all URLs from the Web server that begin with /Pages will be forwarded to the application server with /myDb/myco/Pages substituted for /Pages. The URL sent to the Web server as:
http://myWebServer/Pages/MyPage.html
is forwarded to the application server as:
http://mySilverServer/myDb/myco/Pages/MyPage.html
Description
Optional.
When a request sent to the Web server contains an HTTP authorization header, the WSI will send an HTTP header (called x-agwsi-Authorization) to the application server that echoes the value of the header when WSI.auth.echo is set to true.
This setting allows the application to retrieve the user login information when the user login has been masked with the WSI.auth.user command. For example, when a third-party product is performing authentication and authorization services, the WSI.auth.echo setting allows the application to retrieve the name of the user who logged in to the application and initiated the request.
Format
The HTTP header will appear in the following (name/value) format:
x-agwsi-Authorization: Basic Base64EncodedUserName/Password
Default
WSI.auth.echo=false
Usage
The application server uses the AgiHttpServletRequest API to retrieve the authorization header.
Description
Optional. Used with IIS only.
Set WSI.auth.NTLM.remove to true if NT authentication is enabled for your IIS directories. Setting the value to true removes the NTLM authentication headers so users' requests can be successfully forwarded to the application server. For more information, see Using IIS NTLM authentication with the WSI module.
Default
WSI.auth.NTLM.remove=false
Description
Optional.
When WSI.auth.user is specified, the WSI module intercepts the authentication headers that will be forwarded to the application server and replaces them with the credentials of a single known user. Then it adds HTTP authentication headers to every request it forwards to the application server. Any existing authentication headers on incoming requests to WSI are replaced by the authentication setting.
Usage
To protect the security of the authentication settings, the user name and password are not stored in clear text in the AgWSI.conf file. You must run the AgWSIUser utility to generate the WSI.auth.user statement needed in AgWSI.conf to represent a given user and password. The AgWSIUser utility encrypts the user name and password in a form the WSI can read.
The authentication setting can be used to:
Description
Optional.
WSI.debug specifies the WSI logging level. The WSI logs to the AgWSI.log file, which is stored in your WSI module directory.
Usage
Choose from these levels:
To log the URLs arriving at the destination server, use the SMC to configure your application server debug value to 1 or 2. For more information, see Low-level debugging.
Default
WSI.debug=0
Description
Optional.
WSI.error.url specifies a customized error page users will see if a WSI connection error occurs. If you do not create and specify a WSI error URL, users will see a generic browser notification when the WSI module cannot connect to the application server.
Usage
It is a good idea to create an HTML file that tells users about the problem and advises them to retry the URL connection later.
Specify the WSI error file name and its location on your Web server. You need to put your error page file in your Web server's directory structure, since the WSI redirects the browser to this page on your Web server.
Default
WSI.error.url=\myerror.html
Description
Optional.
WSI.host specifies the HTTP host header to filter when matching URLs to be forwarded to an application server. If this statement is not specified, the request host header is ignored and only URL matching is used as a filter.
Usage
This setting is used for multihomed Web server configurations, where the Web server is hosting multiple separate host names and the WSI needs to forward URLs to different application servers based on the request host name. The WSI.host setting can specify either the hostname alone or the hostname and the port number. If the port number is not specified, the WSI will accept any port number on the request's host header provided the host names match.
Examples
WSI.host=www.abc.com WSI.host=www.abc.com:8080
For more info
For a sample use of this statement, see Directing requests to multiple application servers.
Description
Required for IIS only.
WSI.root.dir is the WSI virtual directory the WSI module runs from. Since the WSI for IIS is both a filter and an extension, you need to specify the URL for the WSI in the IIS Web root (/wwwroot) directory structure.
Usage
You need to install the WSI module for IIS in a directory that is visible from the IIS Web root directory. If you install the WSI in a physical directory below the Web root, the WSI is automatically visible from within IIS. But if you install the WSI module in a directory that is outside the IIS root directory, you must create a virtual directory using the MMC so the WSI appears in the IIS directory.
You must set WSI.root.dir relative to the Web server root directory.
Examples
If you are installing the WSI into C:\Inetpub\wwwroot\agisapi (a physical directory beneath the Web root), specify WSI.root.dir=/agisapi.
If you are installing the WSI into a virtual directory such as C:\WSI, use the MMC to create a virtual directory such as /agisapi that maps to C:\WSI and then specify WSI.root.dir=/agisapi.
Default
WSI.root.dir=/agisapi
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...