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

Versions: 00 01 02 03 04 05 06 draft-irtf-samrg-common-api

SAM Research Group                                          M. Waehlisch
Internet-Draft                                      link-lab & FU Berlin
Intended status: Informational                              T C. Schmidt
Expires: January 13, 2011                                    HAW Hamburg
                                                               S. Venaas
                                                           cisco Systems
                                                           July 12, 2010


             A Common API for Transparent Hybrid Multicast
                   draft-waehlisch-sam-common-api-03

Abstract

   Group communication services exist in a large variety of flavors and
   technical implementations.  Multicast data distribution is most
   efficiently performed on the lowest available layer, but a varying
   deployment status of multicast technologies throughout the Internet
   restricts service binding to runtime.  Today, it is difficult to
   write an application that runs everywhere and at the same time makes
   use of the most efficient multicast service available in the network.
   Facing robustness requirements, developers are frequently forced to
   using a stable, upper layer protocol controlled by the application
   itself.  This document describes a common multicast API that is
   suitable for transparent communication in underlay and overlay, and
   grants access to the different multicast flavors.  It proposes an
   abstract naming by multicast URIs and discusses mapping mechanisms
   between different namespaces and distribution technologies.
   Additionally, it describes the application of this API for building
   gateways that interconnect current multicast domains throughout the
   Internet.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

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

   This Internet-Draft will expire on January 13, 2011.



Waehlisch, et al.       Expires January 13, 2011                [Page 1]

Internet-Draft              Common Mcast API                   July 2010


Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.





































Waehlisch, et al.       Expires January 13, 2011                [Page 2]

Internet-Draft              Common Mcast API                   July 2010


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  5
   3.  Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
     3.1.  Objectives and Reference Scenarios . . . . . . . . . . . .  6
     3.2.  Group Communication API & Protocol Stack . . . . . . . . .  7
     3.3.  Naming and Addressing  . . . . . . . . . . . . . . . . . .  9
     3.4.  Mapping  . . . . . . . . . . . . . . . . . . . . . . . . . 10
   4.  Common Multicast API . . . . . . . . . . . . . . . . . . . . . 11
     4.1.  Abstract Data Types  . . . . . . . . . . . . . . . . . . . 11
       4.1.1.  Multicast URI  . . . . . . . . . . . . . . . . . . . . 11
       4.1.2.  Interface  . . . . . . . . . . . . . . . . . . . . . . 11
     4.2.  Group Management Calls . . . . . . . . . . . . . . . . . . 12
       4.2.1.  Create . . . . . . . . . . . . . . . . . . . . . . . . 12
       4.2.2.  Join . . . . . . . . . . . . . . . . . . . . . . . . . 12
       4.2.3.  Leave  . . . . . . . . . . . . . . . . . . . . . . . . 13
       4.2.4.  Source Register  . . . . . . . . . . . . . . . . . . . 13
       4.2.5.  Source Deregister  . . . . . . . . . . . . . . . . . . 13
     4.3.  Send and Receive Calls . . . . . . . . . . . . . . . . . . 14
       4.3.1.  Send . . . . . . . . . . . . . . . . . . . . . . . . . 14
       4.3.2.  Receive  . . . . . . . . . . . . . . . . . . . . . . . 14
     4.4.  Socket Options . . . . . . . . . . . . . . . . . . . . . . 15
       4.4.1.  Get Interfaces . . . . . . . . . . . . . . . . . . . . 15
       4.4.2.  Add Interface  . . . . . . . . . . . . . . . . . . . . 15
       4.4.3.  Delete Interface . . . . . . . . . . . . . . . . . . . 15
       4.4.4.  Set TTL  . . . . . . . . . . . . . . . . . . . . . . . 16
     4.5.  Service Calls  . . . . . . . . . . . . . . . . . . . . . . 16
       4.5.1.  Group Set  . . . . . . . . . . . . . . . . . . . . . . 16
       4.5.2.  Neighbor Set . . . . . . . . . . . . . . . . . . . . . 16
       4.5.3.  Designated Host  . . . . . . . . . . . . . . . . . . . 17
       4.5.4.  Update Listener  . . . . . . . . . . . . . . . . . . . 17
   5.  Functional Details . . . . . . . . . . . . . . . . . . . . . . 17
     5.1.  Mapping  . . . . . . . . . . . . . . . . . . . . . . . . . 17
     5.2.  Namespaces . . . . . . . . . . . . . . . . . . . . . . . . 18
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 18
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 18
   8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 18
   9.  Informative References . . . . . . . . . . . . . . . . . . . . 18
   Appendix A.  Practical Example of the API  . . . . . . . . . . . . 19
   Appendix B.  Deployment Use Cases for Hybrid Multicast . . . . . . 20
     B.1.  DVMRP  . . . . . . . . . . . . . . . . . . . . . . . . . . 21
     B.2.  PIM-SM . . . . . . . . . . . . . . . . . . . . . . . . . . 21
     B.3.  PIM-SSM  . . . . . . . . . . . . . . . . . . . . . . . . . 22
     B.4.  BIDIR-PIM  . . . . . . . . . . . . . . . . . . . . . . . . 22
   Appendix C.  Change Log  . . . . . . . . . . . . . . . . . . . . . 23
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24




