Appendix E HTTP Load Balancer Configuration File

The loadbalancer.xml file contains the configuration information for load balancing Sun Java™ System Application Server 7 Enterprise Edition instances. This file is part of the load balancer plug-in for the front-end web server. Although located in the web server, it is described in this manual because of its importance and relevance to the Sun Java System Application Server.

The encoding of the loadbalancer.xml file is UTF-8 to maintain compatibility with regular UNIX text editors. A schema file, sun-loadbalancer_1_1.dtd, determines the format and content of the loadbalancer.xml file.

This chapter describes loadbalancer.xml and sun-loadbalancer_1_1.dtd files in these sections:

sun-loadbalancer_1_1.dtd File

The sun-loadbalancer_1_1.dtd file defines the structure of the loadbalancer.xml file, including the elements it can contain and the subelements and attributes these elements can have.

Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:

Subelements


Note	Do not edit the sun-loadbalancer_1_1.dtd file; its contents change only with new versions of Sun Java System Application Server Enterprise Edition.


Note	The sun-loadbalancer_1_1.dtd interface is unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

Elements can contain subelements. For example, the following file fragment defines the cluster element.

The ELEMENT tag specifies that a cluster element can contain instance, web-module, and health-checker elements in that order.

The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements. The left column lists the subelement ending character, and the right column lists the corresponding requirement rule.

Table E-1 requirement rules and subelement suffixes
Subelement Suffix	Requirement Rule
element*	Can contain zero or more of this subelement.
element?	Can contain zero or one of this subelement.
element+	Must contain one or more of this subelement.
element (no suffix)	Must contain only one of this subelement.

If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.

Data

Some elements contain character data instead of subelements. These elements have definitions of the following format:

In the loadbalancer.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:

Attributes

Elements that have ATTLIST tags contain attributes (name-value pairs). For example:

<!ATTLIST instance   name           CDATA      #REQUIRED
                     enabled        %boolean;  "true"
                     disable-timeout-in-minutes  CDATA  "31"
                     listeners      CDATA      #REQUIRED>

An instance element can contain name, enabled, disable-timeout-in-minutes, and listeners attributes.

The #REQUIRED label means that a value must be supplied. The #IMPLIED label means that the attribute is optional, and that Sun Java System Application Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.

Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.

Elements in the loadbalancer.xml File

loadbalancer


Note	Subelements must be defined in the order in which they are listed under each Subelements heading unless otherwise noted.

Defines a load balancer. This is the root element; there can only be one loadbalancer element in a loadbalancer.xml file.

Subelements

The following table describes subelements for the loadbalancer element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table E-2 loadbalancer subelements
Element	Required	Description
cluster	zero or more	Defines a cluster of server instances.
property	zero or more	Specifies a load balancer property.

Attributes

property

Subelements

The following table describes subelements for the property element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table E-3 property subelements
Element	Required	Description
description	zero or one	Contains a text description of this element.

Attributes

The following table describes attributes for the property element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table E-4 property attributes
Attribute	Default	Description
name	none	Specifies the name of the property.
value	none	Specifies the value of the property.

Properties

The following table describes load balancer properties. The left column lists the property name, the middle column indicates the default value if the property is not present, and the right column describes what the property does.

Table E-5 Load Balancer Properties
Property Name	Default Value	Description
response-timeout-in-seconds	60	Specifies the timeout interval within which a response must be obtained for a request that is load balanced, or an error page will be sent to the client.
reload-poll-interval-in-seconds	0	Specifies the interval at which the load balancer checks whether the loadbalancer.xml time stamp has changed. If it has changed, the load balancer reloads the file. If 0, polling is disabled.
https-routing	false	Specifies whether the load balancer routes incoming HTTPS requests to the instance as HTTPS requests.
require-monitor-data	false	Specifies whether load balancer monitoring is enabled.

description

Subelements

Attributes

cluster

Subelements

The following table describes subelements for the cluster element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table E-6 cluster subelements
Element	Required	Description
instance	zero or more	Defines a server instance.
web-module	zero or more	Defines a web module.
health-checker	zero or one	Configures the cluster’s health checker.

Attributes

The following table describes attributes for the cluster element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table E-7 cluster attributes
Attribute	Default	Description
name	none	Specifies the name of the cluster. Within a load balancer, cluster names must be unique.

instance

Subelements

Attributes

The following table describes attributes for the instance element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table E-8 instance attributes
Attribute	Default	Description
name	none	Specifies the name of the server instance. Instance names must be unique.within a cluster as well as across clusters.
enabled	true	(optional) Specifies whether instance is active (enabled) for requests to be load balanced to it.
disable-timeout-in-minutes	31	(optional) Specifies the quiescing timeout interval, at which the load balancer disables the instance and closes all its open connections.
listeners	none	Specifies a space-delimited list of the URLs of the instance’s listeners. Within a cluster, as well as across clusters, listener URLs must be unique.

web-module

Subelements

The following table describes subelements for the web-module element. The left column lists the subelement name, the middle column indicates the requirement rule, and the right column describes what the element does.

Table E-9 web-module subelements
Subelement	Required	Description
idempotent-url-pattern	zero or more	Defines the idempotent URLs to be retried.

Attributes

The following table describes attributes for the web-module element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table E-10 web-module attributes
Attribute	Default	Description
context-root	none	Specifies the context root of the web module. Within a cluster, context roots must be unique. The default context root can be specified as “ “ or “/”. Context roots can also be specified with a leading slash (/). In a cluster, if an empty context root is used along with specific context roots, the load balancer plug-in will give precedence to the specific context roots.
enabled	true	(optional) Specifies whether web module is active (enabled) for requests to be load balanced to it.
disable-timeout-in-minutes	31	(optional) Specifies the quiescing timeout interval, at which the load balancer disables the web module and closes all its open connections.
error-url	none	Specifies the page to be displayed in case of a failure / error. If the error-url sub-element is missing or invalid, the load balancer will display the default error page, sun-http-lb-error.html, from the errorpages directory of the load balancer plug-in.

idempotent-url-pattern

Defines the URL pattern of requests that the load balancer can retry in case of a failure, on healthy server instances.

Attributes

The following table describes attributes for the idempotent-url-pattern subelement. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table E-11 idempotent-url-pattern attributes
Attribute	Default	Description
url-pattern	none	The url-pattern is either an absolute URL for the idempotent request or an URL specification that uses wild cards.
no-of-retries	-1	Attribute to define the number of retries the load balancer must perform for an idempotent request. If the value is -1, the number of retries will be equal to one less than the number of Application Server instances that can serve this request. The Application Server instances that can server this request can span multiple clusters, provided all the instances have the same context root.

health-checker

Subelements

Attributes

The following table describes attributes for the health-checker element. The left column lists the attribute name, the middle column indicates the default value, and the right column describes what the attribute does.

Table E-12 Health checker properties
Attribute	Default	Description
url	/	(optional) Specifies the URL to ping to determine the health state of a listener.
interval-in-seconds	30	(optional) Specifies the interval at which health checks of instances occur.
timeout-in-seconds	10	(optional) Specifies the timeout interval within which a response must be obtained for a listener to be considered healthy.

Previous Contents Index Next
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Update 3 Administration Guide