IBM TJ Watson Research Center
Internet Draft Alan Bivens
Document: draft-bivens-sasp-00.txt IBM Research
Expires: December 2004 June 2004
Sever/Application State Protocol version 1 (SASPv1)
Status of this Memo
By submitting this Internet-Draft, I certify that any applicable
patent or other IPR claims of which I am aware have been disclosed, or
will be disclosed, and any of which I become aware will be disclosed,
in accordance with RFC 3668.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
Entities responsible for distributing work across a group of systems
traditionally do not know a great deal about the ability of the
applications on those systems to complete the work in a satisfactory
fashion. Workload management systems traditionally know a great deal
about the health of applications, but have little control over the
rate in which these applications receive work. The SASP protocol
provides a mechanism for load balancers and workload management
systems to communicate better ways of distributing the existing
workload to the group members.
Conventions used in this document
Load Balancer - Entity responsible for distributing requests amongst
the available members.
Member - Machine, process, or application used to service
requests.
Group Workload Manager (GWM) - Entity responsible for reporting or
managing a group of members (or member managers) on
multiple machines.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC-2119 [i].
[Page i]
Server/Application State Protocol June 2004
Table of Contents
1. Introduction 2
2. General Message Structure 2
2.1 TLV Structure 3
2.2 Component Types 4
2.3 SASP Protocol Header 5
2.4 Version Negotiation 5
3. Singular Protocol Components 6
3.1 Member Data Component 6
3.2 Group Data Component 7
3.3 Weight Entry Data Component 8
3.4 Member State Instance Component 9
4. Group Protocol Component 10
4.1 Group of Member Data Component 10
4.2 Group Of Weight Data Component 11
4.3 Group of Member State Data Components 11
5. Protocol Messages 12
5.1 Registration Request and Reply 12
5.2 DeRegistration Request and Reply 14
5.3 Get Weights Request and Reply 17
5.4 Send Weights 19
5.5 Set Member State Request and Reply 20
5.6 Set Load Balancer State Request and Reply 22
6. Example of SASP Message Encoding 24
7. Protocol Flow 28
7.1 Normal Protocol Flow 28
7.2 Behavior in Error Cases 30
7.3 Example Flow 1 31
7.4 Example Flow 2 33
Security Considerations 34
References 34
Author's Addresses 34
Full Copyright Statement 35
[Page 1]
Server/Application State Protocol June 2004
1. Introduction
The Server/Application State Protocol is designed to enable Load
Balancers or Schedulers to (1) receive traffic weight recommendations
from Workload Managers and (2) to register with Workload Managers
members of Load Balancing/Scheduling groups and (3) to enable
Workload Managers to suggest new Load Balancing group members to
Load Balancers and Schedulers
The figure below shows where the SASP entities are in typical load
balancing topology.
----------
| Group |
--------|Member 1|<--|
| ---------- |
| |
--------- ---------- | ---------- |
|Request|<------| Load |---| | Group | |
|Origins|<------|Balancer|-----------|Member 2|<--|
--------- | |---| ---------- |
---------- | |
^ | ---------- |
| --------| Group | |
SASP | |Member 3|<--|
------- ---------- |
| |
| -------------------- |
| | Group | SASP |
------| Workload Manager |<----------
--------------------
2. General Message Structure
SASP is a binary protocol which facilitates communication from Load
Balancers/Schedulers to Workload Managers. The connection between
the GWM and the Load Balancer/Scheduler is expected to be a long
running TCP connection. Security in SASP is handled by transporting
binary messages over SSL/TLS. This document only describes the
message format and protocol behavior above the connection and
security layers. Connection and security aspects including SSL's
authentication and encryption will be implementation specific.
Any string interpreted by the group workload manager is assumed to
use UTF8. Components implementing SASP MUST support the
single-byte ASCII character encodings of UTF8. Components MAY also
choose to provide support for additional multi-byte UTF8 character
encodings. It is recommended that customers using SASP-enabled
products configure the string-generating components (load balancers
and group members) to use the same character-encoding level.
Many of the SASP structures involve the transfer of multi-byte
integer values. In all cases where multi-byte integer values are
used, they are considered to be in network-byte order (big-endian).
[Page 2]
Server/Application State Protocol June 2004
SASP is organized into several message components. For extendibility
and ease of processing, each message component is described in a TLV
(Type, Length, Value) format. An illustration of the SASP structure
can be found in the example below. The first section is the header
followed by the message component type. As mentioned, the header,
message component, and all other components have a TLV format. Each
component value contains a variable number of fields, some of which
refer to upcoming components (explained component descriptions in the
upcoming sections). After the first message component, any number of
additional components may be included (as stipulated in the fields of
the message type).
-------------------------------------------------
| |T| Type (SASP Header Type) |
| SASP |----------------------------------|
| Header |L| Length of SASP header TLV |
| |----------------------------------|
| |V| Header fields |
|-----------------------------------------------|
| |T| Type (Message Type) |
| Message |----------------------------------|
| Type |L| Length of this Message Type TLV|
| Component |----------------------------------|
| |V| Component fields |
|-----------------------------------------------|
| |T| Type (Component Type) |
| |----------------------------------|
|Component-1 |L| Length of this TLV |
| |----------------------------------|
| |V| Component fields |
|-----------------------------------------------|
| ... |
|-----------------------------------------------|
| |T| Type (Component Type) |
| |----------------------------------|
|Component-n |L| Length of this TLV |
| |----------------------------------|
| |V| Component fields |
-------------------------------------------------
2.1 TLV Structure
An illustration of the TLV format is shown below. The Type is a two
byte field containing a binary value for the component type. The
Length is a two byte field containing the size of the TLV in bytes
(including the Type and Length fields). The Value field is a
variable length field which actually contains the data of the
component.
< xxxx xxxx xxxx xxxx, xxxx xxxx xxxx xxxx, xxxx...........xxxx
|-----------------| |-----------------| |-----------------|
Type(2 bytes) Length(2 bytes) Value(variable)
[Page 3]
Server/Application State Protocol June 2004
2.2 Component Types
The TLV structure requires a type value for each protocol component.
All SASP types are listed in this section.
Name of Type Type value
------------ -----------
Reserved 0x0000-0x1000
A. Message Types
Registration Request 0x1010
Registration Reply 0x1015
DeRegistration Request 0x1020
DeRegistration Reply 0x1025
Get Weights Request 0x1030
Get Weights Reply 0x1035
Send Weights 0x1040
Set Load Balancer State Request 0x1050
Set Load Balancer State Reply 0x1055
Set Member State Request 0x1060
Set Member State Reply 0x1065
B. Utility Component Types
SASP Header 0x2010
C. Singular Component Types
Member Data 0x3010
Group Data 0x3011
Weight Entry Data 0x3012
Member State Instance 0x3013
D. Group Component Types
Group of Member Data 0x4010
Group of Weight Entry Data 0x4011
Group of Member State Data 0x4012
Reserved 0xF000-0xFFFF
[Page 4]
Server/Application State Protocol June 2004
2.3 SASP Protocol Header
An illustration of the SASP Header is found in the table below. It
is expected that every message will start with the SASP Protocol
Header component.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| SASP header type (0x2010) | Size of this TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Version | Message Length
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Message ID
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|
+-+-+-+-+-+-+-+-+
- Version: The version of the protocol used in this message
- Message Length: A 4 byte signed integer value representing the
total length of the SASP message. It is said to be a signed 4
byte value to make any java implementations easier (or any other
implementations without unsigned values); however, no negative
lengths are valid.
- Message ID: Each request message is given a 4 byte Message ID by
the message originator which is simply returned in the Message ID
field of the reply. This field is meant to assist the requestor
in correlating replies to the appropriate request when many
requests have been sent. In the Send Weights message (the only
message transaction that has no reply), this field serves no
purpose.
2.4 Version Negotiation
To negotiate the version of the protocol used by the entities
involved in the connection, the GWM views the version included in
the Load Balancer request as the load balancer's proposed version.
If the GWM supports the version proposed by the load balancer, it
will respond to the connection with the appropriate response code
and the load balancer's proposed version in the response header.
This proposed version should be the version used for all messages
used in this connection.
If the GWM does not support the version proposed by the load
balancer, the GWM will respond with a "message not understood"
response code and the GWM's highest supported SASP version in the
version field of the response header. This is an indication for
the load balancer to come down to GWM's SASP version level.
[Page 5]
Server/Application State Protocol June 2004
3. Singular Protocol Components
The most basic of SASP components are singular components because
they describe a single instance of a member, member resource, member
weight, or group. Some of the SASP components reuse other SASP
components. When this is the case, any component being reused by a
base component will be simply given immediately following the base
component. Some examples of this technique are seen and explained in
the Weight Entry and Member State Instance components.
3.1 Member Data Component
The member data component describes a particular member and is
referred to by other components.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Member Data Type (0x3010) | Size of this TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Protocol | Port | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
| |
+ +
| |
+ IP Address of Member +
| |
+ +-+-+-+-+-+-+-+-+
| | Label Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
. .
. Label .
. .
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Protocol: The assigned number of the IP transport layer used in the
Protocol Field of the IP header. These are defined in RFC 1700[iii];
however, a current list is maintained at http://www.iana.org.
for example: TCP = 0x06, UDP = 0x11, etc.
- Port: The port number used for communication to the member.
*** A value of 0 can be given for the Protocol and Port to signify a
system level member. However, 0 shouldn't be perceived as a wildcard
for either Port or Protocol fields (i.e. a deregistration request
which includes a MemberData component with a 0 for the port doesn't
mean deregister all applications listening on any port of that IP and
protocol).
[Page 6]
Server/Application State Protocol June 2004
- IP Address: The current format is described by the following 16
bytes, where IPv4 addresses are represented as "IPv4-compatible IPv6
addresses" [ii]. In the following example, the x's and
zeros represent 4 bit hex values. The x's describe arbitrary hex
values.
IPv4 Address: 00 00 00 00 00 00 00 00 00 00 00 00 xx xx xx xx
IPv6 Address: xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx
- Label length: The length, in bytes, of the label string to follow.
- Label: A UTF8 string that may be set while registering a member.
This string is opaque to the GWM and is simply included with any
correspondence containing the member data component. Note that the
size of this label is <= 255 bytes. Because UTF8 character encodings
may be up to 6 bytes, care must be exercised by the load balancer or
member to make sure the UTF8 string it sends the GWM is in fact <=
255 bytes.
3.2 Group Data Component
The group data component simply describes a group to associate other
singular components with.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Group Data Type (0x3011) | Size of this TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| LB ID Length | |
+-+-+-+-+-+-+-+-+ +
. .
. LB ID .
. .
+ +-+-+-+-+-+-+-+-+
| |Group Name Len |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Group Name .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- LB ID Length: Length of the LB ID to follow (in bytes).
- LB ID: A byte array used as a unique identifier and
a context for the Group Name (e.g. the MAC address of the Load
Balancer or some type of UUID). This byte array is used by the
Group Workload Manager to associate application registration,
deregistration, and set state messages with the correct load
balancer. This unique identifier should not be any longer than 64
bytes.
- Group Name Len: Length of the Group Name field to follow (in bytes).
[Page 7]
Server/Application State Protocol June 2004
- Group Name: A UTF8 string the load balancer has chosen to tell the
Group Workload Manager that members being registered with this Group
Name are equivalent in function. In Get Weight and DeRegistration
messages, the Group Name may be omitted (Group Name Length = 0) to
indicate all groups from the associated load balancer.
3.3 Weight Entry Data Component
The Weight Entry Component is used by the get and send weight
messages to associate a weight with a particular member (or Member
Data). It also uses an opaque member state field and a general
member flags field to denote extra information about a member
(described below). When the Weight Entry component is used, the
Member Data TLV it refers to is first listed, immediately followed by
the Weight Entry TLV.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Member Data Type (0x3010) | Size of this Member Data TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Member Data Fields .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Weight Entry Type (0x3012) | Size of this Weight Entry TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| State Field | Flags Field | Weight |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- State Field: This field is used by the member to communicate state
information to the scheduler. The information placed in this field
is opaque to the GWM and will simply be forwarded to the scheduler
with the member weights. There are no defined values for this field.
- Flags Field: This field has several flag values which describe
several attributes of the member. The contact success flag describes
the current condition of contact with the member. The quiesce flag
is used when an administrator would like to temporarily remove a
member from the weight calculation, but not deregister it from the
group. When quiesced, the member will still show up in the weights,
but the quiesce flag will be set and its weight will be zero. When
the administrator returns this member to active, the quiesce flag
will be 0 and a weight provided. The registration flag simply stores
how the member was registered.
a) Contact Success Flag (set by the GWM)
xxxx xxx1 The Group Workload Manager is currently experiencing
no errors when contacting this member.
xxxx xxx0 The Group Workload Manager is currently experiencing
an error when contacting this member
b) Quiesce Flag (set by the Load Balancer or Member)
xxxx xx1x The member is quiesced
xxxx xx0x The member is active (not quiesced)
[Page 8]
Server/Application State Protocol June 2004
c) Registration Flag (set by the GWM)
xxxx x1xx This Member has been registered by the Load
Balancer/Scheduler
xxxx x0xx This Member has registered itself
d) Leftmost five bits are reserved 0000 0xxx - 1111 1xxx
3.4 Member State Instance Component
The Member State Instance Component is used by the set member state
message to indicate the sender's perceived state of the member
mentioned. This component is used to set values that will ultimately
end up in the WeightEntry component. When the Member State Instance
component is used, the Member Data TLV it refers to is first listed,
immediately followed by the Member State Instance TLV.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Member Data Type (0x3010) | Size of this Member Data TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. Member Data Fields .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Member State Instance(0x3013) | Size of Member State Inst TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| State Field | Flags Field |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- State Field: This field is used by the member to communicate state
information to the load balancer or scheduler. There are no defined
values for this field.
- Flags Field: This field has describes attributes of the member.
Currently the only flag value defined is that of the quiesce flag.
The quiesce flag is used when an administrator would like to
temporarily remove a member from the weight calculation, but not
deregister it from the group. When quiesced, the member will still
show up in the weights, but the quiesce flag will be set and its
weight will be zero. When the administrator returns this member to
active, the quiesce flag will be 0 and a weight provided.
a) Quiesce Flag
xxxx xxx1 The Member or Load Balancer setting this state is
quiescing this member
xxxx xxx0 The Member or Load Balancer setting this state is
placing the member in a non-quiesced state
b) Leftmost seven bits are reserved 0000 000x - 1111 111x
[Page 9]
Server/Application State Protocol June 2004
4. Group Protocol Components
Group protocol components each contain a collection of related
singular components. In particular, they associate Member Data,
Weight Entry, or Member State Instance components to a particular
Group Data component. In these cases, the particular "Group of x"
component will be immediately followed by the Group Data component.
The Group Data component will be immediately followed by any number
of singular components the group contains. In figures listed in this
document, a component type with an asterisk denotes a component
that is repeated a number of times.
4.1 Group of Member Data Component
The "group of member data" component describes a particular group of
members and is used in the registration message components.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Group of Member Data (0x4010) | Size of GroupOfMemberData TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Member Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. Group Data TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. *Array of Member Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Member Count: The number of Member Data Components immediately
following the Group Data structure.
- Array of Member Data Components: There will be as many Member Data
TLVs as Member Count has specified. A load balancer/scheduler would
use these components to pass information that would enable the Group
Workload Manager to identify the members to associate with this Group
Name. The Member Data Component was described in Section 3.1. In
DeRegistration messages, the count and length of the Member Data
TLV may be set to 0 to indicate all members of a particular group.
[Page 10]
Server/Application State Protocol June 2004
4.2 Group Of Weight Data Component
The "Group of Weight Data" Component is used by the get and send
weight messages to create a list of Weight Entry Components for a
particular group.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Group Weight Entry Type(0x4011)| Size of GroupOfWeightEntry TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Weight Entry Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. Group Data TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. *Array of Weight Entry Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- Weight Entry Count: The number of Member Data / Weight Entry
combinations to follow the Group Data TLV.
- Array of Weight Entry Data TLVs: There will be as many [Member Data
/ Weight Entry] TLVs as Weight Entry Count has specified. Each
Weight Entry component is preceded by its corresponding Member Data
component as explained in Section 3.3. This Member Data / Weight
Entry data combination will repeat to form as many Weight Entry items
as the Weight Entry Count specifies.
4.3 Group of Member State Data Components
The "group of member state data" component describes a particular set
of members and their corresponding state fields used in the Set
Member State messages.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Group Weight Entry Type(0x4011)| Size of GroupOfWeightEntry TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Member State Instance Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. Group Data TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. *Array of Member State Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
[Page 11]
Server/Application State Protocol June 2004
- Member State Instance Count: The number of Member Data / Member
State Instance combinations following the Group Data component.
- Array of Member State Data Components: Each Member State Instance
component is immediately preceded by its corresponding Member Data
component as explained in Section 3.4. This Member Data / Member
State Instance combination will repeat to form as many Member State
items as the Member State Instance Count specifies.
5. Protocol Messages
SASP messages are a collection of TLVs (Type, Length, and Value
components). The header has no information as to what type of
message it is part of; the purpose specific information is in the
message component. This format could facilitate placing more than
one message component in a single message; however, this use of
multiple message components is not supported in every GWM and could
produce indeterminate behavior. Similar to the other protocol
components, when a message component needs to involve other
components, the additional components immediately follow the message
component.
All SASP requests sent to the GWM will be acknowledged with a reply.
The reply contains information requested as well as a single-byte
response code describing the success of the request. SASP defines
some general response codes in the range of 0x00 - 0x3F that may be
used regardless of the response message type. However, some request
types may cause specific error conditions not covered by the general
response codes. The response code range of 0x40 - 0xFF is used for
these message-specific response codes. Any given SASP response will
only contain one response code (depending on the error type). This
section explains the format and purpose of specific SASP messages.
5.1 Registration Request and Reply
This exchange happens between the load balancer/scheduler and the
Group Workload Manager as well as between the Group Workload
Manager and the Member to register the members in a group specified
by Group Name. Applications are identified with an IP address,
Protocol, and Port. Systems are identified only with an IP Address
(Port = 0x0000 and Protocol = 0x00). All members in a group have
equivalent functionality so the Group Workload Manager can direct
routers, load balancers and schedulers to any member in the group.
Even though registrations can come from either the load
balancer/scheduler or the actual member, member-initiated
registrations will only be considered if the Trust flag is set
while setting the state of the load balancer/scheduler.
[Page 12]
Server/Application State Protocol June 2004
Registration Request
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Registration Req. Type(0x1010)| Size of Registration Req. TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flag Field | Group of Member Data Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. *Array of Group of Member Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*There will be as many Group of Member Data Components as "Group
of Member Data Count" has specified.
- Flag Field:
a) Load Balancer Flag
xxxx xxx1 The entity sending this message is the Load Balancer.
xxxx xxx0 The entity sending this message is an Application.
b) Leftmost seven bits are reserved 0000 000x - 1111 111x
- Group of Member Data Count: The number of "Group of Member Data"
components immediately following the Registration Request component.
- Array of Group of Member Data Components: Each "Group of Member
Data" component is immediately followed by Group Data Components and
its Member Data components (as described in Section 4.1). In
the case where several of these "Group of Member Data" components
may be present, the second "Group of Member Data" component only
appears after all of the internal components that are referred to by
the first "Group of Member Data" component are listed. The format
is the same for all subsequent "Group of Member Data" components in
the message.
[Page 13]
Server/Application State Protocol June 2004
Registration Reply
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Registration Reply Type(0x1015)| Size of Registration Reply TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Return Code |
+-+-+-+-+-+-+-+-+
- Return Code: A byte return code indicating the status of action
taken.
General SASP return codes (0x00 - 0x3F)
---------------------------------------
0x00 Successful
0x10 Message not understood
0x11 Sender not authorized to register members
Message Specific return codes (0x40 - 0xFF)
-------------------------------------------
0x40 Member already registered
0x44 Duplicate Member in Request
0x45 Invalid Group (determined by the GWM)
0x50 Invalid Group Name Size (size == 0)
0x51 Invalid LB uid Size (size == 0 or than max)
0x60 Member is registering itself, but LB does not trust
member-initiated registrations. This registration will
not be processed.
0x61 Member is registering itself, but LB hasn't yet contacted
the GWM. This registration will not be processed.
**The Invalid Group error return code refers to the LB or member
attempting to form a group that the GWM considers invalid. For
example, some GWM vendors may not support the registration of both
System and Application members in the same group. To determine what
can cause a GWM to return this error code, the vendor's documentation
must be consulted.
5.2 DeRegistration Request and Reply
This exchange happens between the load balancer/scheduler and the
Group Workload Manager as well as between the Group Workload
Manager and the Member to deregister members from a group specified
by Group Name with the Group Workload Manager. All members in a
group have equivalent functionality so the Group Workload Manager
can direct routers, load balancers and schedulers to any member
in the group. Even though deregistrations can come from either the
load balancer/scheduler or the actual member, member-initiated
deregistrations will only be considered if the Trust flag is set
while setting the state of the load balancer/scheduler.
[Page 14]
Server/Application State Protocol June 2004
DeRegistration Request
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|DeRegistration Req.Type(0x1020)|Size of DeRegistration Req. TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flag Field | Reason | Group of Member Data Count |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. *Array of Group of Member Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*There will be as many Group of Member Data Components as "Group
of Member Data Count" has specified.
- Flag Field:
a) Load Balancer Flag
xxxx xxx1 The entity sending this message is the Load Balancer.
xxxx xxx0 The entity sending this message is an Application.
b) Leftmost seven bits are reserved 0000 000x - 1111 111x
- Reason: Byte describing the reason for deregistering the group or
instance.
SASP-defined Reason Codes (0x00-0x7F)
-------------------------------------
0x00 no reason given
0x01 Learned and Purposeful, i.e. a human has deconfigured this
member from the Load Balancer configuration
0x80-0xFF open for vendor specific deregistration reason codes
- Group of Member Data Count: The number of "Group of Member Data"
components immediately following the DeRegistration Request
component.
[Page 15]
Server/Application State Protocol June 2004
- Array of Group of Member Data Components: Each "Group of Member
Data" component is immediately followed by Group Data Components and
its Member Data components (as described in Section 4.1). In
this case, where several of these "Group of Member Data" components
may be present, the second "Group of Member Data" component only
appears after all of the internal components that are referred to by
the first "Group of Member Data" component are listed. The format
is the same for all subsequent "Group of Member Data" components in
the message.
** If Member Count equals zero in the Group of Member Data
component, the Group Workload Manager will deregister the
entire group.
** Recall that the Group Data Component contains both a Unique LB
Identifier field and a Group Name field. If the Group Data
component has no Group Name (GroupData's Group Name Length==0),
the Group Workload Manager will deregister all groups
associated with this load balancer.
DeRegistration Reply
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| DeReg. Reply Type(0x1025) | Size of DeReg. Reply TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Return Code |
+-+-+-+-+-+-+-+-+
- Return Code: A byte return code indicating the status of action
taken.
General SASP return codes (0x00 - 0x3F)
---------------------------------------
0x00 Successful
0x10 Message not understood
0x11 Sender not authorized to deregister members
[Page 16]
Server/Application State Protocol June 2004
Message Specific return codes (0x40 - 0xFF)
-------------------------------------------
0x41 Application or System not registered
0x42 Unknown Group Name
0x43 Unknown LB uid
0x44 Duplicate Member in Request
0x46 Duplicate Group in Request (for remove all members/groups
requests)
0x51 Invalid LB uid Size (size == 0 or than max)
0x60 Member is deregistering itself, but LB does not trust
member-initiated deregistrations. This deregistration will
not be processed.
0x61 Member is deregistering itself, but LB hasn't yet contacted
the GWM. This deregistration will not be processed.
5.3 Get Weights Request and Reply
This exchange happens between the Load Balancer/Scheduler and the
Group Workload Manager to get weights for the groups specified in
the list of GroupData objects. In the case of application load
balancing (balancing workloads between applications with the same
functionality), the Load Balancer would call the Group Workload
Manager every Interval (parameter returned by the Group Workload
Manager below) to get an array of weights and associated members
(e.g. Application1 20, SecondCopyOfApplication 30,
ThirdCopyOfApplication 5). The load balancer then uses these weights
to determine the fashion in which work will be sent to each of the
members. For example, in the case of weighted round robin, the Load
Balancer/Scheduler would then send a request to Application1, the
next to SecondCopyOfApplication and the next to
ThirdCopyOfApplication. After 15 requests, the load
balancer/scheduler would only send work to Application1 and
SecondCopyOfApplication. After an additional 30 requests, the load
balancer/Scheduler would only send requests to
SecondCopyofApplication. After another 10 requests, the load
balancer/Scheduler product would start over using the weights of 20,
30 or 5 again, or if the Interval number of seconds have passed, get
a new set of weights.
[Page 17]
Server/Application State Protocol June 2004
Get Weights Request
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Get Weights Req. Type(0x1030) | Size of Get Weights Req. TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Group Data Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. *Array of Group Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*There will be as many Group Data Components as "Group Data Count"
has specified.
- Group Data Count: The number of "Group Data" components
immediately following the Get Weights Request TLV.
- Array of Group Data Components: This array of Group Data Components
list the groups the load balancer wants to get weights for.
** If there is no group name in the Group Data structure of the Get
Weights Request, the load balancer is requesting weights for all
groups registered for the load balancer.
Get Weights Reply
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Get Weights Reply Type(0x1035)| Size of Get Weights Reply TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Return Code | Interval | Group of Weight
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Entry Data
Count| |
+-+-+-+-+-+-+-+-+ +
. .
. *Group of Weight Entry Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
* There will be as many Group of Weight Entry Data Components as
"Group of Weight Entry Data Count" has specified.
[Page 18]
Server/Application State Protocol June 2004
- Return Code: A byte return code indicating the status of action
taken.
General SASP return codes (0x00 - 0x3F)
---------------------------------------
0x00 Successful
0x10 Message not understood
0x11 Sender not authorized to deregister members
Message Specific return codes (0x40 - 0xFF)
-------------------------------------------
0x42 Unknown Group Name
0x43 Unknown LB uid
0x51 Invalid LB uid Size (size == 0 or than max)
- Interval: These two bytes indicate a recommended polling interval
for the load balancer to use. The Group Workload Manager is stating
that any polling interval smaller than the suggested interval would
probably retrieve values before they have had a chance to change.
- Group of Weight Entry Data Components: Each "Group of Weight Data"
component is immediately followed by Group Data Components and its
Weight Entry Data components (as described in Section 4.2). In this
case, where several "Group of Weight Data" components may be present,
the second "Group of Weight Data" component only appears after all of
the internal components that are referred to by the first "Group of
Weight Data" component are listed. The format is the same for all
subsequent "Group of Weight Data" components in the message.
5.4 Send Weights
This exchange happens between the Group Workload Manager and the
load balancer/scheduler to send the new weights for the group
specified in Group Name. This message is unique in that it is the
only message exchange initiated by the Group Workload Manager and
the only message that has no reply. In the case of Application load
balancing (balancing workloads between applications with the same
functionality), the Group Workload Manager would message the Load
Balancer at a possibly dynamic interval (chosen by the Group
Workload Manager) to send an array of weights and associated members
(e.g. Application1 20, SecondCopyOfApplication 30,
ThirdCopyOfApplication 5). The load balancer then uses these weights
to determine the fashion in which work will be sent to each of the
members. For example, in the case of weighted round robin, the load
balancer/Scheduler would then send a request to Application1, the
next to SecondCopyOfApplication and the next to
ThirdCopyOfApplication. After 15 requests, the load
balancer/scheduler would only send work to Application1 and
SecondCopyOfApplication. After another 30 requests, the load
balancer/Scheduler would only send requests to
SecondCopyofApplication. After an additional 10 requests, the load
balancer/Scheduler product would start over using the weights of 20,
30 or 5 again, if it has not yet received a new set of weights. The
Group Workload Manager only sends this message if the Push flag has
been enabled using a Set Load Balancer State message.
[Page 19]
Server/Application State Protocol June 2004
Send Weights Message
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Send Weights Type(0x1040) | Size of Send Weights TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Group of Weight Data Count | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. *Group of Weight Entry Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
* There will be as many Group of Weight Entry Data Components as
"Group of Weight Data Count" has specified.
- Group of Weight Entry Data Components: Each "Group of Weight Data"
component is immediately followed by Group Data Components and its
Weight Entry Data components (as described in Section 4.2). In this
case, where several "Group of Weight Data" components may be present,
the second "Group of Weight Data" component only appears after all of
the internal components that are referred to by the first "Group of
Weight Data" component are listed. The format is the same for all
subsequent "Group of Weight Data" components in the message.
5.5 Set Member State Request and Reply
This is a special exchange that can take place between the load
balancer and the Group Workload Manager or between the Member and
the Group Workload Manager to pass information about the state of
the member including placing the member in quiesced or non-quiesced
states. In particular, the load balancer/scheduler can use this
message to quiesce a set of members. Members can also use this
message to quiesce themselves as well as passing certain state
information to the load balancer/scheduler that is opaque to the
Group Workload Manager. This opaque state information is passed to
the load balancer/scheduler with the weights during get and send
weight messages.
[Page 20]
Server/Application State Protocol June 2004
Set Member State Request
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|SetMemberState Req.Type(0x1060)|Size of SetMemberState Req. TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Flag Field | Group of MemberStateData Count| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +
. .
. *Array of Group of Member State Data Components .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
*There will be as many Group of Member State Data Components as
"Group of Member State Data Count" has specified.
- Flag Field:
a) Load Balancer Flag
xxxx xxx1 The entity sending this message is the Load Balancer.
xxxx xxx0 The entity sending this message is an Application.
b) Leftmost seven bits are reserved 0000 000x - 1111 111x
- Group of Member State Data Count: The number of "Group of Member
State Data" components immediately following the Set Member State
Request TLV.
- Array of Group of Member Data Components: Each "Group of Member
State Data" component is immediately followed by Group Data
Components and its Member State Instance components (as described in
Section 4.3). In the case where several "Group of Member
State Data" components may be present, the second "Group of Member
State Data" component only appears after all of the internal
components that are referred to by the first "Group of Member State
Data" component are listed. The format is the same for all
subsequent "Group of Member State Data" components in the message.
[Page 21]
Server/Application State Protocol June 2004
Set Member State Reply
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Set Member State Reply(0x1025)|Size of SetMemberStateReply TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Return Code |
+-+-+-+-+-+-+-+-+
- Return Code: A byte return code indicating the status of action
taken.
General SASP return codes (0x00 - 0x3F)
---------------------------------------
0x00 Successful
0x10 Message not understood
0x11 Sender not authorized to set member state
Message Specific return codes (0x40 - 0xFF)
-------------------------------------------
0x41 Application or System not registered
0x42 Unknown Group Name
0x43 Unknown LB uid
0x44 Duplicate Member in Request
0x46 Duplicate Group in Request (for remove all members/groups
requests)
0x50 Invalid Group Name Size (size == 0)
0x51 Invalid LB uid Size (size == 0 or than max)
0x60 Member is setting state for itself, but LB does not trust
member-initiated state setting. This request will
not be processed.
0x61 Member is setting state for itself, but LB hasn't yet
contacted the GWM. This request will not be processed.
5.6 Set Load Balancer State Request and Reply
This is an exchange that can take place between the load balancer and
the Group Workload Manager to pass information about the state (and
partial configuration) of the load balancer.
[Page 22]
Server/Application State Protocol June 2004
Set LB State Request
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Set LB State Req. Type (0x1050)| Size of Set LB State Req. TLV |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| LB UID Length | |
+-+-+-+-+-+-+-+-+ +
. .
. LB UID .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| LB Health | LB Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
- LB UID Length: one byte length field describing the size of the
following LB UID.
- LB UID: This should be the same unique identifier given when
registering group members for this particular load balancer.
- LB Health: This field gives the load balancer a chance to pass in a
metric describing its own health or state.
0x00 - 0x7F Least Healthy - Most Healthy
0x80 - 0xFF Reserved
- LB Flags:
a) Push Flag
xxxx xxx1 The Load Balancer should receive weights through the
Send Weights message. (GWM pushes weights to Load
Balancer)
xxxx xxx0 The Load Balancer will send a Get Weights message to
get the new weights. This is the default behavior.
(Load Balancer pulls weights from GWM).
b) Trust Flag
xxxx xx1x Trust any member-initiated registration,
deregistration, or set state message. Immediately
reflect the registration, deregistration, or new state
in the weights sent.
xxxx xx0x Do not trust any member-initiated registration,
deregistration, or set state message. Registration,
Deregistration, and State Setting of members can only
occur from the Load Balancer. Discard any
member-initiated registration, deregistration, or set
state message. This is the default behavior.
[Page 23]
Server/Application State Protocol June 2004
c) No Change / No Send Flag
xxxx x1xx The GWM must not include members whose weights and
state (i.e. contact and quiesce flags) have not
changed since the last time period.
xxxx x0xx The GWM must include the weights of all group members
when sending the weights to this load balancer
(including members whose weights and state have not
changed). This is the default behavior.
d) Leftmost five bits are reserved 0000 0xxx - 1111 1xxx
Set LB State Reply
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
. .
. SASP Header TLV .
. .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Set LB State Reply (0x1025) | Size of Set LB State Reply TLV|
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Return Code |
+-+-+-+-+-+-+-+-+
- Return Code: A byte return code indicating the status of action
taken.
General SASP return codes (0x00 - 0x3F)
---------------------------------------
0x00 Successful
0x10 Message not understood
0x11 Sender not authorized to set member state
Message Specific return codes (0x40 - 0xFF)
-------------------------------------------
0x51 Invalid LB uid Size (size == 0 or than max)
6. Example of SASP Message Encoding
This section is to provide an example of the actual SASP message
encoding. For this example, we will look at a sample GetWeights
Reply in which two webservers are registered to a serverfarm called
FARM1. The IP addresses of the two webservers are 10.10.10.1 and
10.10.10.2. Currently the GWM has a weight of 40 for 10.10.10.1 and
20 for 10.10.10.2. The Load Balancer has a unique Identifier of
"LB1" and the message example was sent by the GWM in response to a
request (MessageID: 0x32000000) for FARM1's weights.
[Page 24]
Server/Application State Protocol June 2004
The TLVs necessary for this message are shown in the following list.
1) SASP Header TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x2010 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x000D |
|-----------|---------|------------|
| | Version | 1 byte | 0x01 |
| |---------|---------|------------|
|V| Mesg Len| 4 bytes | 0x0000 006A|
| |---------|---------|------------|
| | Mesg ID | 4 bytes | 0x3200 0000|
------------------------------------
2) Get Weights Reply TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x1035 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x0009 |
|-----------|---------|------------|
| | RetCode | 1 byte | 0x00 |
| |---------|---------|------------|
|V| Interval| 2 bytes | 0x0040 |
| |---------|---------|------------|
| |GWD Count| 2 bytes | 0x0001 |
------------------------------------
3) Group of Weight Data TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x4011 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x0006 |
|-----------|---------|------------|
|V| WE Count| 2 bytes | 0x0002 |
------------------------------------
[Page 25]
Server/Application State Protocol June 2004
4) Group Data TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x3011 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x000E |
|-----------|---------|------------|
| |LB ID len| 1 byte | 0x03 |
| |---------|---------|------------|
| | LB ID |<=64bytes| "LB1" or |
| | | | 0x4C 42 31 |
|V|---------|---------|------------|
| |GroupName| 1 byte | 0x05 |
| | Length | | |
| |---------|---------|------------|
| | Group |<=255 | "FARM1" or |
| | Name | bytes | 0x46 41 52 |
| | | | 4D 31 |
------------------------------------
5) Member Data TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x3010 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x0018 |
|-----------|---------|------------|
| | Protocol| 1 byte | 0x06 |
| |---------|---------|------------|
| | Port | 2 bytes | 0x0050 |
| |---------|---------|------------|
|V| IP |16 bytes | 0x0000 0000|
| | Address | | 0000 0000|
| | | | 0000 0000|
| | | | 0A0A 0A01|
| |---------|---------|------------|
| |Label Len| 1 byte | 0x00 |
| |---------|---------|------------|
| | Label |<=255byte| |
------------------------------------
[Page 26]
Server/Application State Protocol June 2004
6) Weight Entry Data TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x3012 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x0008 |
|-----------|---------|------------|
| | State | 1 byte | 0x00 |
| |---------|---------|------------|
|V| Flags | 1 byte | 0x05 |
| |---------|---------|------------|
| | Weight | 2 bytes | 0x0028 |
------------------------------------
7) Member Data TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x3010 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x0018 |
|-----------|---------|------------|
| | Protocol| 1 byte | 0x06 |
| |---------|---------|------------|
| | Port | 2 bytes | 0x0050 |
| |---------|---------|------------|
|V| IP |16 bytes | 0x0000 0000|
| | Address | | 0000 0000|
| | | | 0000 0000|
| | | | 0A0A 0A02|
| |---------|---------|------------|
| |Label Len| 1 byte | 0x00 |
| |---------|---------|------------|
| | Label |<=255byte| |
------------------------------------
8) Weight Entry TLV
------------------------------------
| | Field | Size | Value |
|-----------|---------|------------|
|T| Type | 2 bytes | 0x3012 |
|-----------|---------|------------|
|L| Length | 2 bytes | 0x0008 |
|-----------|---------|------------|
| | State | 1 byte | 0x00 |
| |---------|---------|------------|
|V| Flags | 1 byte | 0x05 |
| |---------|---------|------------|
| | Weight | 2 bytes | 0x0014 |
------------------------------------
[Page 27]
Server/Application State Protocol June 2004
A hex stream representing this same message is below:
20 10 00 0D 01 00 00 00 6A 32 00 00 00 10 35 00 09 00 00 40
00 01 40 11 00 06 00 02 30 11 00 0E 03 4C 42 31 05 46 41 52
4D 31 30 10 00 18 06 00 50 00 00 00 00 00 00 00 00 00 00 00
00 0A 0A 0A 01 00 30 12 00 08 00 05 00 28 30 10 00 18 06 00
50 00 00 00 00 00 00 00 00 00 00 00 00 0A 0A 0A 02 00 30 12
00 08 00 05 00 14
(106 bytes)
7. Protocol Flow
This section describes the expected general flow of the SASP
messages.
7.1 Normal Protocol Flow
SASP first starts with a connection from a LB to the GWM. This is
expected to be a long running connection, and will be used for many
messages. After establishing the connection, the LB either registers
a group of members or sets a Trust flag to allow the members to
register themselves. The Trust flag is set using a Set LB State
Request (both message flows are shown below).
Registration from Load Balancer
------------ Registration Request ------------------
| |-----------------------| |
| Load | | Group Workload |
| Balancer | Registration Reply | Manager |
| |<-----------------------| |
------------ ------------------
Set LB State from Load Balancer
------------ Set LB State Request ------------------
| |-----------------------| |
| Load | | Group Workload |
| Balancer | Set LB State Reply | Manager |
| |<-----------------------| |
------------ ------------------
The connection can start with other requests, but any other request
would likely result in an error (unless this connection is a
reconnection that has happened a short period of time after the
original connection). For example, if the load balancer issues a
deregistration request as its first message, it will receive an error
because it has not registered any groups.
[Page 28]
Server/Application State Protocol June 2004
In the case of a reconnection (after the original connection was
broken), the load balancer's group information may still be in the
GWM management server. In this case, the reconnection may begin with
a deregister message, or a get weights message, or even a set state
message. The behavior of these messages will depend on whether the
data they refer to is still in the management server.
**Load Balancers which want to maintain minimal state information may
want to begin their connections with deregistration messages to
assure a clean state for configuration. Starting the connection in
this manner after a broken connection may cause applications that were
allowed to register themselves to be deregistered with no feedback to
the application.
Registration of group members may be done at any time. A load
balancer can register anywhere from one group with one member to many
groups of many members. The member may also register itself if the
Trust flag has been set and it knows the appropriate load balancer
information. Registrations will add to groups that already exist,
but return errors if any of the registered members already exist.
In the case of System Load Balancing, the representation of a member
is only the member's IP address with a 0 used as the value for the
port and protocol.
In the case of Application Load Balancing, the representation of a
member is the member's IP address and the Application's port and
protocol.
Deregistration of group members may be done at any time. A load
balancer can deregister anywhere from one group with one member to
many groups of many members. The LB may also deregister entire
groups or deregister all of its groups at once. The member may also
deregister itself if the Trust flag has been set and it knows the
appropriate load balancer information.
Once members are registered, the GWM will start the monitoring and
weight computation processes to determine weights to be sent back to
the load balancer. At any time the load balancer may issue a
GetWeights message and ask for the weights for members in a
particular group. The LB may also set a flag telling the GWM to send
the weights without waiting for the GetWeights message. If this flag
is set, the GWM will send the weights at an interval it feels is
appropriate (the interval could change depending on the algorithm
used and variance of the weights generated).
At any time the LB or a particular member may quiesce the member
through the use of a SetMemberState message. In this case, the
member's weight will always be zero and the quiesce turned on when
sending its weight. Members may also use this message to send an
opaque state value which will also be presented when sending weights.
[Page 29]
Server/Application State Protocol June 2004
At any time the load balancer may choose to send the GWM a SetLBState
request to configure its interaction. The message allows the load
balancer to set the Push, Trust, and NoChange_NoSend flags. It also
allows the load balancer to pass a health value to the GWM to be
displayed.
7.2 Behavior in Error Cases
While behaviors in many error conditions will be product specific,
the following error cases should have the following expected
behavior.
Case: The protocol is violated in an unrecoverable manner by either
end of the connection.
Behavior: Either end of the connection may choose to disconnect to
avoid future message synchronization problems. The state kept when
disconnected is vendor specific.
Case: LB or application attempts to connect to the GWM before the
GWM is fully up and running.
Behavior: The LB or application should wait at least 20 seconds to
retry the connection.
Case: Members attempt to register or deregister themselves before
the LB develops the connection with the GWM.
Behavior: In this case, the members would receive a reply with an
error code signifying that there is no LB registered with that UID.
Case: Member registers or deregisters for a LB who has not set the
Trust flag.
Behavior: GWM will send Member a reply containing an error code.
Case: LB asks for weights for a group that doesn't exist.
Behavior: GWM will send LB a reply containing an error code.
Case: LB or Member attempts to register a member that is already
registered in that group.
Behavior: GWM will send sender a reply containing an error code.
Case: LB or Member attempts to deregister a member or group that
doesn't exist.
Behavior: GWM will send sender a reply containing an error code.
Case: LB or Member tries to set state for a non-registered server.
Behavior: GWM will send sender a reply containing an error code.
Case: LB tries to Get Weights for an unregistered group.
Behavior: GWM will send LB a reply containing an error code.
Case: Member sends the GWM a Get Weights or Set LB State Request.
Behavior: GWM will send the Member a reply containing an error
code.
[Page 30]
Server/Application State Protocol June 2004
7.3 Example Flow 1: Load Balancer Registration, Getting Weights, and
Application-Side Quiescing
Load Group Workload
Balancer Manager
| |
| 1) Registration Request |
|------------------------|
|<------------------------|
| Registration Reply |
| |
| 2) Set LB State Request |
|------------------------|
|<------------------------|
| Set LB State Reply |
| |
| 3) Get Weights Request |
|------------------------|
|<------------------------|
| Get Weights Reply |
| | 4) Set Member State Req. --------
| |<-------------------------|Member|
| |-------------------------| A |
| | Set Member State Reply --------
| |
| | 5) Set Member State Req. --------
| |<-------------------------|Member|
| |-------------------------| C |
| | Set Member State Reply --------
| |
| 6) Get Weights Request |
|------------------------|
|<------------------------|
| Get Weights Reply |
| |
| | 7) Set Member State Req. --------
| |<-------------------------|Member|
| |-------------------------| C |
| | Set Member State Reply --------
| |
| 8) Get Weights Request |
|------------------------|
|<------------------------|
| Get Weights Reply |
| |
1) The LB registers Members A, B, and C in a group named GRP1. The
GWM replies with no error.
2) The LB turns its trust flag on by issuing a Set LB State message:
LB Health: 0x00 Flags: 0000 0010
[Page 31]
Server/Application State Protocol June 2004
3) The LB sends a Get Weights message for GRP1, gets reply:
Members Opaque State Flags Weight
-------- ------------ --------- ------
Member A 0x00 0000 0101 20
Member B 0x00 0000 0101 40
Member C 0x00 0000 0101 5
4) Member A sends a Set Member State message with flags:
Members Opaque State Flags
-------- ------------ ---------
Member A 0x32 0000 0000
5) Member C sends a Set Member State message to quiesce itself with
the following flags:
Members Opaque State Flags
-------- ------------ ---------
Member C 0x0A 0000 0001
6) The LB sends the Get Weights message for GRP1 and receives the
following:
Members Opaque State Flags Weight
-------- ------------ --------- ------
Member A 0x32 0000 0101 20
Member B 0x00 0000 0101 40
Member C 0x0A 0000 0111 5
7) Member C sends a Set Member State message to resume (un-quiesce
itself) with the following flags:
Members Opaque State Flags
-------- ------------ ---------
Member C 0x0A 0000 0000
8) The LB sends a Get Weights message for GRP1 and gets the reply:
Members Opaque State Flags Weight
-------- ------------ --------- ------
Member A 0x32 0000 0101 20
Member B 0x00 0000 0101 40
Member C 0x0A 0000 0101 5
[Page 32]
Server/Application State Protocol June 2004
7.4 Example Flow 2: Set Load Balancer State, Application Registration,
and Load Balancer Group DeRegistration
Load Group Workload
Balancer Manager
| |
| 1) Set LB State Request |
|------------------------|
|<------------------------|
| Set LB State Reply |
| |
| | 2) Registration Request --------
| |-------------------------|Member|
| |<-------------------------| A |
| | Registration Reply --------
| |
| | 3) Registration Request --------
| |-------------------------|Member|
| |<-------------------------| B |
| | Registration Reply --------
| |
| 4) Send Weights Mesg |
|<------------------------|
| |
| | 5) Registration Request --------
| |-------------------------|Member|
| |<-------------------------| C |
| | Registration Reply --------
| |
| 6) Send Weights Mesg |
|<------------------------|
| |
|7) Deregistration Request|
|------------------------|
|<------------------------|
| Deregistration Reply |
| |
1) The LB sets its state with the Set LB State message and the
following parameters.
LB Health: 0x7F Flags: 0000 0011
2) Member A registers itself for work in GRP1 using the Register
message.
3) Member B registers itself for work in GRP1 using the Register
message
[Page 33]
Server/Application State Protocol June 2004
4) The GWM issues a Send Weights message to the LB
Members Opaque State Flags Weight
-------- ------------ --------- ------
Member A 0x00 0000 0001 20
Member B 0x00 0000 0001 40
5) Member C registers itself for work in GRP1 using the Register
message
6) The GWM issues a Send Weights message to the LB
Members Opaque State Flags Weight
-------- ------------ --------- ------
Member A 0x00 0000 0001 20
Member B 0x00 0000 0001 40
Member C 0x00 0000 0001 5
7) LB deregisters GRP1 by using the DeRegister message with the
Member Data Count = 0
Security Considerations
SASP is a binary stream expected to be transported over a TCP
connection. To secure this protocol, it is expected that
implementers of the protocol use a secure mode of transport such as
SSL/TLS.
References
[i] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997
[ii] Hinden, R. and Deering, S., "Internet Protocol Version 6
(IPv6) Addressing Architecture", RFC 3513, April 2003
[iii] Reynolds, J. and Postel, J., "Assigned Numbers",
RFC 1700, October 1994
Author's Addresses
Alan Bivens
IBM TJ Watson Research Center
19 Skyline Drive
Hawthorne, NY 10532
Phone: (914)784-7624
Email: jbivens@us.ibm.com
[Page 34]
Server/Application State Protocol June 2004
Full Copyright Statement
Copyright (C) The Internet Society (2004). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
[Page 35]
Server/Application State Protocol June 2004