Waehlisch, et al.       Expires January 13, 2011                [Page 3]

Internet-Draft              Common Mcast API                   July 2010


1.  Introduction

   Currently, group application programmers need to make a choice of the
   distribution technology required at runtime.  There is no common
   communication interface that abstracts multicast transmission and
   subscriptions from the deployment state at runtime.  The standard
   multicast socket options [RFC3493], [RFC3678] are bound to an IP
   version and do not distinguish between naming and addressing of
   multicast identifiers.  Group communication, however, is commonly
   implemented in different flavors (e.g., any source vs. source
   specific mutlicast), on different layers (e.g., IP vs. application
   layer multicast), and may be based on different technologies on the
   same tier (e.g., IPv4 vs. IPv6).  It is the objective of this
   document to provide a universal access to group services.

   Multicast application development should be decoupled of
   technological deployment throughout the infrastructure.  It requires
   a common multicast API that offers calls to transmit and receive
   multicast data independent of the supporting layer and the underlying
   technological details.  For inter-technology transmissions, a
   consistent view on multicast states is needed, as well.  This
   document describes an abstract group communication API and core
   functions necessary for transparent operations.  Specific
   implementation guidelines with respect to operating systems or
   programming languages are out-of-scope of this document.

   In contrast to the standard multicast socket interface, the API
   introduced in this document abstracts naming from addressing.  Using
   a multicast address in the current socket API predefines the
   corresponding routing layer.  In this specification, the multicast
   name used for joining a group denotes an application layer data
   stream that is identified by a multicast URI, independent of a
   binding to a specific distribution technology.  Such a group name can
   be mapped to variable routing identifiers.

   The aim of this common API is twofold:

   o  Enable any application programmer to implement group-oriented data
      communication independent of the underlying delivery mechanisms.
      In particular, allow for a late binding of group applications to
      multicast technologies that makes applications efficient, but
      robust with respect to deployment aspects.

   o  Allow for a flexible namespace support in group addressing, and
      thereby separate naming and addressing/routing schemes from the
      application design.  This abstraction does not only decouple
      programs from specific apects of underlying protocols, but may
      open application design to extend to specifically flavored group



Waehlisch, et al.       Expires January 13, 2011                [Page 4]

Internet-Draft              Common Mcast API                   July 2010


      services.

   Multicast technologies may be of various P2P kinds, IPv4 or IPv6
   network layer multicast, or implemented by some other application
   service.  Corresponding namespaces may be IP addresses, overlay
   hashes, other application layer group identifiers like <sip:*@
   peanuts.org>, or names defined by the applications.

   This document also proposes and discusses mapping mechanisms between
   different namespaces and forwarding technologies.  Additionally, the
   multicast API provides internal interfaces to access current
   multicast states at the host.  Multiple multicast protocols may run
   in parallel on a single host.  These protocols may interact to
   provide a gateway function that bridges data between different
   domains.  The application of this API at gateways operating between
   current multicast instances throughout the Internet is described, as
   well.


2.  Terminology

   This document uses the terminology as defined for the multicast
   protocols [RFC2710],[RFC3376],[RFC3810],[RFC4601],[RFC4604].  In
   addition, the following terms will be used.

   Group Address:  A Group Address is a routing identifier.  It
      represents a technological identifier and thus reflects the
      distribution technology in use.  Multicast packet forwarding is
      based on this ID.

   Group Name:  A Group Name is an application identifier that is used
      by applications to manage (e.g., join/leave and send/receive) a
      multicast group.  The Group Name does not imply any distribution
      technologies but represents a logical identifier.

   Multicast Namespace:  A Multicast Namespace is a collection of
      designators (i.e., names or addresses) for groups that share a
      common syntax.  Typical instances of namespaces are IPv4 or IPv6
      multicast addresses, overlay group ids, group names defined on the
      application layer (e.g., SIP or Email), or some human readable
      strings.

   Multicast Domain:  A Multicast Domain accommodates nodes and routers
      of a common, single multicast forwarding technology and is bound
      to a single namespace.






Waehlisch, et al.       Expires January 13, 2011                [Page 5]

Internet-Draft              Common Mcast API                   July 2010


   Interface  An Interface is a forwarding instance of a distribution
      technology on a given node.  For example, the IP interface
      192.168.1.1 at an IPv4 host.

   Inter-domain Multicast Gateway:  An Inter-domain Multicast Gateway
      (IMG) is an entity that interconnects different multicast domains.
      Its objective is to forward data between these domains, e.g.,
      between IP layer and overlay multicast.


3.  Overview

