svn commit: r189337 - head/share/man/man4
Bruce M Simpson
bms at FreeBSD.org
Tue Mar 3 18:00:15 PST 2009
Author: bms
Date: Wed Mar 4 02:00:14 2009
New Revision: 189337
URL: http://svn.freebsd.org/changeset/base/189337
Log:
Add source-specific multicast (SSM) option documentation.
Modified:
head/share/man/man4/ip.4
Modified: head/share/man/man4/ip.4
==============================================================================
--- head/share/man/man4/ip.4 Wed Mar 4 01:59:14 2009 (r189336)
+++ head/share/man/man4/ip.4 Wed Mar 4 02:00:14 2009 (r189337)
@@ -32,7 +32,7 @@
.\" @(#)ip.4 8.2 (Berkeley) 11/30/93
.\" $FreeBSD$
.\"
-.Dd April 9, 2007
+.Dd February 13, 2009
.Dt IP 4
.Os
.Sh NAME
@@ -404,8 +404,9 @@ group and if multicast loopback has not
Multicast datagrams with TTL greater than 1 may be forwarded
to other networks if a multicast router is attached to the local network.
.Pp
-For hosts with multiple interfaces, each multicast transmission is
-sent from the primary network interface.
+For hosts with multiple interfaces, where an interface has not
+been specified for a multicast group membership,
+each multicast transmission is sent from the primary network interface.
The
.Dv IP_MULTICAST_IF
option overrides the default for
@@ -423,12 +424,25 @@ to specify the default interface.
.Pp
To specify an interface by index, an instance of
.Vt ip_mreqn
-should be passed instead.
+may be passed instead.
The
.Vt imr_ifindex
member should be set to the index of the desired interface,
or 0 to specify the default interface.
The kernel differentiates between these two structures by their size.
+.Pp
+The use of
+.Vt IP_MULTICAST_IF
+is
+.Em not recommended ,
+as multicast memberships are scoped to each
+individual interface.
+It is supported for legacy use only by applications,
+such as routing daemons, which expect to
+be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24)
+on multiple interfaces,
+without requesting an individual membership for each interface.
+.Pp
.\"
An interface's local IP address and multicast capability can
be obtained via the
@@ -485,24 +499,32 @@ struct ip_mreq {
.Ed
.Pp
.Va imr_interface
-should be set to
-.Dv INADDR_ANY
-to choose the default multicast interface,
-or the
+should be set to the
.Tn IP
address of a particular multicast-capable interface if
the host is multihomed.
-.\" TODO: Remove this piece when the RFC 3678 API is implemented and
-.\" the RFC 1724 hack is removed.
-Since
-.Fx 4.4 ,
+It may be set to
+.Dv INADDR_ANY
+to choose the default interface, although this is not recommended;
+this is considered to be the first interface corresponding
+to the default route.
+Otherwise, the first multicast-capable interface
+configured in the system will be used.
+.Pp
+Prior to
+.Fx 7.0 ,
if the
.Va imr_interface
member is within the network range
.Li 0.0.0.0/8 ,
it is treated as an interface index in the system interface MIB,
as per the RIP Version 2 MIB Extension (RFC-1724).
-.\" TODO: Update this piece when IPv4 source-address selection is implemented.
+In versions of
+.Fx
+since 7.0, this behavior is no longer supported.
+Developers should
+instead use the RFC 3678 multicast source filter APIs; in particular,
+.Dv MCAST_JOIN_GROUP .
.Pp
Up to
.Dv IP_MAX_MEMBERSHIPS
@@ -511,24 +533,123 @@ Membership is associated with a single i
programs running on multihomed hosts may need to
join the same group on more than one interface.
.Pp
+To drop a membership, use:
+.Bd -literal
+struct ip_mreq mreq;
+setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
+.Ed
+.Pp
+where
+.Fa mreq
+contains the same values as used to add the membership.
+Memberships are dropped when the socket is closed or the process exits.
+.\" TODO: Update this piece when IPv4 source-address selection is implemented.
+.Pp
The IGMP protocol uses the primary IP address of the interface
as its identifier for group membership.
+This is the first IP address configured on the interface.
+If this address is removed or changed, the results are
+undefined, as the IGMP membership state will then be inconsistent.
If multiple IP aliases are configured on the same interface,
they will be ignored.
+.Pp
This shortcoming was addressed in IPv6; MLDv2 requires
that the unique link-local address for an interface is
used to identify an MLDv2 listener.
+.Ss "Source-Specific Multicast Options"
+Since
+.Fx 8.0 ,
+the use of Source-Specific Multicast (SSM) is supported.
+These extensions require an IGMPv3 multicast router in order to
+make best use of them.
+If a legacy multicast router is present on the link,
+.Fx
+will simply downgrade to the version of IGMP spoken by the router,
+and the benefits of source filtering on the upstream link
+will not be present, although the kernel will continue to
+squelch transmissions from blocked sources.
+.Pp
+Each group membership on a socket now has a filter mode:
+.Bl -tag -width MCAST_EXCLUDE
+.It Dv MCAST_EXCLUDE
+Datagrams sent to this group are accepted,
+unless the source is in a list of blocked source addresses.
+.It Dv MCAST_INCLUDE
+Datagrams sent to this group are accepted
+only if the source is in a list of accepted source addresses.
+.El
.Pp
-To drop a membership, use:
+Groups joined using the legacy
+.Dv IP_ADD_MEMBERSHIP
+option are placed in exclusive-mode,
+and are able to request that certain sources are blocked or allowed.
+This is known as the
+.Em delta-based API .
+.Pp
+To block a multicast source on an existing group membership:
.Bd -literal
-struct ip_mreq mreq;
-setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
+struct ip_mreq_source mreqs;
+setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs));
.Ed
.Pp
where
-.Fa mreq
-contains the same values as used to add the membership.
-Memberships are dropped when the socket is closed or the process exits.
+.Fa mreqs
+is the following structure:
+.Bd -literal
+struct ip_mreq_source {
+ struct in_addr imr_multiaddr; /* IP multicast address of group */
+ struct in_addr imr_sourceaddr; /* IP address of source */
+ struct in_addr imr_interface; /* local IP address of interface */
+}
+.Ed
+.Va imr_sourceaddr
+should be set to the address of the source to be blocked.
+.Pp
+To unblock a multicast source on an existing group:
+.Bd -literal
+struct ip_mreq_source mreqs;
+setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs));
+.Ed
+.Pp
+The
+.Dv IP_BLOCK_SOURCE
+and
+.Dv IP_UNBLOCK_SOURCE
+options are
+.Em not permitted
+for inclusive-mode group memberships.
+.Pp
+To join a multicast group in
+.Dv MCAST_INCLUDE
+mode with a single source,
+or add another source to an existing inclusive-mode membership:
+.Bd -literal
+struct ip_mreq_source mreqs;
+setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
+.Ed
+.Pp
+To leave a single source from an existing group in inclusive mode:
+.Bd -literal
+struct ip_mreq_source mreqs;
+setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));
+.Ed
+If this is the last accepted source for the group, the membership
+will be dropped.
+.Pp
+The
+.Dv IP_ADD_SOURCE_MEMBERSHIP
+and
+.Dv IP_DROP_SOURCE_MEMBERSHIP
+options are
+.Em not accepted
+for exclusive-mode group memberships.
+However, both exclusive and inclusive mode memberships
+support the use of the
+.Em full-state API
+documented in RFC 3678.
+For management of source filter lists using this API,
+please refer to
+.Xr sourcefilter 3 .
.\"-----------------------
.Ss "Raw IP Sockets"
.Pp
@@ -676,7 +797,16 @@ field was not equal to the length of the
.Xr icmp 4 ,
.Xr inet 4 ,
.Xr intro 4 ,
-.Xr multicast 4
+.Xr multicast 4 ,
+.Xr sourcefilter 3
+.Rs
+.%A D. Thaler
+.%A B. Fenner
+.%A B. Quinn
+.%T "Socket Interface Extensions for Multicast Source Filters"
+.%N RFC 3678
+.%D Jan 2004
+.Re
.Sh HISTORY
The
.Nm
More information about the svn-src-all
mailing list