One document matched: draft-waehlisch-sam-common-api-03.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="3"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="info" docName="draft-waehlisch-sam-common-api-03"
ipr="trust200902">
<front>
<title abbrev="Common Mcast API">A Common API for Transparent Hybrid
Multicast</title>
<author fullname="Matthias Waehlisch" initials="M." surname="Waehlisch">
<organization>link-lab & FU Berlin</organization>
<address>
<postal>
<street>Hoenower Str. 35</street>
<city>Berlin</city>
<code>10318</code>
<country>Germany</country>
</postal>
<email>mw@link-lab.net</email>
<uri>http://www.inf.fu-berlin.de/~waehl</uri>
</address>
</author>
<author fullname="Thomas C. Schmidt" initials="T C." surname="Schmidt">
<organization>HAW Hamburg</organization>
<address>
<postal>
<street>Berliner Tor 7</street>
<city>Hamburg</city>
<code>20099</code>
<country>Germany</country>
</postal>
<email>schmidt@informatik.haw-hamburg.de</email>
<uri>http://inet.cpt.haw-hamburg.de/members/schmidt</uri>
</address>
</author>
<author fullname="Stig Venaas" initials="S." surname="Venaas">
<organization>cisco Systems</organization>
<address>
<postal>
<street>Tasman Drive</street>
<city>San Jose</city>
<region>CA</region>
<code>95134</code>
<country>USA</country>
</postal>
<email>stig@cisco.com</email>
</address>
</author>
<date day="12" month="July" year="2010" />
<workgroup>SAM Research Group</workgroup>
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>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 <xref target="RFC3493"></xref>, <xref
target="RFC3678"></xref> 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.</t>
<t>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.</t>
<t>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.</t>
<t>The aim of this common API is twofold: <list style="symbols">
<t>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.</t>
<t>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
services.</t>
</list></t>
<t>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.</t>
<t>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.</t>
</section>
<section title="Terminology">
<t>This document uses the terminology as defined for the multicast
protocols <xref target="RFC2710"></xref>,<xref
target="RFC3376"></xref>,<xref target="RFC3810"></xref>,<xref
target="RFC4601"></xref>,<xref target="RFC4604"></xref>. In addition,
the following terms will be used.</t>
<t><list style="hanging">
<t hangText="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.</t>
<t hangText="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.</t>
<t hangText="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.</t>
<t hangText="Multicast Domain:">A Multicast Domain accommodates
nodes and routers of a common, single multicast forwarding
technology and is bound to a single namespace.</t>
<t hangText="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.</t>
<t hangText="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.</t>
</list></t>
<t></t>
</section>
<section title="Overview">
<t></t>
<section title="Objectives and Reference Scenarios">
<t>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<list style="symbols">
<t>programmers are enabled to process group names in their
programs without the need to consider technological mappings to
designated deployments in target domains;</t>
<t>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.</t>
</list></t>
<t>This document refers to a reference scenario that covers the
following two hybrid deployment cases displayed in <xref
target="fig:reference"></xref>:</t>
<t><list style="numbers">
<t>Multicast domains running the same multicast technology but
remaining isolated, possibly only connected by network layer
unicast.</t>
<t>Multicast domains running different multicast technologies, but
hosting nodes that are members of the same multicast group.</t>
</list></t>
<figure anchor="fig:reference"
title="Reference scenarios for hybrid multicast, interconnecting group members from isolated homogeneous and heterogeneous domains.">
<artwork><![CDATA[
+-------+ +-------+
| Member| | Member|
| Foo | | G |
+-------+ +-------+
\ /
*** *** *** ***
* ** ** ** *
* *
* MCast Tec A *
* *
* ** ** ** *
*** *** *** ***
+-------+ +-------+ |
| Member| | Member| +-------+
| G | | Foo | | IMG |
+-------+ +-------+ +-------+
| | |
*** *** *** *** *** *** *** ***
* ** ** ** * * ** ** ** *
* * +-------+ * *
* MCast Tec A * --| IMG |-- * MCast Tec B * +-------+
* * +-------+ * * - | Member|
* ** ** ** * * ** ** ** * | G |
*** *** *** *** *** *** *** *** +-------+
]]></artwork>
</figure>
<t></t>
<t>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.</t>
</section>
<section title="Group Communication API & Protocol Stack">
<t>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: <list
style="hanging">
<t hangText="Group Management Calls">provide the minimal API to
instantiate a multicast socket and manage group membership.</t>
<t hangText="Send/Receive Calls">provide the minimal API send and
receive multicast data in a technology-transparent fashion.</t>
<t hangText="Socket Options">provide extension calls for the
configuration of the multicast socket, i.e., setting path length
and associated interfaces explicitly.</t>
<t hangText="Service Calls">provide extension calls that grant
access to internal multicast states of an interface such as the
multicast groups under subscription.</t>
</list></t>
<t>Multicast applications that use the common API require assistance
by a group communication stack. This protocol stack serves two
needs:</t>
<t><list style="symbols">
<t>It provides system-level support to transfer the abstract
functions of the common API, including namespace support, into
protocol operations at interfaces.</t>
<t>It bridges data distribution between different multicast
technologies.</t>
</list></t>
<t>The general procedure to initiate multicast communication in this
setting proceeds as follows:</t>
<t><list style="numbers">
<t>An application opens an abstract multicast socket.</t>
<t>The application subscribes/leaves/sends to a group using a
logical group identifier.</t>
<t>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.</t>
<t>Packet distribution proceeds to and from one or several
multicast-enabled interfaces.</t>
</list></t>
<t>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).</t>
<t>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 at
the application side.</t>
<t>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.</t>
<t><!--In this case, they will be enabled to forward data between the different technologies using the service calls of the API. Such a proxy function can be implemented on each host or on dedicated gateways. These gateways also assist multicast members that have no middleware support to be integrated in additional namespaces.--></t>
<t>The extended multicast functions can be implemented by a middleware
as visualized in <xref target="fig:middleware"></xref>.</t>
<t></t>
<figure anchor="fig:middleware"
title="A middleware for offering uniform access to multicast in underlay and overlay">
<artwork><![CDATA[*-------* *-------*
| App 1 | | App 2 |
*-------* *-------*
| |
*---------------------* ---|
| Middleware | |
*---------------------* |
| | |
*---------* | |
| Overlay | | \ Group Communication
*---------* | / Stack
| | |
| | |
*---------------------* |
| Underlay | |
*---------------------* ---|]]></artwork>
</figure>
<t></t>
<t></t>
</section>
<section title="Naming and Addressing">
<t>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.</t>
<t>URIs <xref target="RFC3986"></xref> 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 <xref target="sec:details-uri"></xref>. Examples
are, ip://224.1.2.3:5000, and sip://news@cnn.com.</t>
<t>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.</t>
<t>A multicast socket (IPv4/v6 interface) can be used by multiple
logical multicast IDs from different namespaces (IPv4-group address,
IPv6-group address).</t>
</section>
<section title="Mapping">
<t>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.</t>
<t>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.</t>
<t>Two (or more) Multicast Addresses from different namespaces may
belong to</t>
<t><list style="letters">
<t>the same logical group (i.e., same Multicast Name)</t>
<t>different multicast channels (i.e., different technical
IDs).</t>
</list></t>
<t>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).</t>
<t>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 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.</t>
<t>All group members subscribe to the same Group Name within the same
namespace.</t>
</section>
</section>
<section title="Common Multicast API">
<t></t>
<section title="Abstract Data Types">
<t></t>
<section anchor="sec:details-uri" title="Multicast URI">
<t>Multicast Names and Multicast Addresses follow an URI scheme that
defines a subset of the generic URI specified in <xref
target="RFC3986"></xref> and is compliant with the guidelines in
<xref target="RFC4395"></xref>.</t>
<t>The multicast URI is defined as follows:</t>
<t><list style="empty">
<t>scheme "://" group "@" instantiation ":" port "/"
sec-credentials</t>
</list></t>
<t>The parts of the URI are defined as follows:</t>
<t><list style="hanging">
<t hangText="scheme">referes to the specification of the
assigned identifier <xref target="RFC3986"></xref> which takes
the role of the namespace.</t>
<t hangText="group">identifies the group uniquely within the
namespace given in scheme.</t>
<t hangText="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.</t>
<t hangText="port">identifies a specific application at an
instance of a group.</t>
<t hangText="sec-credentials">used to implement security
credentials (e.g., to authorize a multicast group access).</t>
</list></t>
</section>
<section title="Interface">
<t>The interface denotes the layer and instance on which the
corresponding call will be effective. In agreement with <xref
target="RFC3493"></xref> we identify an interface by an identifier,
which is a positive integer starting at 1.</t>
<t>Properties of an interface are stored in the following
struct:</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ 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", ... */
};]]></artwork>
</figure>
<t></t>
<t>The following function retrieves all available interfaces from
the system:</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ struct if_prop *if_prop(void);]]></artwork>
</figure>
<t></t>
<t>It extends the functions for Interface Identfication in <xref
target="RFC3493"></xref> (cf., Section 4).</t>
</section>
</section>
<section title="Group Management Calls">
<t></t>
<section title="Create">
<t>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.<spanx style="verbatim"></spanx></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int createMSocket(uint32_t *if);]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument denotes a list of interfaces that will be
associated with the multicast socket. This parameter is
optional.</t>
<t>On success a multicast socket identifier is returned, otherwise
NULL.</t>
</section>
<section title="Join">
<t>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.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int join(int s, const uri group_name);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the group.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Leave">
<t>The leave call results in an unsubscription for the given Group
Name.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int leave(int s, const uri group_name);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name identifies the group.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Source Register">
<t>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.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int srcRegister(int s, const uri group_name,
uint_t num_ifs, uint_t *ifs);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the multicast group to which a
source sends data.</t>
<t>The num_ifs argument holds the number of elements in the ifs
array.</t>
<t>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.</t>
<t>If source registration succeeded for all interfaces associated
with the socket, the value 0 is returned, otherwise -1.</t>
</section>
<section title="Source Deregister">
<t>The srcDeregister indicates that a source does no longer intend
to send data to the multicast group.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int srcDeregister(int s, const uri group_name,
uint_t num_ifs, uint_t *ifs);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the multicast group to which a
source stops sending multicast data.</t>
<t>The num_ifs argument holds the number of elements in the ifs
array.</t>
<t>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.</t>
<t>If source deregistration succeeded for all interfaces associated
with the socket, the value 0 is returned, otherwise -1.</t>
</section>
</section>
<section title="Send and Receive Calls">
<t></t>
<section title="Send">
<t>The send call passes multicast data for a Multicast Name from the
application to the multicast socket.<spanx
style="verbatim"></spanx></t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int send(int s, const uri group_name,
size_t msg_len, const void *buf);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the group to which data will
be sent.</t>
<t>The msg_len argument holds the length of the message to be
sent.</t>
<t>The buf argument passes the multicast data to the multicast
socket.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Receive">
<t>The receive call passes multicast data and the corresponding
Group Name to the application.<spanx
style="verbatim"></spanx><figure>
<preamble></preamble>
<artwork><![CDATA[ int receive(int s, const uri group_name,
size_t msg_len, msg *msg_buf);]]></artwork>
<postamble></postamble>
</figure></t>
<t>The s argument identifies the multicast socket.</t>
<t>The group_name argument identifies the subscribed multicast
group.</t>
<t>The msg_len argument holds the length of the received
message.</t>
<t>The msg_buf argument points to the payload of the received
multicast data.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
</section>
<section title="Socket Options">
<t>The following calls configure an existing multicast socket.</t>
<section title="Get Interfaces">
<t>The getInterface call returns an array of all available multicast
communication interfaces associated with the multicast socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int getInterfaces(int s, uint_t num_ifs, uint_t *ifs);]]></artwork>
<postamble></postamble>
</figure>
<t>The s argument identifies the multicast socket.</t>
<t>The num_ifs argument holds the number of interfaces in the ifs
list.</t>
<t>The ifs argument points to an array of interface identifiers.</t>
<t>On success the value 0 or lager is returned, otherwise -1.</t>
</section>
<section title="Add Interface">
<t>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.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int addInterface(int s, uint32_t if);]]></artwork>
<postamble></postamble>
</figure>
<t>The s and if arguments identify a multicast socket and interface,
respectively.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Delete Interface">
<t>The delnterface call removes the interface if from the multicast
socket.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int delInterface(int s, uint32_t if);]]></artwork>
<postamble></postamble>
</figure>
<t>The s and if arguments identify a multicast socket and interface,
respectively.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Set TTL">
<t>The setTTL call configures the maximum hop count for the socket a
multicast message is allowed to traverse.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int setTTL(int s, int h);]]></artwork>
<postamble></postamble>
</figure>
<t>The s and h arguments identify a multicast socket and the maximum
hop count, respectively.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
</section>
<section title="Service Calls">
<t></t>
<section title="Group Set">
<t>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.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ 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 */]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the interface for which states are
maintained.</t>
<t>The num_groups argument holds number of groups in the groupSet
array.</t>
<t>The groupSet argument points to an array group states.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Neighbor Set">
<t>The neighborSet function can be invoked to get the set of
multicast routing neighbors.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int neighborSet(uint32_t if, uint_t *num_groups,
const uri *group_name);]]></artwork>
<postamble></postamble>
</figure>
<t>The if argument identifies the interface to which neighbors are
attached.</t>
<t>The num_groups argument holds the number of addresses in the
group_name array.</t>
<t>The group_name argument points to a list of multicast neighbors
on a successfull return.</t>
<t>On success the value 0 is returned, otherwise -1.</t>
</section>
<section title="Designated Host">
<t>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.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ int designatedHost(const uri *group_name);]]></artwork>
<postamble></postamble>
</figure>
<t>The group_name argument points to the group for which the host
may attain the role of designated forwarder.</t>
<t>The function returns 1 if the host is a designated forwarder or
querier, otherwise 0. The return value -1 indicates an error.</t>
</section>
<section title="Update Listener">
<t>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.</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[ const uri *updateListener();]]></artwork>
<postamble></postamble>
</figure>
<t>On success the updateListener function points to the Group Name
that experienced state change, otherwise NULL.</t>
</section>
</section>
</section>
<section title="Functional Details">
<t>In this section, we describe the functional details of the API and
the middleware.</t>
<t>TODO</t>
<section title="Mapping">
<t>Group Name to Group Address, SSM/ASM TODO</t>
</section>
<section anchor="sec:namespace" title="Namespaces"></section>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>This document makes no request of IANA.</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>This draft does neither introduce additional messages nor novel
protocol operations. TODO</t>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>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.</t>
<t>This work is partially supported by the German Federal Ministry of
Education and Research within the HAMcast project, which is part of
G-Lab.</t>
</section>
</middle>
<back>
<references title="Informative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include="reference.RFC.3493"?>
<?rfc include="reference.RFC.3678"?>
<?rfc include="reference.RFC.1075"?>
<?rfc include="reference.RFC.5015"?>
<?rfc include="reference.RFC.3810"?>
<?rfc include="reference.RFC.4604"?>
<?rfc include="reference.RFC.2710"?>
<?rfc include="reference.RFC.4601"?>
<?rfc include="reference.RFC.3376"?>
<?rfc include="reference.RFC.3986"?>
<?rfc include="reference.RFC.4395"?>
<?rfc include="reference.I-D.ietf-mboned-auto-multicast"?>
<?rfc ?>
</references>
<section title="Practical Example of the API">
<t></t>
<figure>
<artwork><![CDATA[ -- 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);
//...
}
}
}
]]></artwork>
</figure>
</section>
<section title="Deployment Use Cases for Hybrid Multicast">
<t>This section describes the application of the defined API to
implement an IMG.</t>
<section title="DVMRP">
<t>The following procedure describes a transparent mapping of a
DVMRP-based any source multicast service to another many-to-many
multicast technology.</t>
<t>An arbitrary DVMRP <xref target="RFC1075"></xref> 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.</t>
<t>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.</t>
</section>
<section title="PIM-SM">
<t>The following procedure describes a transparent mapping of a
PIM-SM-based any source multicast service to another many-to-many
multicast technology.</t>
<t>The Protocol Independent Multicast Sparse Mode (PIM-SM) <xref
target="RFC4601"></xref> 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 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.</t>
</section>
<section title="PIM-SSM">
<t>The following procedure describes a transparent mapping of a
PIM-SSM-based source specific multicast service to another one-to-many
multicast technology.</t>
<t>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 <xref target="RFC4604"></xref>. A multicast
distribution tree can be established without the assistance of a
rendezvous point.</t>
<t>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.</t>
<t>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 <xref
target="I-D.ietf-mboned-auto-multicast"></xref> 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.</t>
</section>
<section title="BIDIR-PIM">
<t>The following procedure describes a transparent mapping of a
BIDIR-PIM-based any source multicast service to another many-to-many
multicast technology.</t>
<t>Bidirectional PIM <xref target="RFC5015"></xref> is a variant of
PIM-SM. In contrast to 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.</t>
</section>
</section>
<section title="Change Log">
<t>The following changes have been made from
draft-waehlisch-sam-common-api-02<list style="numbers">
<t>Rename init() in createSocket().</t>
<t>Cleanup code in "Practical Example of the API".</t>
<t>Editoral improvements.</t>
</list></t>
<t>The following changes have been made from
draft-waehlisch-sam-common-api-01<list style="numbers">
<t>Document restructured to clarify the realm of document overview
and specific contributions s.a. naming and addressing.</t>
<t>A clear separation of naming and addressing was drawn. Multicast
URIs have been introduced.</t>
<t>Clarified and adapted the API calls.</t>
<t>Introduced Socket Option calls.</t>
<t>Deployment use cases moved to an appendix.</t>
<t>Simple programming example added.</t>
<t>Many editorial improvements.</t>
</list></t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 10:20:27 |