3.1.  Objectives and Reference Scenarios

   The default use case addressed in this document targets at
   applications that participate in a group by using some common
   identifier taken from some common namespace.  This group name is
   typically learned at runtime from user interaction like the selection
   of an IPTV channel, from dynamic session negotiations like in the
   Session Initiation Protocol (SIP), but may as well have been
   predefined for an application as a common group name.  Technology-
   specific system functions then transparently map the group name to
   group addresses such that

   o  programmers are enabled to process group names in their programs
      without the need to consider technological mappings to designated
      deployments in target domains;

   o  applications are enabled to identify packets that belong to a
      logically named group, independent of the interface technology
      used for sending and receiving packets.  The latter shall also
      hold for multicast gateways.

   This document refers to a reference scenario that covers the
   following two hybrid deployment cases displayed in Figure 1:

   1.  Multicast domains running the same multicast technology but
       remaining isolated, possibly only connected by network layer
       unicast.

   2.  Multicast domains running different multicast technologies, but
       hosting nodes that are members of the same multicast group.









Waehlisch, et al.       Expires January 13, 2011                [Page 6]

Internet-Draft              Common Mcast API                   July 2010


                                        +-------+         +-------+
                                        | Member|         | Member|
                                        |  Foo  |         |   G   |
                                        +-------+         +-------+
                                              \            /
                                            ***  ***  ***  ***
                                           *   **   **   **   *
                                          *                    *
                                           *   MCast Tec A    *
                                          *                    *
                                           *   **   **   **   *
                                            ***  ***  ***  ***
   +-------+          +-------+                      |
   | Member|          | Member|                  +-------+
   |   G   |          |  Foo  |                  |  IMG  |
   +-------+          +-------+                  +-------+
       |                |                            |
       ***  ***  ***  ***                  ***  ***  ***  ***
      *   **   **   **   *                *   **   **   **   *
     *                    *  +-------+   *                    *
      *   MCast Tec A    * --|  IMG  |--  *   MCast Tec B    *    +-------+
     *                    *  +-------+   *                    * - | Member|
      *   **   **   **   *                *   **   **   **   *    |   G   |
       ***  ***  ***  ***                  ***  ***  ***  ***     +-------+


    Figure 1: Reference scenarios for hybrid multicast, interconnecting
    group members from isolated homogeneous and heterogeneous domains.

   It is assumed throughout the document that the domain composition, as
   well as the node attachement to a specific technology remain
   unchanged during a multicast session.

3.2.  Group Communication API & Protocol Stack

   The group communication API consists of four parts.  Two parts
   combine the essential communication functions, while the remaining
   two offer optional extensions for an enhanced management:

   Group Management Calls  provide the minimal API to instantiate a
      multicast socket and manage group membership.

   Send/Receive Calls  provide the minimal API send and receive
      multicast data in a technology-transparent fashion.







Waehlisch, et al.       Expires January 13, 2011                [Page 7]

Internet-Draft              Common Mcast API                   July 2010


   Socket Options  provide extension calls for the configuration of the
      multicast socket, i.e., setting path length and associated
      interfaces explicitly.

   Service Calls  provide extension calls that grant access to internal
      multicast states of an interface such as the multicast groups
      under subscription.

   Multicast applications that use the common API require assistance by
   a group communication stack.  This protocol stack serves two needs:

   o  It provides system-level support to transfer the abstract
      functions of the common API, including namespace support, into
      protocol operations at interfaces.

   o  It bridges data distribution between different multicast
      technologies.

   The general procedure to initiate multicast communication in this
   setting proceeds as follows:

   1.  An application opens an abstract multicast socket.

   2.  The application subscribes/leaves/sends to a group using a
       logical group identifier.

   3.  An intrinsic function of the stack maps the logical group ID
       (Group Name) to a technical group ID (Group Address).  This
       function may make use of deployment-specific knowledge such as
       available technologies and unused group addresses in its domain.

   4.  Packet distribution proceeds to and from one or several
       multicast-enabled interfaces.

   The multicast socket describes a group communication channel composed
   of one or multiple interfaces.  A socket may be created without
   explicit interface association by the application, which leaves the
   choice of the underlying forwarding technology to the group
   communication stack.  However, an application may also bind the
   socket to one or multiple dedicated interfaces, which predefines the
   forwarding technology and the namespace(s) of the Group Address(es).

   Applications are not required to maintain mapping states for Group
   Addresses.  The group communication stack accounts for the mapping of
   the Group Name to the Group Address(es) and vice versa.  Multicast
   data passed to the application will be augmented by the corresponding
   Group Name.  Multiple multicast subscriptions thus can be conducted
   on a single multicast socket without the need for Group Name encoding



Waehlisch, et al.       Expires January 13, 2011                [Page 8]

Internet-Draft              Common Mcast API                   July 2010


   at the application side.

   Hosts may support several multicast protocols.  The group
   communication stack discovers available multicast-enabled
   communication interfaces.  It provides a minimal hybrid function that
   bridges data between different interfaces and multicast domains.
   Details of service discovery are out-of-scope of this document.

   The extended multicast functions can be implemented by a middleware
   as visualized in Figure 2.

   *-------*     *-------*
   | App 1 |     | App 2 |
   *-------*     *-------*
       |             |
   *---------------------*         ---|
   |   Middleware        |            |
   *---------------------*            |
        |          |                  |
   *---------*     |                  |
   | Overlay |     |                   \  Group Communication
   *---------*     |                   /  Stack
        |          |                  |
        |          |                  |
   *---------------------*            |
   |   Underlay          |            |
   *---------------------*         ---|

    Figure 2: A middleware for offering uniform access to multicast in
                           underlay and overlay

