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

> ## 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
> - Elements in the loadbalancer.xml File

> ### 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.

> 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.

> For general information about DTD files and XML, see the XML specification at:

> http://www.w3.org/TR/REC-xml

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

> - Subelements
> - Data
> - Attributes

> ### Subelements

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

> <!ELEMENT cluster (instance*, web-module*, health-checker?)>

> 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:

> <!ELEMENT element-name (#PCDATA)>

> For example:

> <!ELEMENT description (#PCDATA)>

> 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:

> <description>response timeout property</description>

> ### 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

> This section describes the XML elements in the loadbalancer.xml file.

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

> ### loadbalancer

> 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

> none

> ### property

> Specifies a load balancer 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

> Contains a text description of the parent element.

> ##### Subelements

> none

> ##### Attributes

> none

> ### cluster

> Defines a cluster of server instances.

> ##### 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

> Defines a server instance.

> ##### Subelements

> none

> ##### 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

> Defines a 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

> Configures the cluster’s health checker.

> ##### Subelements

> none

> ##### 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

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.