Introduction

The Intershop Commerce Management Web Adapter (WA) is a Web application that distributes client requests from public Web servers to the Intershop Commerce Management application servers, and implements a specialized HTTP proxy cache for application server responses. The Web Adapter is implemented as a plug-in for the Apache HTTP Server.

Glossary

References

You should be familiar with the main concepts of the Intershop Commerce Management infrastructure. Refer to Overview - Infrastructure, Scaling and Performance.

Web Adapter Configuration Files

The Web Adapter is configured using two different configuration files:

• A global webadapter.properties file
  This file is located in <IS.INSTANCE.SHARE>/system/config/cluster/. It is used to provide global configuration information which applies to all Web Adapters in a cluster. The Web Adapter accesses this file through an HTTP call to a configuration servlet. Information on available configuration servlets is obtained from the local webadapter.properties file.

• A local webadapter.properties file
  Each Web Adapter has a local webadapter.properties file, located in <IS.INSTANCE.LOCAL>/webadapter/. This file can be used to overload any parameter setting from the global Web Adapter configuration file, for example to set individual logging or tuning parameter values. In addition, the local webadapter.properties file contains information on available configuration servlets.

The location of the local webadapter.properties file can be customized. To specify a custom location, modify the WebAdapterProperties directive within the httpd.conf file (Windows: <IS.INSTANCE.LOCAL>/httpd/conf/,Linux: /etc/opt/intershop/eserver#/httpd/conf/) of the Web Server. Changes to the property files are effective immediately without the need for a restart of the application server or the web server.

Configuration Servlets

Central WA configuration data, such as timeout settings, servlet names and dynamic registration information about available server groups (see Server Group Definition), sites and application servers, is provided by configuration servlets. Every application server runs a configuration servlet. In order to query the required information, the Web Adapter periodically performs HTTP calls to an available configuration servlet.

The local webadapter.properties file in <IS.INSTANCE.LOCAL>/webadapter/ must list all configuration servlets in the cluster. The Web Adapter cannot process requests without at least one responsive configuration servlet and a valid property file. Contact with one configuration servlet is sufficient because every configuration servlet is capable of providing the necessary configuration data about the entire cluster. Fail-over functionality, however, is only available if the local webadapter.properties file lists all the configuration servlets available in the cluster. If one configuration servlet fails, the Web Adapter tries all other configuration servlets to find a responsive configuration servlet.

The cs.url.<n> properties in the webadapter.properties file specify the access URLs of each application server's configuration servlet, for example:

cs.url.0=http://<host1>:10054/servlet/ConfigurationServlet
cs.url.1=http://<host2>:10054/servlet/ConfigurationServlet

or

cs.url.0=http://<host1>:10054/servlet/ConfigurationServlet
cs.url.1=http://<host1>:10064/servlet/ConfigurationServlet

Web Adapter Logging Options

In the local webadapter.properties file you can set the path and specify the file name of the Web Adapter's request log and error log. Logging behavior can be controlled using the central or the local webadapter.properties file.

Request Log

The request log contains information

• about incoming client requests
• about requests issued by the Web Adapter

Request Log Configuration

The content of the request log can be processed by other tools. The log directory can be configured via the local webadapter.properties file. The installation default is

#requestlog.dir=/<IS.INSTANCE.LOCAL>/webadapter/log

If you want to supply a different path, change the setting as needed and remove the # character to enable this property.

For efficiency, the log entries are not written separately with each request. Instead, they are buffered in memory until a configurable size or interval is exceeded. The default settings are:

requestlog.enabled = true
requestlog.buffersize = 500000
requestlog.flushinterval = 10
requestlog.switchinterval = 86400

where buffersize defines the size (in bytes) of the memory where log entries are buffered before they are written to disk, and flushinterval specifies the time (in seconds) between flushes of the buffer to disk. The property switchinterval specifies the interval (in seconds) when a new log file is created.

In addition, the following properties are available to control the request log behavior, in particular, to reduce the log file size:

Request Log Content

The statistical information contained in request log files is arranged in columns, separated by the character '|'. Each request entry terminates with the character '\n'. The column separator character '|' is replaced by '%7C' if it occurs in the logged data.

All request log lines produced by a single client request (nested <wainclude> requests, the client request itself and business events) are written in an uninterrupted sequence of lines. They cannot be mixed line-by-line with other requests or split by log rotation.

The following table describes the columns in detail:

Request Log Upload Settings

The request log upload behavior is controlled by the Web Adapter Agent. The corresponding settings are stored in the Web Adapter Agent section of the global webadater.properties file.

The following properties are available:

Error Log

The error log will be written by the Web Adapter to indicate error situations. The name of this file is configurable in the local webadapter.properties file. The default is

#errorlog.file=/<IS.INSTANCE.LOCAL>/webadapter/log/webadapter.log

If you want to supply a different path, change the setting as needed and remove the # character to enable this property.

In addition, errorlog.file can be configured with strftime() conversion specifiers for time-based rotation, like .../webadapter-%Y-%m-%d.log.

The overall log level is configured using the property errorlog.level. The value can be one of OFF, FATAL, ERROR, WARN, INFO, VERBOSE or DEBUG. The default value is

#errorlog.level = INFO

Runtime Log Level Configuration

Besides overriding a log level configuration in the global webadapter.properties file with a configuration in a local webadapter.properties file, it is also possible to override the setting of errorlog.level with specific settings for individual log scopes. This makes it possible, for example, to obtain detailed log messages for certain functional domains of the Web Adapter, without having to deal with the same log detail for other domains which are of less interest for a certain purpose.

For example, with settings as below, log messages of level ERROR are recorded for configuration service messages, and messages of level VERBOSE to trace external HTTP traffic. For all other domains, log messages of level INFO are included with the error log file.

errorlog.level=INFO
errorlog.level.config=ERROR
errorlog.level.httpexternal=VERBOSE

The following log scopes are available:

Log Entry Structure

Each entry in the error log file consists of a single line with the following basic format:

<date> <time> (<hostname>) [<process-id>/<thread-id>/request-id]<log level> <text>\n

Note that the process-id and thread-id entries may differ according to the environment. These entries provide a unique identifier for a request handler within the machine. For the multi-processed Apache Web server, it is actually a combination of parent-process-id/process-id; multi-threaded servers use process-id/thread-id.

The request-id is assigned to every incoming request. It is also used in the Web Adapter request log and in the application server error log.

Internal Logfiles

pagecache-<date>.log

The Web Adapter process writes the pagecache-<date>.log file if the keyword or page indexing for the site is enabled. The Web Adapter agent process reads the entries (operation write_time fileLocation) and indexes the corresponding files. This index is used for cache clear operations (by keyword or content).

Web Adapter Error Pages

The Web Adapter stores several public pages which are returned in case of general errors, e.g., to indicate URL errors or system overload. By default, error pages are stored in <IS.INSTANCE.LOCAL>/webadapter/public. Using the property errorpage.dir of the local webadapter.properties file, it is possible to store error pages in a different location.

Intershop Commerce Management supports site-specific error pages. To this end, the Web Adapter looks up error pages in the following sequence until it finds a valid page:

(1) <errorpage.dir>/<site>/<page>

(2) <errorpage.dir>/<hostname>/<page>

(3) <errorpage.dir>/<ip>/<page>

(4) <errorpage.dir>/<page>

where

• <errorpage.dir>
  is the error page base directory as configured in the property errorpage.dir of the local webadapter.properties file

• <site>
  is the Intershop Commerce Management site name of the request
  Note that in some cases, the Web Adapter does not know the site name, e.g., in short URL requests.

• <hostname>
  is the host name taken from the Host HTTP request header or – as a fallback – from the HTTP server configuration (with Apache, ServerName)

• <ip>
  is the resolved IPv4 address of the host

• <page>
  is majorerror.html, overload.html, or url_error.html, depending on the error condition.

Intershop recommends to create error pages in <errorpage.dir>/<site> with absolute path references to this site in the ISML templates, e.g.,

<img src="/waroot/<site>/site_error_image.gif">

Symbolic links from <host>/<ip> to <site> can be used to provide the correct error pages in case the site context is unknown but a dedicated host name exists.

Web Adapter Statistics

In order to facilitate monitoring of activity within an Intershop Commerce Management cluster, the Web Adapter tracks statistical data and sends these data to a configurable pipeline in regular intervals.

With the default implementation, the Web Adapter statistics are sent to the pipeline WebadapterStatistics-Push, which is part of the monitor cartridge. It is possible to configure a different pipeline, in order to implement custom monitoring solutions.

The default pipeline (WebadapterStatistics-Push) writes the statistical data to a log file in the Intershop Shared Files. The log file content is optimized for easy parsing.

Web Adapter Statistics Log

If not otherwise specified, the Web Adapter statistics is written into Intershop Commerce Management's default log directory <IS.INSTANCE.SHARE>/system/log. The log file names correspond to the following pattern:

<IS.INSTANCE.SHARE>/system/log/wastatistics-<instance-ID>-<date>.log

for example,

/eserver1/share/system/log/wastatistics-10.0.20.1-2010-03-25.log

Configuring the Statistics Log

To configure the Web Adapter statistics log, adjust the following properties:

Global Web Adapter Properties File

In the global webadapter.properties, specify

• monitor.pathinfo
  Configures the pipeline to which the statistics data will be sent. The default configuration is:

  monitor.pathinfo = /BOS/SMC/-/-/-/WebadapterStatistics-Push

• monitor.pushinterval
  Configures the time (in seconds) between transmissions of statistics data from the Web Adapter to the application server. The default value 0 disables the transmission of statistics data.

  monitor.pushinterval = 0

• monitor.propertyInterval
  Configures the time (in seconds) between transmissions of the full set of Web Adapter properties to the application server. Additional transmissions (pushes) within this interval do not contain these properties. The default value is 600. If set to 0, the properties are sent only in case the Web Adapter properties have changed.

  monitor.propertyInterval = 600

Local Web Adapter Properties File

In the local Web Adapter properties file <IS.INSTANCE.LOCAL>/webadapter/webadapter.properties, specify the Web Adapter instance (<IS.WA.INSTANCE.ID>), for example:

monitor.instance.id = WA0

Setting this property allows to overwrite the value of <IS.WA.INSTANCE.ID> that is sent within the statistics data. This may be necessary, for example, to distinguish different Web servers that share the same IP address.

Pipelet Properties of StatisticsWriterPipelet

Specify the following properties for the StatisticsWriterPipelet in the pipeline WebadapterStatistics:

• LogDirectory
  Defines the directory where the log file will be stored. Make sure that the specified directory exists. Default:

  LogDirectory = <IS.INSTANCE.SHARE>/system/log

• DatePattern
  Defines the file name and the rollover of the log file. DatePattern must match a pattern as defined in java.text.SimpleDateFormat. Default:

  DatePattern = yyyy-MM-dd

Monitoring System Information

Intershop 7's Web Adapter provides a means of monitoring system information via HTTP calls. This section explains the basics of the so-called wastatistics and wastatus monitors.

About wastatistics Monitor

The motivation behind wastatistics is to provide realtime insights into an Intershop system from the Web Adapter point of view. Therefore, internal Web Adapter state information is structured and put into a form suitable for human readers. The monitor page consists of sections which are closely related to the main Web Adapter functionalities. The following types of information are provided:

• Information about Web Server/Web Adapter related configuration
• Information about application server request processing (load balancing)
• Information about the Web Adapter page caching feature
• Information about Web Adapter request queuing

Of the different pieces of information wastatistics provides, some have immediate relevance for the administration and maintenance of an Intershop application system. Others are displayed but are not of immediate significance and require interpretation.

For example, besides more or less static information about configuration parameters, one immediately usable information is that of the availability of application servers. Due to its design, wastatistics displays information only about those application servers that are currently registered at the master Control Server. By checking wastatistics you can easily determine whether all application servers are online and take steps when one or more of them are missing.

Calling wastatistics Monitor

Regardless of which Intershop Application is running, the monitor can be called with the following URL syntax:

http://localhost/INTERSHOP/wastatistics[?]

The argument is optional. It specifies a refresh interval for the "wastatistics" monitor page in seconds.

Be aware, however, that you must have added the necessary Web Server mapping for the extension /wastatistics before, see Guide - Checklist Going Live.

About wastatus Monitor

Contrary to wastatistics, which provides system information from the Web Adapter point of view, wastatus simply returns the status of the Web Adapter itself. Depending on its status, the Web Adapter responds either with 200 (OK) and a single-line HTML page Up or with 500 (Internal Server Error) and a single-line HTML page Down.

The Down state is meant to indicate that this Web Adapter is not able to process any request at the moment. Recognized Down state conditions are:

• No master Control Server could be contacted
• The local property file cannot be read (was modified since startup in some wrong way)

Calling the "wastatus" Monitor

Regardless of which Intershop Application is running, the monitor can be called with the following URL syntax:
http://localhost/INTERSHOP/wastatus

Be aware, that you must have added the necessary Web Server mapping for the extension .wastatus before, see Guide - Checklist Going Live.

Web Adapter Control Interface

Intershop Commerce Management's Web Adapter features a control interface that allows to trace and to modify certain aspects of the Web Adapter's internal operation. It is realized as a set of optional, "magic" request parameters, which can be appended as path segment parameters to URLs to be finally handled by the Web Adapter.

To enable this tracing and control functionality, add the following line to either the global or the local webadapter.properties file:

ctl.commandPrefix = wa_

 The command prefix wa_ can be modified to match your preferences. Intershop, however, recommends to use a prefix that is simple, short and unique enough. When enabled, the interface supports URLs like

http[s]://.../<url-path>[;<prefix><cmd>[=<args>][;...]][?<url-query>]

 The following table lists the available commands.

To restrict the control interface access for a defined IP range, for example, edit the Web server configuration accordingly. That is, in <IS.INSTANCE.LOCAL>/httpd/conf/extra/httpd-webadapter.conf, add something like

<LocationMatch ;wa_>
   Require ip 10.0.0.0/8
 </LocationMatch>

Web Adapter Session Handling

Web based applications use session IDs (SIDs) to overcome the limitations of the HTTP. As a stateless protocol, HTTP needs a session ID to assign certain activities to a specific user.

Each user entering a site for the first time starts a new session and gets a unique session ID. From that point, this SID will be used in all subsequent requests. Depending on the lifetime value specified for a session, the IDs remain valid for a few minutes, hours, or even days.

Session Cookie Settings

You can define how the session tracking cookies are set in the client. To this end, the webadapter.properties file includes the two settings

session.SIDCookie[.<site>]  = <Set-Cookie>
session.PGIDCookie[.<site>] = <Set-Cookie>

where session.SIDCookie defines the SID cookie generation, and session.PGIDCookie defines the PGID cookie generation. The default values are:

#session.SIDCookie  = Set-Cookie: sid=%v; Path=/; Version=1
#session.PGIDCookie = Set-Cookie: pgid=%v; Path=/; Version=1

The placeholder %v is to be used "as is" as the actual SID or PGID cookie value. Another placeholder, %s, expands to the request's site name (or an empty string), which is useful in the PGID name definition.

For detailed information about the <Set-Cookie> syntax, refer to RFC 2109 (http://www.ietf.org/rfc/rfc2109.txt).

Robot Detection

The Web Adapter can be configured to render responses without session ID or personalization group ID occurrences if the client is recognized as a robot. This detection can be based either on the user agent request header or on a client IP address.

session.skipForUserAgent.0=googlebot
session.skipForUserAgent.1=spider
session.skipForRemoteAddr.0=10.0.*
session.skipForRemoteAddr.1=127.0.0.1

If the client address cannot be determined from the connection (because of proxies, load balancers or SSL boxes, for instance), it can be read from the HTTP request header using

request.remoteAddrHeader=X-Forwarded-For

If a client is recognized as a robot via session.skipForUserAgent or session.skipForRemoteAddr but sends requests with a session ID, it can be redirected via 301 Moved Permanently to the session-less version of the request using

session.skipByRedirect = <true|false>

where the default setting is false.

For easier maintenance, the list of user agents and addresses can also be kept in plain text files. The configuration service is configured to support the following files:

• <IS.INSTANCE.SHARE>/system/config/cluster/robot-agents.txt

  # comment
  googlebot
  spider

• <IS.INSTANCE.SHARE>/system/config/cluster/robot-addresses.txt

  # comment
  10.0.*
  127.0.0.1

Page Cache Options

The Web Adapter can be seen as a specialized HTTP caching proxy. Whenever possible, it stores application server responses in a cache in the local file system and tries to respond to subsequent requests for the same resource by reading the stored response from the cache instead of forwarding the request to an application server.

The page cache is not session-dependent, which means that all session use the same set of pages in the cache (unless the pages are personalized via a personalization group ID).

Page Cache Management at Application Level

The page cache can be enabled or disabled individually for each sales channel storefront application. The page cache options are accessed via the channel management plug-ins for sales channels in Commerce Management. Commerce Management also provides the possibility to invalidate the entire page cache manually, and to submit pre-defined keywords in order to delete only pages from the page cache that are marked with this keyword. For details, see the user guide Managing Online Shops.

Page Cache Settings

The general naming scheme for locally cached static responses is:

<pagecache.dir>/<site>/static/<version>/hh/hh/hhhhhhhhhhhhhhhhhhhhhhhhhh

The format for locally cached pipeline-generated, or dynamic, responses is:

<pagecache.dir>/<site>/pipeline/<version>/hh/hh/hhhhhhhhhhhhhhhhhhhhhhhhhh

<pagecache.dir> is taken from the local webadapter.properties file and can be controlled by the user. The default entry is

#pagecache.dir=/<IS.INSTANCE.LOCAL>/webadapter/pagecache

If you want to supply a different path, change the setting as needed and remove the # character to enable this property.

<site> is taken from the request URL, <version> is a site attribute retrieved from the configuration servlet. It is a time stamp that increases whenever the page cache of a site is invalidated. After page cache invalidation, the Web Adapter will start to use the new directory and after a while there will be no more open handles in the old one, allowing the old directory to be removed completely.

The last two sub-directories and the filename itself are created from a hash value printed in hex format. The hash value is derived from a unique key string built from the following request data (some verbatim and some shortened to internal codes):

<siteStatus>#<method>#<SERVER_PORT_SECURE>#<Host>#<serviceType>#<PATH_INFO>[;pgid=<pgid>][?<QUERY_STRING>][#<postContent>]

Responses that depend on other request attributes, such as special headers or cookies, cannot be cached. The <postContent> data is only appended if it does not exceed a configurable maximum size defined in the Misc section of the global webadapter.properties file. The default value (in bytes) is

post.cachesize = 16000

Larger POST requests are not cacheable.

The following table lists basic page cache control settings defined in the global webadapter.properties file (Page Cache Options section).

Page Cache Invalidation Settings

The page cache invalidation is triggered by the Web Adapter Agent. The corresponding settings are stored in the Web Adapter Agent section of the global webadater.properties file.

The following properties are available:

Pragma No-Cache Requests

When the Web Adapter receives client requests containing a Pragma or Cache Control header, it will bypass its own cached pages, send the request to an application server, and respond and update its page cache with the new response that results from this request. This behavior can be disabled via the pagecache.ignoreGetCacheControlHeaders and pagecache.ignorePostCacheControlHeaders properties in the global webadapter.properties file. The default is

pagecache.ignoreGetCacheControlHeaders = true
pagecache.ignorePostCacheControlHeaders = true

The default value is true for both properties which is the recommended value for production systems. This ensures that it is always the application itself which determines the caching behavior (via enabling or disabling the page cache at application level), and not the clients. In a development environment, it may be advisable to set the properties to false. This way, developers can verify changes immediately by simply using the browser's refresh function, without having to disable the page cache.

Page Cache Pre-Fetching

The Web Adapter agent features a recursive web crawling functionality. It is intended to refill the Web Adapter's page cache after page cache deletions, typically after data replications. By default, the web crawler is started and stopped automatically based on defined schedules, or explicitly from System Management.

This means, if a crawler run is started explicitly from System Management while a scheduled crawler is already running, the previous process is stopped immediately, and the new crawler request is processed.

In custom projects, any pipeline can trigger the web crawler using the PrefetchPageCache pipelet from the core cartridge.

General Web Crawler Control

By default, the web crawler is enabled and sends the page requests to the IP address of the Web Adapter. Using the local webadapter.properties file, however, the general control settings can be changed.

Web Crawler Configuration

The web crawler, as part of the Web Adapter agent, retrieves its configuration via the configuration servlet. The configuration settings are stored in a global crawler_defaults.properties file and one or more site-specific crawler_<site_name>.properties files, each of them located in <IS.INSTANCE.SHARE>/system/config/cluster.

The following table lists the possible web crawler configuration properties.

Server Group Definition

In an Intershop Commerce Management deployment with multiple application servers, you can assign a single application server to certain server groups in a default installation. The default server groups are WFS for web front requests or BOS for back end requests. You can also add server group names for exclusive web front application use or data replication processes as required.

To add a server group to the server group list, open the global Web Adapter configuration file <IS.INSTANCE.SHARE>/system/config/cluster/webadapter.properties and add the intended value to server.groups. For example, to set up a server group for Data Replication processes:

• Edit the global property file and add Data Replication, making the configuration available to all web adapters.

  server.groups = WFS, BOS, DataRep

• Assign the Web Adapters to a particular server group by editing the property file.

HTTP Status Response Configuration

The instance-specific Web Adapter configuration file <IS.INSTANCE.LOCAL>/webadapter/webadapter.properties can control the response status to be returned by the web server upon a wastatus request. To this end, the property wastatus.defaultResponse is used.

#####################################################################
## service control
##
## Configures the regular HTTP response status of the 'wastatus'
## handler. This could be useful to exclude a running WA instance
## from load-balancing (before planned HTTP server maintenance).
## Set:
##
##  200 - to report a 'up' state (default)
##  500 - to report a 'down' state (not distinguishable from real failure)
##  503 - to report a 'down' state (with a distinct 'maintenance' code)
##
## Requires an appropriate front-end load-balancer configuration
## to be recognized - and a reset to "200" to resume operation!

#wastatus.defaultResponse = 200
#wastatus.defaultResponse = 500
#wastatus.defaultResponse = 503

SSL Box Support

If you use an external hardware unit to encrypt SSL communication, the port for decrypted https and the original SSL port must be propagated to the Web Adapter. In this case, edit the following lines in the <IS.INSTANCE.LOCAL>/webadapter/webadapter.properties file according to your needs:

sslbox.webserver.port=81
sslbox.public.port=443

For more information on SSL box support, see Guide - Web Server Settings.

Load Balancing Between Application Servers

The Web Adapter features two load-balancing algorithms for distributing HTTP requests between multiple application servers, a response time-based algorithm and another one that is based on a configurable server process weighting. These algorithms try to find the best server for each request. They distinguish between session-bound .enfinity/.servlet requests and requests that do not rely on session affinity, such as requests resolved by the .static handler.

Response Time-Based Load Balancing

Since there is no server load information available to the Web Adapter, it measures the request response time of each application server and uses this data as the quality indicator of an application server. The load-balancing achieves the best performance of a cluster by allocating more load to machines whose response times are shorter. All requests made as part of one session are routed to the same application server regardless of response time. This is known as session affinity and always applies, except in fail-over situations. Session affinity improves performance because there is a better chance that session-related data will still be in the server's cache, ensuring faster response times than those possible on other servers, which would need to load this data from the database first.

The behavior of the load-balancing algorithm can be controlled by four properties, all stored in the global webadapter.properties file.

session.lb.filterperiod = 120

request.lb.filterperiod = 30

session.lb.qualityweight = 1

request.lb.qualityweight = 1

Change the default settings only if necessary, as they are sensitive. An indication for load balancing problems might be a very uneven and unstable workload distribution among the application servers over a longer period of time. Keep in mind that there might be a number of other issues that lead to uneven application server load, for example single sessions that introduce an exceptional high load on the system, or Commerce Management user activities like data updates as well as Intershop Commerce Management jobs running on certain application servers.

Weight-Based Load Balancing

With this mechanism, each application server process is configured with a weight value. The value is supposed to indicate this server's theoretical request processing capacity in relation to the other servers. The server usage probabilities - as derived from the average response time measure - are corrected with the relative weight of the server within all available servers.

Assume one 4-core and one 8-core server with equal CPU clock-frequencies and response times. Normally, they share the load 50:50, maybe leading to a 80% host utilization of the smaller server and a 40% utilization of the larger one. To have a larger share of the load in the larger server, we have to "overload" the smaller one: Response times will increase, the usage probability will decrease. With the new weight setting, this can be done without reaching the "beginning overload" state, as illustrated below:

Each application server process (not host) - uniquely known to the Web Adapter by <IP>:<port> - is assigned exactly one weight value. The built-in default weight is 1. Custom values are specified using the lb.serverWeight* settings in the webadapter.properties file. These settings can be either global or specific per netmask, host or server process, using

lb.serverWeight             = <weight>
lb.serverWeight.<CIDR>      = <weight>
lb.serverWeight.<IP>        = <weight>
lb.serverWeight.<IP>.<port> = <weight>

where <CIDR> is the netmask in CIDR notation, <IP> is the IPv4 network address in decimal dotted notation, <port> is the TCP port number, and <weight> is the integral weight value (0..99999). The last matching setting - the most specific one - wins.

When using this load-balancing algorithm, keep the following issues in mind:

• Choose your (integral) weight values so that you can adjust their relations exactly enough: Use "10/20" instead of "1/2". Later, if you see that the "double capacity" assumption is wrong, you can adjust it to "10/18".
• Check the webadapter.log. Invalid settings are ignored with a warning here. You do not want a flooded log and an incomplete cluster setup in production.
• A weight of 0 can be used to exclude a server from getting new sessions or new single requests. However, it will still receive requests from the existing sessions, which are bound to it. But it could help to exclude a server from production load, e.g., for an upcoming local patch testing.
• The effective server weight configuration can be monitored in the .wastatistics dump. If the feature is in use, there is a new "weight" column in the per-server statistics. Also, the successfully parsed lb.serverWeight* settings are reported. The "( <n> matches)" output indicates how many servers got their actual weight setting from this particular rule. This may help in complex configurations like determining, for example, if a new rule exactly selects the 16 servers that were intended.

webadapter.properties settings:

lb.serverWeight               = 40
lb.serverWeight.10.0.29.64/26 = 80

/is-bin/INTERSHOP.wastatistics output:

single:            server  ...  ms_f  weight      WFS      BOS     TEST
  0      10.0.29.19:10099          1      40   0.1667   0.3333      -
  1      10.0.29.20:10099          1      40   0.1667      -        -
  2      10.0.29.64:10099          1      80   0.3333   0.6667   1.0000
  3      10.0.29.65:10099          1      80   0.3333      -        -
...
properties:
...
  lb.serverWeight                       =    40   (  2 matches)
  lb.serverWeight.10.0.29.64/26         =    80   (  2 matches)

Tuning and Troubleshooting

This section lists and explains the most common performance-relevant properties of webadapter.properties as well as configuration options for shortening the response time of the Web Adapter.

Performance-relevant Properties

post.maxsize

This property determines the maximum content-length of HTTP POST requests. It becomes important if one wants to restrict HTTP POST request size. Large POST requests can put a large amount of load on the application servers and can slow down their response time. Also, by using the parameter, one can avoid denial of service attacks through very large HTTP POST requests.

Per default, the value of this property is set to 0, which means there is no limit for HTTP POST requests. When you set a limit and a HTTP POST request exceeds the limit, the response will be 413 (Request Entity too large). Please keep in mind, however, that the value for post.maxsize must be large enough to ensure the smooth communication between Webadapter and application servers.

post.cachesize

This property determines the maximum content length of POST requests, which are cacheable by the WebAdapter.

Per default, the value of this property is set to 16000. See also Page Cache Settings.

as.connect.keepalive

If the property as.connect.keepalive is set to true, one persistent connection is used for all AS requests triggered by a single client request (the forwarded client request and all its <wainclude>s). Try both variants, true and false, in real conditions; false was sometimes observed to be faster.

Per default, this property is set to false.

cicevent.enabled

Enable this property to search and process business event tags (<cicevent .../>) in the response content. For performance reasons, do not enable it when not needed.

Per default, this property is set to false.

as.connect.timeout, as.socket.timeout, intershop.registration.registrationTime and intershop.registration.expirationTime  

When stopping an Intershop application server, the Web Adapter requires a certain time until it gets aware of the application server's status. Until that moment, the Web Adapter may redirect customer requests to an application server that is not running anymore. Customers whose request is sent to an already stopped application server receive an error message after some time, which is not desirable. The following properties can be adjusted to shorten the reaction time of the Web Adapter in case an application server stops.

The values of the properties as.connect.timeout and as.socket.timeout can be adjusted to set socket or communication timeouts. Use a short timeout for the connection attempt since there is a retry/failover policy. Use a long timeout for read/write operations to allow an AS to process expensive requests without running into timeouts.

Per default, the value of as.connect.timeout is set to 10 and the value of as.socket.timeout is set to 300.

Two other relevant properties for shortening the reaction time of the Web Adapter are intershop.registration.registrationTime and intershop.registration.expirationTime.

The application servers send an registration event every 10 seconds that informs the cluster that they are still alive. You can shorten the interval by changing the value for intershop.registration.registrationTime.

If appserver1 is shut down, the configuration service does not receive this event and declares appserver1 as "dead" after a certain time. You can change this timeout by adjusting the value of intershop.registration.expirationTime.

For more information see appserver.properties.

cs.poll.interval

This property sets the minimal time between subsequent configuration requests of the Web Adapter and Web Adapter agent. You may want to increase this value if there are many Web Adapter instances to reduce the configuration service load. 

Per default, the value of this property is set to 10.

session.lb.filterperiod

A small lb.filterperiod makes the Web Adapter react more quickly to server performance (load) changes but also makes it more sensitive to disturbance. Per default, the value of this property is set to 120.

See also lb.filterperiod.

pagecache.monitor

Use this property to toggle the request/hit accounting in .wastatistics. This can improve throughput in special, extreme load conditions.

Per default, this property is set to true.

cs.url.#= (Configuration Services)

All configuration services in the cluster must be listed here in form of an HTTP URL (the port number is required). In case one application server goes down, the Web Adapter can use another configuration service as fallback. Requests can be processed as long as at least one configuration service is available.