3.3.  Naming and Addressing

   Applications use Group Names to identify groups.  Names can uniquely
   determine a group in a global communication context and hide
   technological deployment for data distribution from the application.
   In contrast, multicast forwarding operates on Group Addresses.  Even
   though both identifiers may be identical in symbols, they carry
   different meanings.  They may also belong to different namespaces.
   The namespace of a Group Address reflects a routing technology, while
   the namespace of a Group Name represents the context in which the
   application operates.

   URIs [RFC3986] are a common way to represent namespace-specific
   identifiers in applications.  Throughout this document, any kind of
   Group Name follows a URI notation with the syntax defined in
   Section 4.1.1.  Examples are, ip://224.1.2.3:5000, and
   sip://news@cnn.com.



Waehlisch, et al.       Expires January 13, 2011                [Page 9]

Internet-Draft              Common Mcast API                   July 2010


   An implementation of the group communication middleware can provide
   convenience functions that detect the namespace of a Group Name and
   use it to optimize service instantiation.  In practice, such a
   library would provide support for high-level data types to the
   application, similar to the current socket API (e.g., InetAddress in
   Java).  Using this data type could implicitly determine the
   namespace.  Details of automatic identifcation is out-of-scope of
   this document.

   A multicast socket (IPv4/v6 interface) can be used by multiple
   logical multicast IDs from different namespaces (IPv4-group address,
   IPv6-group address).

3.4.  Mapping

   Group Names require a mapping to Group Addresses prior to service
   instantiation at an Interface.  Similarly, a mapping is needed at
   gateways to translate between Group Addresses from different
   namespaces.  Some namespaces facilitate a canonical transformation to
   default address spaces.  For example, ip://224.1.2.3:5000 has an
   obvious correspondance to 224.1.2.3 in the IPv4 multicast address
   space.  Note that in this example the multicast URI can be completely
   recovered from any data packet received from this group.

   However, mapping in general can be more complex and need not be
   invertible.  Mapping functions can be stateless in some contexts, but
   may require states in others.  The application of such functions
   depends on the cardinality of the namespaces, the structure of
   address spaces, and possible address collisions.  For example, it is
   not obvious how to map a large identifier space (e.g., IPv6) to a
   smaller, collision-prone set like IPv4.

   Two (or more) Multicast Addresses from different namespaces may
   belong to

   a.  the same logical group (i.e., same Multicast Name)

   b.  different multicast channels (i.e., different technical IDs).

   This decision can be solved based on invertible mappings.  However,
   the application of such functions depends on the cardinality of the
   namespaces and thus does not hold in general.  It is not obvious how
   to map a large identifier space (e.g., IPv6) to a smaller set (e.g.,
   IPv4).

   A mapping can be realized by embedding smaller in larger namespaces
   or selecting an arbitrary, unused ID in the target space.  The
   relation between logical and technical ID is stored based on a



Waehlisch, et al.       Expires January 13, 2011               [Page 10]

Internet-Draft              Common Mcast API                   July 2010


   mapping service (e.g., DHT).  The middleware thus queries the mapping
   service first, and creates a new technical group ID only if there is
   no identifier available for the namespace in use.  The Group Name is
   associated with one or more Group Addresses, which belong to
   different namespaces.  Depending on the scope of the mapping service,
   it ensures a consistent use of the technical ID in a local or global
   domain.

   All group members subscribe to the same Group Name within the same
   namespace.


4.  Common Multicast API

4.1.  Abstract Data Types

4.1.1.  Multicast URI

   Multicast Names and Multicast Addresses follow an URI scheme that
   defines a subset of the generic URI specified in [RFC3986] and is
   compliant with the guidelines in [RFC4395].

   The multicast URI is defined as follows:

      scheme "://" group "@" instantiation ":" port "/" sec-credentials

   The parts of the URI are defined as follows:

   scheme  referes to the specification of the assigned identifier
      [RFC3986] which takes the role of the namespace.

   group  identifies the group uniquely within the namespace given in
      scheme.

   instantiation  identifies the entitiy that generates the instance of
      the group (e.g., a SIP domain or a source in SSM) using the
      namespace given in scheme.

   port  identifies a specific application at an instance of a group.

   sec-credentials  used to implement security credentials (e.g., to
      authorize a multicast group access).

4.1.2.  Interface

   The interface denotes the layer and instance on which the
   corresponding call will be effective.  In agreement with [RFC3493] we
   identify an interface by an identifier, which is a positive integer



Waehlisch, et al.       Expires January 13, 2011               [Page 11]

