Network Working Group A. Silverton Internet-Draft Q. Xie Expires: April 14, 2005 Motorola M. Tuexen Muenster Univ. of Applied Sciences T. Dreibholz University of Duisburg-Essen October 14, 2004 Reliable Server Pooling Sockets API Extensions draft-silverton-rserpool-api-00.txt Status of this Memo This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. 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 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. This Internet-Draft will expire on April 14, 2005. Copyright Notice Copyright (C) The Internet Society (2004). 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 Silverton, et al. Expires April 14, 2005 [Page 1] Internet-Draft RSerPool API October 2004 layer via a highly-available socket interface (rsp_socket). 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 . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . . 9 Intellectual Property and Copyright Statements . . . . . . . . 11 Silverton, et al. Expires April 14, 2005 [Page 2] Internet-Draft RSerPool API October 2004 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 14, 2005 [Page 3] Internet-Draft RSerPool API October 2004 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 14, 2005 [Page 4] Internet-Draft RSerPool API October 2004 .... 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 necessary all the same, are defined for the RSerPool sockets Silverton, et al. Expires April 14, 2005 [Page 5] Internet-Draft RSerPool API October 2004 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. 5.1 An ECHO Pool Element Silverton, et al. Expires April 14, 2005 [Page 6] Internet-Draft RSerPool API October 2004 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 14, 2005 [Page 7] Internet-Draft RSerPool API October 2004 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 14, 2005 [Page 8] Internet-Draft RSerPool API October 2004 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 14, 2005 [Page 9] Internet-Draft RSerPool API October 2004 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 14, 2005 [Page 10] Internet-Draft RSerPool API October 2004 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 (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. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Silverton, et al. Expires April 14, 2005 [Page 11]