Integrating HP WebQoS with the Apache Web Server

To turn HP WebQoS on and off, use the HPACAdmission Control directive. The default for this directive is "on." For example, to turn admissions off, use the following directive in your configuration file:

HPACAdmission Control off

If WebQoS is disabled (set to off), all sessions are admitted to the web server.When the HP WebQoS is in effect, new sessions are admitted based on system load. You can set a load threshold using the HPACAdmitLoadThreshold directive. The default for this directive is "2.0." For example, to set the load threshold at 1.5, use the following directive in your configuration file:

HPACAdmitLoadThreshold 1.5

To calculate the load threshold

Run top when performance is poor, and when it is acceptable to determine an acceptable load threshold.

A session duration can be set with the HPACSessionDuration directive. The default for this directive is "0." For example to set a session to 3600 seconds, use the following directive in your configuration file:

HPACSessionDuration 3600

The duration of a session is specified in seconds. If the duration is set to 0, the session never expires. If a session exceeds the specified duration, it is ended.

A session can also be terminated if the time interval between two successive requests of a session exceeds a set number of seconds. You can set this time interval with the HPACIdleSessionTimeout directive. The default for this directive is "300" seconds. For example, to set the time interval to 120 seconds, use the following directive in your configuration file:

HPACIdleSessionTimeout 120

	NOTE: Termination of a session means that the next request coming from the same user agent will start a new session. All privileges that the old session might have enjoyed are lost.

If conditions on the web server do not allow servicing new requests, sessions can be redirected or rejected.You turn on redirection indirectly by setting the redirection URL with the HPACRedirectURL directive. For example, to redirect rejected sessions, use the following directive in your configuration file, filling in the appropriate URL:

HPACRedirectURL [http://]host[:port]

	NOTE: A request can be redirected only to a mirror site.

A redirected session can be bounced back to the original server. You can control how many times a session is redirected with the HPACRedirectTTL directive (TTL stands for time-to-live). The default for this directive is “0.” For example, to set the number of times a session is redirected to 1, use the following directive in your configuration file:

HPACRedirectTTL 1 The number set by this directive is the number of redirections a session has been subjected to, beyond the first one. In other words, 0 means the session has been redirected once, 1 means the session has been redirected twice, etc. This number should not exceed 2, to avoid wasting the resources of the server(s) involved. (The default is probably appropriate for most sites.)If a session has to be rejected, the action the HP WebQoS takes depends on the rejection policy in effect. The rejection policy can be reject, rejectpage, or defer. It can be set using the directive HPACRejectionPolicy. The default for this directive is “reject.” For example, to set the rejection policy to "defer," use the following directive in your configuration file:

HPACRejectionPolicy defer

When the reject rejection policy is in effect, the server sends the HTTP_SERVICE_UNAVAILABLE code and associated message to the client. This is the easiest but least informative way to respond to a rejected request. Users may try to reconnect right away, generating extra load on the system.When the rejectpage rejection policy is in effect, the server returns the contents of a page containing a custom, more explanatory response to the client. For instance, the customer whose access has been rejected may be given a reason for the rejection and a suggestion of a more opportune time to return to the site. The extra information is more likely to dissuade users from retrying immediately, without discouraging them from returning to the site in the future.The location of the file holding this custom response is specified with the directive HPACRejectPagePath. For example,

HPACRejectPagePath <file_path>

If the policy is set to rejectpage, but the rejectpage path has not been set (or cannot be accessed), the server response is the same as the reject policy server response.The defer policy is a special case of rejection. The admission of a session rejected under this policy is merely postponed to a future time slot, when the session will automatically gain access to the server. Once a deferred session is admitted, it is handled as a priority session. A countdown web page is returned to the user agent in response to deferred requests which shows how long the user has to wait in line.You can set the rate (per minute) at which deferred sessions are admitted to the server with the HPACDeferredAdmitRate directive. The default for this directive is "10" sessions per minute. For example, to set the rate at which the deferred sessions are admitted to the server to 5 sessions per minute, use the following directive in your configuration file:

HPWebQoSDeferredAdmitRate 5

In the example above, one session will be admitted every 12 seconds. (At this rate, for example, if there are only 5 sessions waiting for admission, they will all gain access during the next minute. If there are 20 sessions waiting for admission, the last 5 sessions will be admitted 4 minutes later than the first 5.)When setting the admission (allocation) rate of deferred sessions, make sure that the system has adequate capacity to handle it. Take into account that some of the deferred sessions may not come back (because the user gave up), and compensate accordingly.Monitoring the % Priority Requests and Last Allocation Delay statistics can help in setting a realistic allocation rate. The first statistic will show the system's load due to priority sessions. Reduce the allocation rate if this number approaches, or is over, 50%. The second statistic shows how long the user of a deferred session had to wait before gaining access to the server.After the initial rejection, the user is prevented from returning to the site for a specified amount of time. If a session is allocated, this is the minimum delay that can be scheduled. You can set this time interval with the directive HPACRejectedExclusionTime. The default is "300" seconds. For example, to specify that the user will have to wait 120 seconds before he can again try to access the site, use the following directive in your configuration file:

HPACRejectedExclusionTime 120

The following is the default contents of the deferral (allocation) page:

Example 5-2 Server Busy

We are sorry our server is busy, and in order to ensure adequate levels of service to our current visitors, we cannot serve you at this time. We have allocated you a position in line and will serve you as soon as we can.

You will automatically enter the site in mm:ss (minutes:seconds).

The page has three parts, which can be set independently. The first part is the title (Server Busy). You can change the title with the HPACDeferralTitle directive. To set the title to "Site Temporarily Unavailable," use the following directive in your configuration file:

HPACDeferralTitle Site Temporarily Unavailable

The second part of the deferral page is an explanatory message, which can be set with the HPACDeferralMessage directive. An informative message is likely to span several lines, in which case you have to escape the newline character on all but the last line. For example,

The third part is the countdown line, which can be set with the HPACDeferralEnterMsg directive. For example:

HPACDeferralEnterMsg Time left:

HP WebQoS admission decisions can be saved to the server's access log, by adding the "%{HPAC}n" format option to the LogFormat directive. For example:

LogFormat %h %l %u %t \%r\ %>s %b %{HPAC}n

The effect of this option is to append one of the words listed below to the log message:

The statistics displayed on the HP WebQoS Statistics web page can be logged to a file. You can turn on statistics logging with the HPACStatsLogging directive. The default for this directive is "off." For example:

HPACStatsLogging on

In addition, you can specify the time interval between log updates with the HPACLogUpdateInterval directive. The default for this directive is "300" seconds. You can specify the log file with the HPACStatsLogfile directive.For example, to specify that the log file apache_home/var/log/stats.hpac is updated every 600 seconds, use the following directives:

HPACLogUpdateInterval 600

HPACStatsLogfile var/log/stats.hpac

The log update interval has to be a multiple of 5 seconds. For example, if you set the interval to 1 second, the update will take place after 5 seconds. If you set the interval to 7 seconds, the update will take place after 10 seconds.If logging is enabled, but the log file has not been specified, the default log file is apache_home/var/log/hpac.log (or apache_home/logs/hpac.log, depending on the layout of apache_home).

	NOTE: The HPACStatsLogging, HPACLogUpdateInterval and HPACStatsLogfile directives set global HP WebQoS parameters, therefore they should be used outside virtual host configuration blocks. They are ignored inside the virtual host configuration blocks.

A log entry consists of a number of comma separated fields, as follows:

07/Oct/1998:19:30:00,virtual.host.com,15,0,0,0,0,0,0,0,181,0,0,0.5,0.00,92

The first field is the update time (GMT) and the second field is the name of the virtual host to which the statistics refer. The table below lists the remaining fields.

To control session admissions, HP WebQoS tracks the session state by including cookies in HTTP responses. For the session tracking mechanism to work properly, server responses can no longer be cached. This, in turn, impacts the performance of the server.You can alleviate the problem by specifically allowing caching of certain mime types, short of allowing a session to be fully served from cached responses. Good candidates for caching are mime types representing objects embedded in an HTML document (for example, images, sounds).To turn on caching, use the HPACMimeCaching directive. The default for the directive is "off." For example, to turn mime caching on, use the following directive in your configuration file:

HPACMimeCaching on

With mime caching on, HP WebQoS allows caching of the following mime types:

You can turn off caching of individual mime types in this list with the directive. For example, assuming that mime caching is on, the following directive turns off caching for the specified mime types:

HPACMimeNocache video/x-mpeg2 audio/x-pn-realaudio

You can add to the default list of mime types that can be cached with the HPACMimeCache directive. For example, if mime caching is on, the following directive adds the specified mime types to the list of mime types that can be cached:

HPACMimeCache image/x-rgb image/x-xpixmap

	NOTE: If the list of mime types passed to the HPACMimeNocache and HPACMimeCache directives is too long to fit on one line, the newline character must be escaped on all but the last line.

The caching commands specified in the configuration file have no effect if a document cannot be cached in the first place (for instance, documents created dynamically).

By default, each virtual host equally shares the system resources. However, this does not guarantee equal use of the resources. Virtual hosts hosting active sites may use more than their fair share of system resources, at the expense of other virtual hosts. A more equitable use of system resources can be achieved using one of the techniques described below.

You can influence the access of virtual servers to system resources by using different load thresholds for the virtual hosts. For instance, you could set the load threshold lower for virtual hosts that have a tendency to use most of the system resources. Conversely, you can set the load threshold higher, or even turn off HP WebQoS, for virtual hosts that have little impact on the system resources.You can use the HPACShareUnits directive to give more weight to some of the virtual hosts. The default for this directive is "1." For example, to give more weight to some of the virtual hosts, use the following directive in your configuration file:

HPACShareUnits 2 To understand the effect of this command, assume that you have three virtual hosts, A, B and C: A is assigned one share of system resources, B is assigned two shares and C is assigned three shares. (There are a total of six shares.) This amounts to assigning 17% of system resources to A
(1 / 6 * 1), 33% to B (1 / 6 * 2) and 50% to C (1 / 6 * 3).

The assigned share of system resources is used to compute the actual priority threshold for each virtual host from the server-wide priority threshold. You can set the value for the server-wide priority threshold with HPACAdmitPriorityThreshold. The default for this directive is "0.9.". For example, to set the server-wide priority threshold to .75, use the following directive in your configuration file:

HPACAdmitPriorityThreshold 0.75

The setting above will allow up to 75% of all sessions to be priority sessions. Beyond this threshold, even priority sessions are rejected. The value set with directive is used to compute the priority threshold for individual hosts, taking into account the assigned share (see HPACShareUnits above).The assigned share is also used to give priority to under-represented virtual hosts, when virtual host isolation is in effect. Virtual host isolation is turned on with the HPACVHostIsolation directive. The default for this directive is "off." For example, to turn on virtual host isolation, use the following directive in your configuration file:

HPWebQoSVHostIsolation on

With this option in effect, HP WebQoS raises the priority of new sessions for those virtual hosts that contribute less than their assigned share to the system load.

Most HP WebQoS configuration directives set values for parameters that affect individual virtual hosts. A few of them set values for parameters that affect all virtual hosts. These directives are:

The directives setting global HP WebQoS parameters should be used outside virtual host configuration blocks. Inside virtual host configuration blocks, the directives are ignored and the parameters they try to set revert to default values.