Internet-Draft              Common Mcast API                   July 2010


   starting at 1.

   Properties of an interface are stored in the following struct:

     struct if_prop {
       unsigned int if_index; /* 1, 2, ... */
       char        *if_name;  /* "eth0", "eth1:1", "lo", ... */
       char        *if_addr;  /* "1.2.3.4", "abc123" ... */
       char        *if_tech;  /* "ip", "overlay", ... */
     };

   The following function retrieves all available interfaces from the
   system:

     struct if_prop *if_prop(void);

   It extends the functions for Interface Identfication in [RFC3493]
   (cf., Section 4).

4.2.  Group Management Calls

4.2.1.  Create

   The create call initiates a multicast socket and provides the
   application programmer with a corresponding handle.  If no interfaces
   will be assigned based on the call, the default interface will be
   selected and associated with the socket.  The call may return an
   error code in the case of failures, e.g., due to a non-operational
   middleware.

     int createMSocket(uint32_t *if);

   The if argument denotes a list of interfaces that will be associated
   with the multicast socket.  This parameter is optional.

   On success a multicast socket identifier is returned, otherwise NULL.

4.2.2.  Join

   The join call initiates a group subscription.  Depending on the
   interfaces that are associated with the socket, this may result in an
   IGMP/MLD report or overlay subscription.

     int join(int s, const uri group_name);

   The s argument identifies the multicast socket.

   The group_name argument identifies the group.



Waehlisch, et al.       Expires January 13, 2011               [Page 12]

Internet-Draft              Common Mcast API                   July 2010


   On success the value 0 is returned, otherwise -1.

4.2.3.  Leave

   The leave call results in an unsubscription for the given Group Name.

    int leave(int s, const uri group_name);

   The s argument identifies the multicast socket.

   The group_name identifies the group.

   On success the value 0 is returned, otherwise -1.

4.2.4.  Source Register

   The srcRegister call allows sources to register for a Group Name.
   This may be helpful for the creation of sub-overlays, for example.
   This call is optional.

     int srcRegister(int s, const uri group_name,
                     uint_t num_ifs, uint_t *ifs);

   The s argument identifies the multicast socket.

   The group_name argument identifies the multicast group to which a
   source sends data.

   The num_ifs argument holds the number of elements in the ifs array.

   The ifs argument points to the list of interfaces for which the
   source registration failed.  If num_ifs was 0 on output, a NULL
   pointer is returned.

   If source registration succeeded for all interfaces associated with
   the socket, the value 0 is returned, otherwise -1.

4.2.5.  Source Deregister

   The srcDeregister indicates that a source does no longer intend to
   send data to the multicast group.

     int srcDeregister(int s, const uri group_name,
                       uint_t num_ifs, uint_t *ifs);

   The s argument identifies the multicast socket.

   The group_name argument identifies the multicast group to which a



Waehlisch, et al.       Expires January 13, 2011               [Page 13]

Internet-Draft              Common Mcast API                   July 2010


   source stops sending multicast data.

   The num_ifs argument holds the number of elements in the ifs array.

   The ifs argument points to the list of interfaces for which the
   source deregistration failed.  If num_ifs was 0 on output, a NULL
   pointer is returned.

   If source deregistration succeeded for all interfaces associated with
   the socket, the value 0 is returned, otherwise -1.

4.3.  Send and Receive Calls

4.3.1.  Send

   The send call passes multicast data for a Multicast Name from the
   application to the multicast socket.

      int send(int s, const uri group_name,
               size_t msg_len, const void *buf);

   The s argument identifies the multicast socket.

   The group_name argument identifies the group to which data will be
   sent.

   The msg_len argument holds the length of the message to be sent.

   The buf argument passes the multicast data to the multicast socket.

   On success the value 0 is returned, otherwise -1.

4.3.2.  Receive

   The receive call passes multicast data and the corresponding Group
   Name to the application.

     int receive(int s, const uri group_name,
                 size_t msg_len, msg *msg_buf);

   The s argument identifies the multicast socket.

   The group_name argument identifies the subscribed multicast group.

   The msg_len argument holds the length of the received message.

   The msg_buf argument points to the payload of the received multicast
   data.



Waehlisch, et al.       Expires January 13, 2011               [Page 14]

Internet-Draft              Common Mcast API                   July 2010


   On success the value 0 is returned, otherwise -1.

4.4.  Socket Options

   The following calls configure an existing multicast socket.

4.4.1.  Get Interfaces

   The getInterface call returns an array of all available multicast
   communication interfaces associated with the multicast socket.

     int getInterfaces(int s, uint_t num_ifs, uint_t *ifs);

   The s argument identifies the multicast socket.

   The num_ifs argument holds the number of interfaces in the ifs list.

   The ifs argument points to an array of interface identifiers.

   On success the value 0 or lager is returned, otherwise -1.

4.4.2.  Add Interface

   The addInterface call adds a distribution channel to the socket.
   This may be an overlay or underlay interface, e.g., IPv6 or DHT.
   Multiple interfaces of the same technology may be associated with the
   socket.

     int addInterface(int s, uint32_t if);

   The s and if arguments identify a multicast socket and interface,
   respectively.

   On success the value 0 is returned, otherwise -1.

