3.4 Configuring an External Web Server
You may wish to use an external Web server with HydraExpress. This section discusses how to configure the external Web server Apache.
3.4.1 Configuring the HydraExpress AJP 1.3 Connector
HydraExpress ships with a connector that accepts requests from an Apache Web server. This connector is configured in rwagent.xml located in your installdir\conf directory, with a default port 8009. Here is a relevant excerpt from that file:
<rwsf:connector name="AJP 1.3" class="rwsf_transport_ajp1335.createAjp13ConnectorImp" handlerChain="http"> <rwsf:property name="accepter-threads" value="2"/> <!--1--> <rwsf:property name="thread-pool-min" value="5"/> <!--2--> <rwsf:property name="thread-pool-max" value="10"/> <!--3--> <rwsf:property name="host" value="localhost"/> <!--4--> <rwsf:property name="port" value="8009"/> <rwsf:property name="request-backlog" value="5"/> <rwsf:property name="request-buffersize" value="4096"/> <rwsf:property name="request-timeout" value="30000"/> </rwsf:connector>
| //1 | Specifies the number of threads that should be spawned listening for new connections. Defaults to 2. |
| //2 | The minimum number of threads to be created in the thread pool. Defaults to 5. |
| //3 | The maximum number of threads to be created in the thread pool, in this case 20. Defaults to 10. |
| //4 | The host property defines servers from which messages will be accepted; in this case, localhost only. |
You may customize this configuration to complement your Apache Web server configuration.
3.4.2 Configuring the Apache Web Server
The Agent uses Web server plug-ins provided by the Apache Software Foundation to communicate with an Apache Web server. These plug-ins read the worker.properties file to configure the connections that the Web server makes to the servlet execution engine. This chapter documents the syntax of the worker.properties file and presents sample configurations for common scenarios.
The worker.properties file configures workers. A worker represents the concept of a connection to a servlet execution engine. A worker often corresponds to an actual on-the-wire connection, but it may also be an intermediary between the Web server and other workers. For example, the load-balancing worker described in Section 3.4.2.3 is a connector that balances requests among a number of other workers.
Each configuration line has the format property=value. For example, the line below sets the port number for a worker named container1 to port 8007:
worker.container1.port=8007
The Web server ignores blank lines and lines that begin with the # character.
3.4.2.1 Setting the Worker Type
HydraExpress supports the following worker types:
An ajp13 worker communicates with a servlet execution engine over the AJP13 protocol. This is the recommended protocol for communicating with a servlet execution engine. Section 3.4.2.2 describes ajp13 workers.
An lb worker load balances requests to other workers. Section 3.4.2.3 describes lb workers.
To set the type of a worker, use the syntax worker.name.type=<workertype>. For example, the line below declares the worker with the name container1 to be of type ajp13:
worker.container1.type=ajp13
3.4.2.2 Configuring AJP13 Workers
An ajp13 worker represents an AJP13 connection to a servlet execution engine. Each ajp13 worker has two required properties and two optional properties.
An ajp13 worker must be configured with the properties in Table 4:
Table 4: Required properties for an ajp13 worker
| Property | Description |
host | Name of the server that runs the servlet execution engine |
port | Port number of the servlet execution engine |
An ajp13 worker may be configured with the properties in Table 5:
Table 5: Optional properties for an ajp13 worker
| Property | Description |
lbfactor | Assigned weight for load balancing (see Section 3.4.2.3) |
cachesize | Number of socket connections the Web server opens to the servlet execution engine. (If this property is not explicitly set, the server opens one connection.) Typically, this number should be equal to the number of threads specified in the server.xml file for the servlet execution engine. |
For example, the configuration lines below set an ajp13 worker named container1 to connect to port 8009 on the local machine:
worker.container1.host=localhost worker.container1.port=8009
3.4.2.3 Configuring Load Balancing Workers
An lb worker distributes requests across any number of other workers. The lb worker maintains a weighted list of the workers available for a request. The Web server sends requests to the lb worker, and the lb worker balances those requests among the workers in the list. The lb worker also provides basic fault-tolerance. Should one of the servlet execution engines go offline, the lb worker no longer forwards requests to the worker that corresponds to the offline servlet execution engine.
Each of the workers that the lb worker manages must have an lbfactor property greater than zero to receive requests.
An lb worker requires a single parameter, balanced_workers, that names the workers that the lb worker balances.
The sample below defines two ajp13 workers on different hosts and an lb worker that balances requests between the two ajp13 workers:
worker.loadbalancer.type=lb worker.loadbalancer.balanced_workers=container1, container2 worker.container1.type=ajp13 worker.container1.host=localhost worker.container1.port=8009 worker.container1.lbfactor=1 worker.container2.type=ajp13 worker.container2.host=bigiron.example.com worker.container2.port=8009 worker.container2.lbfactor=9
In this example, the primary server is container2 which has a greater capacity for handling requests than container1. For every 10 requests to loadbalancer, container2 receives 9 requests and container1 receives 1 request.
3.4.2.4 Declaring Workers to the Web Server
The worker.list property declares the names of workers that are available to the Web server. The property holds the names of the workers as a comma-separated list. For example, the line below declares three workers:
worker.list=worker1, worker2
Only one worker.list may appear in the file. All workers that the Web server uses directly must be in the worker.list. Note that workers that are managed by an lb worker should not be included in the worker.list.
3.4.2.5 Sample Configuration for Load Balancing
This section shows a sample configuration that uses load balancing to balance connections across three hosts. Two of the hosts have the same capacity to serve requests. The third host is able to serve twice as many requests as either of the first two hosts. The sample below shows the worker.properties file for the Web server.
# # Simple configuration file for load balancing. # # Define only the lb worker in the worker.list. The Web server # should not communicate directly with the workers that the # lb worker manages. worker.list=loadbalancer # Define the first container. worker.host1.type=ajp13 worker.host1.host=www1.example.com worker.host1.port=8009 worker.host1.lbfactor=1 worker.host1.cachesize=20 # Define the second container. worker.host2.type=ajp13 worker.host2.host=www2.example.com worker.host2.port=8009 worker.host2.lbfactor=1 worker.host2.cachesize=20 # Define the third container. worker.host3.type=ajp13 worker.host3.host=www3.example.com worker.host3.port=8009 worker.host3.lbfactor=2 worker.host3.cachesize=40 # Define the load balancing worker. worker.loadbalancer.type=lb worker.loadbalancer.balanced_workers=host1,host2,host3
The hosts at www1.example.com and www2.example.com use the same rwagent.xml file. The file defines an AJP13 connector with 20 threads for use by the Web server. The file also defines an AJP13 connector reserved for Agent shutdown requests, as shown below:
<rwsf:agent>
...
<rwsf:connector
name="AJP 1.3"
class="rwsf_transport_ajp1335.createAjp13ConnectorImp"
handlerChain="http">
<rwsf:property name="accepter-threads" value="2"/>
<rwsf:property name="thread-pool-min" value="5"/>
<rwsf:property name="thread-pool-max" value="20"/> <!-- 1 -->
<rwsf:property name="port" value="8009"/>
<rwsf:property name="request-backlog" value="5"/>
<rwsf:property name="request-buffersize" value="4096"/>
<rwsf:property name="request-timeout" value="30000"/>
</rwsf:connector>
...
</rwsf:agent>
| //1 | Note that the maximum number of threads to be created in the thread pool is 20. The default is 10. |
The host at www3.example.com uses a rwagent.xml file that specifies 40 threads for the public connector, as shown below:
<rwsf:agent>
...
<rwsf:connector
name="AJP 1.3"
class="rwsf_transport_ajp1335.createAjp13ConnectorImp"
handlerChain="http">
<rwsf:property name="accepter-threads" value="2"/>
<rwsf:property name="thread-pool-min" value="5"/>
<rwsf:property name="thread-pool-max" value="40"/>
<rwsf:property name="port" value="8009"/>
<rwsf:property name="request-backlog" value="5"/>
<rwsf:property name="request-buffersize" value="4096"/>
<rwsf:property name="request-timeout" value="30000"/>
</rwsf:connector>
...
</rwsf:agent>
The Web server configuration maps the servlet requests directly to the loadbalancer worker. On an Apache HTTP server, the servlet.conf file contains the following line:
JkMount /servlets/* loadbalancer
For IIS, the uriworkermap.properties file contains the line:
/servlets/*=loadbalancer
©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.