[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01

Network Working Group                                       A. Silverton
Internet-Draft                                                    Q. Xie
Expires: January 20, 2006                                       Motorola
                                                               M. Tuexen
                                      Muenster Univ. of Applied Sciences
                                                            T. Dreibholz
                                            University of Duisburg-Essen
                                                           July 17, 2005


             Reliable Server Pooling Sockets API Extensions
                  draft-silverton-rserpool-api-01.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 January 18, 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 January 18, 2006                [Page 1]


Internet-Draft                RSerPool API                     July 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 . . . . . . . . . . . . . . . . . . .  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 . . . . . . . . . . . . . . . . . . . . . . 10
       Intellectual Property and Copyright Statements . . . . . . . . 11
































Silverton, et al.       Expires January 18, 2006                [Page 2]


Internet-Draft                RSerPool API                     July 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 an 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 an 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 January 18, 2006                [Page 3]


Internet-Draft                RSerPool API                     July 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
   potential uses are: 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 January 18, 2006                [Page 4]


Internet-Draft                RSerPool API                     July 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
   necessary all the same, are defined for the RSerPool sockets



Silverton, et al.       Expires January 18, 2006                [Page 5]


Internet-Draft                RSerPool API                     July 2005


   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.  This is just
   a placeholder and requires more thought.

     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 January 18, 2006                [Page 6]


Internet-Draft                RSerPool API                     July 2005


   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 January 18, 2006                [Page 7]


Internet-Draft                RSerPool API                     July 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 January 18, 2006                [Page 8]


Internet-Draft                RSerPool API                     July 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., Loughney, J., and
        A. Silverton, "Architecture for Reliable Server Pooling",
        draft-ietf-rserpool-arch-10 (work in progress), July 2005.

   [3]  Stewart, R., Xie, Q., Stillman, M., and M. Tuexen, "Aggregate
        Server Access Protocol (ASAP)", draft-ietf-rserpool-asap-12
        (work in progress), July 2005.

   [4]  Xie, Q., Stewart, R., Stillman, M., Tuexen, M., and A.
        Silverton, "Endpoint Name Resolution Protocol (ENRP)",
        draft-ietf-rserpool-enrp-12 (work in progress), July 2005.

   [5]  Stillman, M., "Threats Introduced by Rserpool and Requirements
        for Security in Response to Threats",
        draft-ietf-rserpool-threats-05 (work in progress), July 2005.















Silverton, et al.       Expires January 18, 2006                [Page 9]


Internet-Draft                RSerPool API                     July 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 January 18, 2006               [Page 10]


Internet-Draft                RSerPool API                     July 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 January 18, 2006               [Page 11]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/