4.4.3.  Delete Interface

   The delnterface call removes the interface if from the multicast
   socket.

     int delInterface(int s, uint32_t if);

   The s and if arguments identify a multicast socket and interface,
   respectively.

   On success the value 0 is returned, otherwise -1.





Waehlisch, et al.       Expires January 13, 2011               [Page 15]

Internet-Draft              Common Mcast API                   July 2010


4.4.4.  Set TTL

   The setTTL call configures the maximum hop count for the socket a
   multicast message is allowed to traverse.

     int setTTL(int s, int h);

   The s and h arguments identify a multicast socket and the maximum hop
   count, respectively.

   On success the value 0 is returned, otherwise -1.

4.5.  Service Calls

4.5.1.  Group Set

   This groupSet call returns all registered multicast groups.  The
   information can be provided by group management or routing protocols.
   The return values distinguish between sender and listener states.

     int groupSet(uint32_t if, uint_t *num_groups,
                  struct groupSet *groupSet);

     struct groupSet {
       uri group_name; /* registered multicast group */
       int type;       /* 0 = listener state, 1 = sender state */

   The if argument identifies the interface for which states are
   maintained.

   The num_groups argument holds number of groups in the groupSet array.

   The groupSet argument points to an array group states.

   On success the value 0 is returned, otherwise -1.

4.5.2.  Neighbor Set

   The neighborSet function can be invoked to get the set of multicast
   routing neighbors.

     int neighborSet(uint32_t if, uint_t *num_groups,
                     const uri *group_name);

   The if argument identifies the interface to which neighbors are
   attached.

   The num_groups argument holds the number of addresses in the



Waehlisch, et al.       Expires January 13, 2011               [Page 16]

Internet-Draft              Common Mcast API                   July 2010


   group_name array.

   The group_name argument points to a list of multicast neighbors on a
   successfull return.

   On success the value 0 is returned, otherwise -1.

4.5.3.  Designated Host

   The designatedHost function returns if the host has the role of a
   designated forwarder or querier, or not.  Such an information is
   provided by almost all multicast protocols to handle packet
   duplication, if multiple multicast instances serve on the same
   subnet.

     int designatedHost(const uri *group_name);

   The group_name argument points to the group for which the host may
   attain the role of designated forwarder.

   The function returns 1 if the host is a designated forwarder or
   querier, otherwise 0.  The return value -1 indicates an error.

4.5.4.  Update Listener

   The updateListener function is invoked to inform a group service
   about a change of listener states for a group.  This is the result of
   receiver new subscriptions or leaves.  The group service may call
   groupSet to get updated information.

     const uri *updateListener();

   On success the updateListener function points to the Group Name that
   experienced state change, otherwise NULL.


5.  Functional Details

   In this section, we describe the functional details of the API and
   the middleware.

   TODO

5.1.  Mapping

   Group Name to Group Address, SSM/ASM TODO





Waehlisch, et al.       Expires January 13, 2011               [Page 17]

Internet-Draft              Common Mcast API                   July 2010


5.2.  Namespaces


6.  IANA Considerations

   This document makes no request of IANA.


7.  Security Considerations

   This draft does neither introduce additional messages nor novel
   protocol operations.  TODO


8.  Acknowledgements

   We would like to thank the HAMcast-team, Dominik Charousset, Gabriel
   Hege, Fabian Holler, Alexander Knauf, Sebastian Meiling, and
   Sebastian Woelke, at the HAW Hamburg for fruitful discussions.

   This work is partially supported by the German Federal Ministry of
   Education and Research within the HAMcast project, which is part of
   G-Lab.


9.  Informative References

   [I-D.ietf-mboned-auto-multicast]
              Thaler, D., Talwar, M., Aggarwal, A., Vicisano, L., and T.
              Pusateri, "Automatic IP Multicast Without Explicit Tunnels
              (AMT)", draft-ietf-mboned-auto-multicast-10 (work in
              progress), March 2010.

   [RFC1075]  Waitzman, D., Partridge, C., and S. Deering, "Distance
              Vector Multicast Routing Protocol", RFC 1075,
              November 1988.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2710]  Deering, S., Fenner, W., and B. Haberman, "Multicast
              Listener Discovery (MLD) for IPv6", RFC 2710,
              October 1999.

   [RFC3376]  Cain, B., Deering, S., Kouvelas, I., Fenner, B., and A.
              Thyagarajan, "Internet Group Management Protocol, Version
              3", RFC 3376, October 2002.




Waehlisch, et al.       Expires January 13, 2011               [Page 18]

