Internet DRAFT - draft-ietf-rserpool-api
draft-ietf-rserpool-api
Network Working Group A. Silverton
Internet-Draft Q. Xie
Expires: April 20, 2006 Motorola
M. Tuexen
Muenster Univ. of Applied Sciences
T. Dreibholz
University of Duisburg-Essen
October 17, 2005
Reliable Server Pooling Sockets API Extensions
draft-ietf-rserpool-api-00.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
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.
This Internet-Draft will expire on April 20, 2006.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This document describes a sockets-like API for the Reliable Server
Pooling (RSerPool) protocol suite. This API provides applications
within an RSerPool enabled system with a reliable communications
layer via a highly-available socket interface (rsp_socket).
Silverton, et al. Expires April 20, 2006 [Page 1]
Internet-Draft RSerPool API October 2005
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Send and Receive Data with HA Sockets . . . . . . . . . . . . 3
2.1. Send Message By Pool Handle . . . . . . . . . . . . . . . 4
2.2. Send Message By Pool Element Handle . . . . . . . . . . . 4
3. Socket Utility Functions . . . . . . . . . . . . . . . . . . . 5
4. RSerPool Utility Functions . . . . . . . . . . . . . . . . . . 5
5. Example API Usage . . . . . . . . . . . . . . . . . . . . . . 6
5.1. An ECHO Pool Element . . . . . . . . . . . . . . . . . . . 7
5.2. An ECHO Pool User . . . . . . . . . . . . . . . . . . . . 8
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
9.1. Normative References . . . . . . . . . . . . . . . . . . . 9
9.2. Informative References . . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Intellectual Property and Copyright Statements . . . . . . . . . . 11
Silverton, et al. Expires April 20, 2006 [Page 2]
Internet-Draft RSerPool API October 2005
1. Introduction
This document describes a sockets-like API for the Reliable Server
Pooling (RSerPool) protocol suite. This API provides applications
within an RSerPool enabled system [2] with a reliable communications
layer via a highly-available socket interface (rsp_socket).
The RSerPool API is intended to mimic the well-known UNIX sockets
API. The functions in this proposed extension to the sockets API are
prefixed with "rsp_" to signify that they are highly-available
RSerPool API calls. Some new utility functions are defined as well.
The API is intended to be extensible.
2. Send and Receive Data with HA Sockets
The UNIX sockets API contains several functions for sending and
receiving data, e.g., send/recv, writev/readv, etc. Here we provide
RSerPool analogs of the most general of the IO functions, sendmsg and
recvmsg (we pick this pair just to illustrate our general approach.
More careful thinking should be put in here before deciding the exact
syntax we will use for HA sockets).
The intention is to retain as much as possible the basic UNIX
programming model that many UNIX programmers have been familiar with.
However, the semantics may be changed since we do not see the benefit
for strictly mapping the semantics from UNIX sockets API.
The following API call is used for sending a message with HA socket.
ssize_t rsp_sendmsg(int sockfd, /* HA socket descriptor */
struct msghdr *msg, /* message header struct */
int flags); /* Options flags */
The following API call is used for receiving a message with HA
socket.
ssize_t rsp_rcvmsg(int sockfd, /* HA socket descriptor */
struct msghdr *msg, /* msg header struct */
int flags); /* Options flags */
The msg header stucture has RSERPOOL specific semantics.
Silverton, et al. Expires April 20, 2006 [Page 3]
Internet-Draft RSerPool API October 2005
struct msghdr {
void *msg_name; /* RSERPOOL destination name */
int msg_namelen; /* Length of name */
struct iovec *msg_iov; /* Data blocks */
size_t msg_iovlen; /* Number of blocks */
void *msg_control; /* RSERPOOL specific ancillary
data */
size_t msg_controllen; /* Length of cmsg data */
unsigned msg_flags; /* RSERPOOL specific flags
returned by recvmsg */
};
For example, the *msg_name can be a pointer to a NULL terminated
string that indicates the destination pool handle, or it can be a
pointer to a structure that indicates a PE handle in a specific pool.
The use of *msg_control and msg_flags parameter is TBD. Some
examples are, we can use them to indicate whether this message is
allowed for failover, etc., or to use them to return a pointer to a
PE handle indicating to whom the message was actually sent.
2.1. Send Message By Pool Handle
Using rsp_sendmsg to send to a pool handle:
....
struct msghdr myMsg;
char destinationPool[255];
....
strcpy(destinationPool, "IETF-RSERPOOL-Server-cluster");
myMsg.msg_name = destinationPool;
myMsg.msg_namelen = strlen(destinationPool) + 1;
/* set up the data pointer here */
myMsg.msg_flags = FAILOVER_ALLOWED;
....
ret = rsp_sendmsg(sock, &myMsg, myFlags);
....
(Should this go in the example section?)
2.2. Send Message By Pool Element Handle
Using rsp_sendmsg to send to a specific PE handle (and the sender
does not allow failover of this message):
Silverton, et al. Expires April 20, 2006 [Page 4]
Internet-Draft RSerPool API October 2005
....
struct msghdr myMsg;
struct sockaddr_pehandle destPE; /* feilds TBD */
....
/* (somehow) obtain and fill in destPE struct here */
myMsg.msg_name = &destPE;
myMsg.msg_namelen = sizeof(destPE);
/* set up the data pointer here */
myMsg.msg_flags = FAILOVER_NOT_ALLOWED;
....
ret = rsp_sendmsg(sock, &myMsg, myFlags);
....
(Should this go in the example section?)
3. Socket Utility Functions
These calls provide the basic functionality for controlling RSerPool
HA sockets and obtaining information about active sockets.
rsp_socket(): This call sets up necessary ASAP resources for this HA
socket and returns a socket fd to the caller.
ssize_t rsp_socket(TBD);
rsp_close(): This call closes the specified HA socket (and releases
the ASAP resources associated to this HA socket).
ssize_t rsp_close(int sockfd);
rsp_connect(): One possibility here is to use this call to pre-fetch
the pool information. The caller can put the destination pool handle
in the parameter when making this call, and the ASAP layer will query
the Pool Registrar for the named pool and if successful will store
the query result in its local cache. If the named pool does not
exist in the Pool Registrar, an error is then returned to the caller
of connect().
ssize_t rsp_connect(sockfd, TBD);
4. RSerPool Utility Functions
A number of utility functions, not directly related to data IO, but
Silverton, et al. Expires April 20, 2006 [Page 5]
Internet-Draft RSerPool API October 2005
necessary all the same, are defined for the RSerPool sockets
interface.
rsp_register(): This function call is used to registry a PE as a
member of a pool. This call should be after socket();
ssize_t rsp_register(sockfd, TBD);
rsp_deregister(): This function call is used to remove, or
deregister, a PE from a pool.
ssize_t rsp_deregister(sockfd, TBD);
rsp_getpoolinfo(): The caller uses this to get the details of a pool.
The call should return a full PE list, together with the pool policy,
PE load factor, etc. to the caller. This can be the base for the
basic mode operation (see the service draft) in which the user of
RSERPOOL chooses to handle its own data sending but using RSERPOOL
only for resolving pool handles.
struct TBD rsp_getPoolInfo(sockfd, TBD);
rsp_reportpefailure(): This call is used by an PU and PE to report an
unreachable PE in a pool.
ssize_t rsp_reportfailure(sockfd, TBD);
rsp_notify(): A notify function is needed to pass various RSERPOOL as
well as lower layer events back to the HA socket user. Maybe we can
model the notification mechanism after the SCTP socket extension?
This is just a placeholder.
ssize_t rsp_notify(TBD);
rsp_forcefailover(): Not sure if this is really necessary as a
separate API call, however, this functionality is needed to allow
user of RSERPOOL to trigger a failover (the upper layer may want to
take over the failure detection from RSERPOOL).
ssize_t rsp_forcefailover(sockfd, TBD);
5. Example API Usage
This section demonstrates the usage of the RSerPool API.
Silverton, et al. Expires April 20, 2006 [Page 6]
Internet-Draft RSerPool API October 2005
5.1. An ECHO Pool Element
int main()
{
int fd;
struct sockaddr_in server_addr;
struct rsp_info info;
struct rsp_sndrcvinfo sinfo;
struct rsp_loadinfo linfo;
int len;
char buf[1<<16];
/* initialize the RSerPool implementation */
memset(&info, 0, sizeof(struct rsp_info));
rsp_initialize(&info);
/* we want to provide an SCTP based echo server */
fd = rsp_socket(AF_INET, SOCK_DGRAM, IPPROTO_SCTP);
/* we want to use all addresses and use the standard port number */
memset(&server_addr, 0, sizeof(server_addr));
server_addr.sin_family = AF_INET;
#ifdef HAVE_SIN_LEN
server_addr.sin_len = sizeof(struct sockaddr_in);
#endif
server_addr.sin_addr.s_addr = htonl(INADDR_ANY);
server_addr.sin_port = htons(7);
rsp_bind(fd, (const struct sockaddr *) &server_addr, sizeof(server_addr));
/* we need to register ourself */
memset(&linfo, 0, sizeof(struct rsp_loadinfo);
linfo.policy = RSP_ROUND_ROBIN;
rsp_register(fd, "echo", 4, &linfo);
/* send back all received messages */
while (1) {
memset(&sinfo, 0, sizeof(struct rsp_sndrcvinfo));
len = rsp_recvmsg(fd, (void *) buf, sizeof(buf), &sinfo, 0);
rsp_sendmsg(fd, (const void *) buf, len, sinfo, 0);
}
/* the deregistration would also be done implicitly by rsp_close() */
rsp_deregister(fd);
rsp_close(fd);
rsp_cleanup();
}
Silverton, et al. Expires April 20, 2006 [Page 7]
Internet-Draft RSerPool API October 2005
5.2. An ECHO Pool User
int main()
{
int fd, n, done;
struct rsp_info info;
fd_set rset;
char buf[1<<16];
/* initialize the RSerPool implementation */
memset(&info, 0, sizeof(struct rsp_info));
rsp_initialize(&info);
/* we want to provide an SCTP based echo server */
fd = rsp_socket(AF_INET, SOCK_DGRAM, IPPROTO_SCTP);
/* set the destination */
rsp_connect(fd, "echo", 4);
done = 0;
FD_ZERO(&rset);
while(!done) {
FD_SET(0, &rset);
FD_SET(fd, &rset);
/* wait for a packet from the server of stdin input */
rsp_select(fd + 1, &rset, (fd_set *) NULL, (fd_set *), NULL, (struct timeval *) NULL);
if (FD_ISSET(0, &rset)) {
n = Read(0, (void *) buf, sizeof(buf));
if (n == 0)
done = 1;
else
rsp_sendmsg(fd, (const void *) buf, len, NULL, 0);
}
if (FD_ISSET(fd, &rset)) {
n = rsp_recvmsg(fd, (void *) buf, sizeof(buf), NULL, 0);
if(n > 0)
printf("%s", buf);
}
}
rsp_close(fd);
rsp_cleanup();
}
Silverton, et al. Expires April 20, 2006 [Page 8]
Internet-Draft RSerPool API October 2005
6. Security Considerations
The security threat analysis of RSerPool is found in [5]. This
document does not introduce any new threats.
7. IANA Considerations
None
8. Acknowledgements
9. References
9.1. Normative References
[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
9.2. Informative References
[2] Tuexen, M., Xie, Q., Stewart, R., Shore, M., and J. Loughney,
"Architecture for Reliable Server Pooling",
draft-ietf-rserpool-arch-07 (work in progress), October 2003.
[3] Stewart, R., Xie, Q., Stillman, M., and M. Tuexen, "Aggregate
Server Access Protocol (ASAP)", draft-ietf-rserpool-asap-09
(work in progress), June 2004.
[4] Xie, Q., Stewart, R., and M. Stillman, "Endpoint Name Resolution
Protocol (ENRP)", draft-ietf-rserpool-enrp-08 (work in
progress), June 2004.
[5] Stillman, M., "Threats Introduced by Rserpool and Requirements
for Security in Response to Threats",
draft-ietf-rserpool-threats-02 (work in progress), Sept 2003.
Silverton, et al. Expires April 20, 2006 [Page 9]
Internet-Draft RSerPool API October 2005
Authors' Addresses
Aron J. Silverton
Motorola, Inc.
1301 E. Algonquin Road
Room 2246
Schaumburg, IL 60196
US
Phone: +1 847-576-8747
Email: aron.j.silverton@motorola.com
Qiaobing Xie
Motorola, Inc.
1501 W. Shure Drive, 2-F9
Arlington Heights, IL 60004
US
Phone: +1 847-632/3028
Email: qxie1@email.mot.com
Michael Tuexen
Muenster University of Applied Sciences
Stegerwaldstrasse 39
48565 Steinfurt
Germany
Email: tuexen@fh-muenster.de
Thomas Dreibholz
University of Duisburg-Essen, Institute for Experimental Mathematics
Ellernstrasse 29
45326 Essen, Nordrhein-Westfalen
Germany
Phone: +49 201 183-7637
Fax: +49 201 183-7673
Email: dreibh@exp-math.uni-essen.de
URI: http://www.exp-math.uni-essen.de/~dreibh/
Silverton, et al. Expires April 20, 2006 [Page 10]
Internet-Draft RSerPool API October 2005
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Disclaimer of Validity
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.
Copyright Statement
Copyright (C) The Internet Society (2005). 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.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Silverton, et al. Expires April 20, 2006 [Page 11]