Internet-Draft              Common Mcast API                   July 2010


   [RFC3493]  Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
              Stevens, "Basic Socket Interface Extensions for IPv6",
              RFC 3493, February 2003.

   [RFC3678]  Thaler, D., Fenner, B., and B. Quinn, "Socket Interface
              Extensions for Multicast Source Filters", RFC 3678,
              January 2004.

   [RFC3810]  Vida, R. and L. Costa, "Multicast Listener Discovery
              Version 2 (MLDv2) for IPv6", RFC 3810, June 2004.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, January 2005.

   [RFC4395]  Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
              Registration Procedures for New URI Schemes", BCP 35,
              RFC 4395, February 2006.

   [RFC4601]  Fenner, B., Handley, M., Holbrook, H., and I. Kouvelas,
              "Protocol Independent Multicast - Sparse Mode (PIM-SM):
              Protocol Specification (Revised)", RFC 4601, August 2006.

   [RFC4604]  Holbrook, H., Cain, B., and B. Haberman, "Using Internet
              Group Management Protocol Version 3 (IGMPv3) and Multicast
              Listener Discovery Protocol Version 2 (MLDv2) for Source-
              Specific Multicast", RFC 4604, August 2006.

   [RFC5015]  Handley, M., Kouvelas, I., Speakman, T., and L. Vicisano,
              "Bidirectional Protocol Independent Multicast (BIDIR-
              PIM)", RFC 5015, October 2007.


Appendix A.  Practical Example of the API

















Waehlisch, et al.       Expires January 13, 2011               [Page 19]

Internet-Draft              Common Mcast API                   July 2010


     -- Application above middleware:

     //Initialize multicast socket;
     //the middleware selects all available interfaces
     MulticastSocket m = new MulticastSocket();

     m.join(URI("ipv4://224.1.2.3:5000"));
     m.join(URI("ipv6://[FF02:0:0:0:0:0:0:3]:6000"));
     m.join(URI("sip://news@cnn.com"));

     -- Middleware:

     join(URI mcAddress) {
       //Select interfaces in use
       for all this.interfaces {
         switch (interface.type) {
           case "ipv6":
             //... map logical ID to routing address
             Inet6Address rtAddressIPv6 = new Inet6Address();
             mapNametoAddress(mcAddress,rtAddressIPv6);
             interface.join(rtAddressIPv6);
           case "ipv4":
             //... map logical ID to routing address
             Inet4Address rtAddressIPv4 = new Inet4Address();
             mapNametoAddress(mcAddress,rtAddressIPv4);
             interface.join(rtAddressIPv4);
           case "sip":
             //... map logical ID to routing address
             SIPAddress rtAddressSIP = new SIPAddress();
             mapNametoAddress(mcAddress,rtAddressSIP);
             interface.join(rtAddressSIP);
           case "dht":
             //... map logical ID to routing address
             DHTAddress rtAddressDHT = new DHTAddress();
             mapNametoAddress(mcAddress,rtAddressDHT);
             interface.join(rtAddressDHT);
            //...
         }
       }
     }



Appendix B.  Deployment Use Cases for Hybrid Multicast

   This section describes the application of the defined API to
   implement an IMG.




Waehlisch, et al.       Expires January 13, 2011               [Page 20]

Internet-Draft              Common Mcast API                   July 2010


B.1.  DVMRP

   The following procedure describes a transparent mapping of a DVMRP-
   based any source multicast service to another many-to-many multicast
   technology.

   An arbitrary DVMRP [RFC1075] router will not be informed about new
   receivers, but will learn about new sources immediately.  The concept
   of DVMRP does not provide any central multicast instance.  Thus, the
   IMG can be placed anywhere inside the multicast region, but requires
   a DVMRP neighbor connectivity.  The group communication stack used by
   the IMG is enhanced by a DVMRP implementation.  New sources in the
   underlay will be advertised based on the DVMRP flooding mechanism and
   received by the IMG.  Based on this the updateSender() call is
   triggered.  The relay agent initiates a corresponding join in the
   native network and forwards the received source data towards the
   overlay routing protocol.  Depending on the group states, the data
   will be distributed to overlay peers.

   DVMRP establishes source specific multicast trees.  Therefore, a
   graft message is only visible for DVMRP routers on the path from the
   new receiver subnet to the source, but in general not for an IMG.  To
   overcome this problem, data of multicast senders will be flooded in
   the overlay as well as in the underlay.  Hence, an IMG has to
   initiate an all-group join to the overlay using the namespace
   extension of the API.  Each IMG is initially required to forward the
   received overlay data to the underlay, independent of native
   multicast receivers.  Subsequent prunes may limit unwanted data
   distribution thereafter.

B.2.  PIM-SM

   The following procedure describes a transparent mapping of a PIM-SM-
   based any source multicast service to another many-to-many multicast
   technology.

   The Protocol Independent Multicast Sparse Mode (PIM-SM) [RFC4601]
   establishes rendezvous points (RP).  These entities receive listener
   and source subscriptions of a domain.  To be continuously updated, an
   IMG has to be co-located with a RP.  Whenever PIM register messages
   are received, the IMG must signal internally a new multicast source
   using updateSender().  Subsequently, the IMG joins the group and a
   shared tree between the RP and the sources will be established, which
   may change to a source specific tree after a sufficient number of
   data has been delivered.  Source traffic will be forwarded to the RP
   based on the IMG join, even if there are no further receivers in the
   native multicast domain.  Designated routers of a PIM-domain send
   receiver subscriptions towards the PIM-SM RP.  The reception of such



Waehlisch, et al.       Expires January 13, 2011               [Page 21]

Internet-Draft              Common Mcast API                   July 2010


   messages invokes the updateListener() call at the IMG, which
   initiates a join towards the overlay routing protocol.  Overlay
   multicast data arriving at the IMG will then transparently be
   forwarded in the underlay network and distributed through the RP
   instance.

B.3.  PIM-SSM

   The following procedure describes a transparent mapping of a PIM-SSM-
   based source specific multicast service to another one-to-many
   multicast technology.

   PIM Source Specific Multicast (PIM-SSM) is defined as part of PIM-SM
   and admits source specific joins (S,G) according to the source
   specific host group model [RFC4604].  A multicast distribution tree
   can be established without the assistance of a rendezvous point.

   Sources are not advertised within a PIM-SSM domain.  Consequently, an
   IMG cannot anticipate the local join inside a sender domain and
   deliver a priori the multicast data to the overlay instance.  If an
   IMG of a receiver domain initiates a group subscription via the
   overlay routing protocol, relaying multicast data fails, as data are
   not available at the overlay instance.  The IMG instance of the
   receiver domain, thus, has to locate the IMG instance of the source
   domain to trigger the corresponding join.  In the sense of PIM-SSM,
   the signaling should not be flooded in underlay and overlay.

   One solution could be to intercept the subscription at both, source
   and receiver sites: To monitor multicast receiver subscriptions
   (updateListener()) in the underlay, the IMG is placed on path towards
   the source, e.g., at a domain border router.  This router intercepts
   join messages and extracts the unicast source address S, initializing
   an IMG specific join to S via regular unicast.  Multicast data
   arriving at the IMG of the sender domain can be distributed via the
   overlay.  Discovering the IMG of a multicast sender domain may be
   implemented analogously to AMT [I-D.ietf-mboned-auto-multicast] by
   anycast.  Consequently, the source address S of the group (S,G)
   should be built based on an anycast prefix.  The corresponding IMG
   anycast address for a source domain is then derived from the prefix
   of S.

B.4.  BIDIR-PIM

   The following procedure describes a transparent mapping of a BIDIR-
   PIM-based any source multicast service to another many-to-many
   multicast technology.

   Bidirectional PIM [RFC5015] is a variant of PIM-SM.  In contrast to



Waehlisch, et al.       Expires January 13, 2011               [Page 22]

Internet-Draft              Common Mcast API                   July 2010


   PIM-SM, the protocol pre-establishes bidirectional shared trees per
   group, connecting multicast sources and receivers.  The rendezvous
   points are virtualized in BIDIR-PIM as an address to identify on-tree
   directions (up and down).  However, routers with the best link
   towards the (virtualized) rendezvous point address are selected as
   designated forwarders for a link-local domain and represent the
   actual distribution tree.  The IMG is to be placed at the RP-link,
   where the rendezvous point address is located.  As source data in
   either cases will be transmitted to the rendezvous point address, the
   BIDIR-PIM instance of the IMG receives the data and can internally
   signal new senders towards the stack via updateSender().  The first
   receiver subscription for a new group within a BIDIR-PIM domain needs
   to be transmitted to the RP to establish the first branching point.
   Using the updateListener() invocation, an IMG will thereby be
   informed about group requests from its domain, which are then
   delegated to the overlay.


Appendix C.  Change Log

   The following changes have been made from
   draft-waehlisch-sam-common-api-02

   1.  Rename init() in createSocket().

   2.  Cleanup code in "Practical Example of the API".

   3.  Editoral improvements.

   The following changes have been made from
   draft-waehlisch-sam-common-api-01

   1.  Document restructured to clarify the realm of document overview
       and specific contributions s.a. naming and addressing.

   2.  A clear separation of naming and addressing was drawn.  Multicast
       URIs have been introduced.

   3.  Clarified and adapted the API calls.

   4.  Introduced Socket Option calls.

   5.  Deployment use cases moved to an appendix.

   6.  Simple programming example added.

   7.  Many editorial improvements.




Waehlisch, et al.       Expires January 13, 2011               [Page 23]

Internet-Draft              Common Mcast API                   July 2010


Authors' Addresses

   Matthias Waehlisch
   link-lab & FU Berlin
   Hoenower Str. 35
   Berlin  10318
   Germany

   Email: mw@link-lab.net
   URI:   http://www.inf.fu-berlin.de/~waehl


   Thomas C. Schmidt
   HAW Hamburg
   Berliner Tor 7
   Hamburg  20099
   Germany

   Email: schmidt@informatik.haw-hamburg.de
   URI:   http://inet.cpt.haw-hamburg.de/members/schmidt


   Stig Venaas
   cisco Systems
   Tasman Drive
   San Jose, CA  95134
   USA

   Email: stig@cisco.com






















Waehlisch, et al.       Expires January 13, 2011               [Page 24]


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