Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
The names and trademarks of copyright holders may not be used in
advertising or publicity pertaining to the software without specific
prior permission. Title to copyright in this software and any associated
documentation will at all times remain with the copyright holders.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
$FreeBSD: src/share/man/man4/multicast.4,v 1.4 2004/07/09 09:22:36 ru Exp $
$OpenBSD: multicast.4,v 1.17 2024/01/23 08:20:30 jmc Exp $
$NetBSD: multicast.4,v 1.3 2004/09/12 13:12:26 wiz Exp $
.Dd $Mdocdate: February 18 2022 $ .Dt MULTICAST 4 .Os
.Sh NAME .Nm multicast .Nd multicast routing
.Sh SYNOPSIS .Cd "options MROUTING"
p n sys/types.h n sys/socket.h n netinet/in.h n netinet/ip_mroute.h n netinet6/ip6_mroute.h .Ft int .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen" .Ft int .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen" .Sh DESCRIPTION Multicast routing is used to efficiently propagate data packets to a set of multicast listeners in multipoint networks. If unicast is used to replicate the data to all listeners, then some of the network links may carry multiple copies of the same data packets. With multicast routing, the overhead is reduced to one copy (at most) per network link.
p All multicast-capable routers must run a common multicast routing protocol. The Distance Vector Multicast Routing Protocol (DVMRP) was the first developed multicast routing protocol. Later, other protocols such as Multicast Extensions to OSPF (MOSPF) and Core Based Trees (CBT) were developed as well.
p
To start multicast routing,
the user must enable multicast forwarding via the
.Xr sysctl 8
variables
.Va net.inet.ip.mforwarding
and/or
.Va net.inet6.ip6.mforwarding ,
and set
.Va multicast
to
.Dq YES
in
.Xr rc.conf.local 8 .
The user must also run a multicast routing capable user-level process,
such as
.Xr mrouted 8 .
From a developer's point of view,
the programming guide described in the
.Sx Programming Guide
section should be used to control the multicast forwarding in the kernel.
.Ss Programming Guide
This section provides information about the basic multicast routing API.
The so-called
.Dq advanced multicast API
is described in the
.Sx "Advanced Multicast API Programming Guide"
section.
p First, a multicast routing socket must be open. That socket would be used to control the multicast forwarding in the kernel. Note that most operations below require certain privilege (i.e., root privilege): d -literal -offset indent /* IPv4 */ int mrouter_s4; mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP); .Ed d -literal -offset indent int mrouter_s6; mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6); .Ed
p Note that if the router needs to open an IGMP or ICMPv6 socket (IPv4 or IPv6, respectively) for sending or receiving of IGMP or MLD multicast group membership messages, then the same .Va mrouter_s4 or .Va mrouter_s6 sockets should be used for sending and receiving respectively IGMP or MLD messages. In the case of x Ns -derived kernels, it may be possible to open separate sockets for IGMP or MLD messages only. However, some other kernels (e.g., Linux) require that the multicast routing socket must be used for sending and receiving of IGMP or MLD messages. Therefore, for portability reasons, the multicast routing socket should be reused for IGMP and MLD messages as well.
p After the multicast routing socket is open, it can be used to enable or disable multicast forwarding in the kernel: d -literal -offset 5n /* IPv4 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, &v, sizeof(v)); .Ed d -literal -offset 5n /* IPv6 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, &v, sizeof(v)); ... /* If necessary, filter all ICMPv6 messages */ struct icmp6_filter filter; ICMP6_FILTER_SETBLOCKALL(&filter); setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, &filter, sizeof(filter)); .Ed
p For each network interface (e.g., physical or a virtual tunnel) that would be used for multicast forwarding, a corresponding multicast interface must be added to the kernel: d -literal -offset 3n /* IPv4 */ struct vifctl vc; memset(&vc, 0, sizeof(vc)); /* Assign all vifctl fields as appropriate */ vc.vifc_vifi = vif_index; vc.vifc_flags = vif_flags; vc.vifc_threshold = min_ttl_threshold; vc.vifc_rate_limit = max_rate_limit; memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr)); if (vc.vifc_flags & VIFF_TUNNEL) memcpy(&vc.vifc_rmt_addr, &vif_remote_address, sizeof(vc.vifc_rmt_addr)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, &vc, sizeof(vc)); .Ed
p The .Va vif_index must be unique per vif. The .Va vif_flags contains the .Dv VIFF_* flags as defined in n netinet/ip_mroute.h . The .Va min_ttl_threshold contains the minimum TTL a multicast data packet must have to be forwarded on that vif. Typically, it would be 1. The .Va max_rate_limit contains the maximum rate (in bits/s) of the multicast data packets forwarded on that vif. A value of 0 means no limit. The .Va vif_local_address contains the local IP address of the corresponding local interface. The .Va vif_remote_address contains the remote IP address for DVMRP multicast tunnels. d -literal -offset indent /* IPv6 */ struct mif6ctl mc; memset(&mc, 0, sizeof(mc)); /* Assign all mif6ctl fields as appropriate */ mc.mif6c_mifi = mif_index; mc.mif6c_flags = mif_flags; mc.mif6c_pifi = pif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, &mc, sizeof(mc)); .Ed
p The .Va mif_index must be unique per vif. The .Va mif_flags contains the .Dv MIFF_* flags as defined in n netinet6/ip6_mroute.h . The .Va pif_index is the physical interface index of the corresponding local interface.
p A multicast interface is deleted by: d -literal -offset indent /* IPv4 */ vifi_t vifi = vif_index; setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, &vifi, sizeof(vifi)); .Ed d -literal -offset indent /* IPv6 */ mifi_t mifi = mif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, &mifi, sizeof(mifi)); .Ed
p After multicast forwarding is enabled, and the multicast virtual interfaces have been added, the kernel may deliver upcall messages (also called signals later in this text) on the multicast routing socket that was open earlier with .Dv MRT_INIT or .Dv MRT6_INIT . The IPv4 upcalls have a .Vt "struct igmpmsg" header (see n netinet/ip_mroute.h ) with the .Va im_mbz field set to zero. Note that this header follows the structure of .Vt "struct ip" with the protocol field .Va ip_p set to zero. The IPv6 upcalls have a .Vt "struct mrt6msg" header (see n netinet6/ip6_mroute.h ) with the .Va im6_mbz field set to zero. Note that this header follows the structure of .Vt "struct ip6_hdr" with the next header field .Va ip6_nxt set to zero.
p The upcall header contains the .Va im_msgtype and .Va im6_msgtype fields, with the type of the upcall .Dv IGMPMSG_* and .Dv MRT6MSG_* for IPv4 and IPv6, respectively. The values of the rest of the upcall header fields and the body of the upcall message depend on the particular upcall type.
p If the upcall message type is .Dv IGMPMSG_NOCACHE or .Dv MRT6MSG_NOCACHE , this is an indication that a multicast packet has reached the multicast router, but the router has no forwarding state for that packet. Typically, the upcall would be a signal for the multicast routing user-level process to install the appropriate Multicast Forwarding Cache (MFC) entry in the kernel.
p An MFC entry is added by: d -literal -offset indent /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); mc.mfcc_parent = iif_index; for (i = 0; i < maxvifs; i++) mc.mfcc_ttls[i] = oifs_ttl[i]; setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC, &mc, sizeof(mc)); .Ed d -literal -offset indent /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); mc.mf6cc_parent = iif_index; for (i = 0; i < maxvifs; i++) if (oifs_ttl[i] > 0) IF_SET(i, &mc.mf6cc_ifset); setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC, &mc, sizeof(mc)); .Ed
p The .Va source_addr and .Va group_addr fields are the source and group address of the multicast packet (as set in the upcall message). The .Va iif_index is the virtual interface index of the multicast interface the multicast packets for this specific source and group address should be received on. The .Va oifs_ttl[] array contains the minimum TTL (per interface) a multicast packet should have to be forwarded on an outgoing interface. If the TTL value is zero, the corresponding interface is not included in the set of outgoing interfaces. Note that for IPv6 only the set of outgoing interfaces can be specified.
p An MFC entry is deleted by: d -literal -offset indent /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC, &mc, sizeof(mc)); .Ed d -literal -offset indent /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC, &mc, sizeof(mc)); .Ed
p The following method can be used to get various statistics per installed MFC entry in the kernel (e.g., the number of forwarded packets per source and group address): d -literal -offset indent /* IPv4 */ struct sioc_sg_req sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq); .Ed d -literal -offset indent /* IPv6 */ struct sioc_sg_req6 sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq); .Ed
p The following method can be used to get various statistics per multicast virtual interface in the kernel (e.g., the number of forwarded packets per interface): d -literal -offset indent /* IPv4 */ struct sioc_vif_req vreq; memset(&vreq, 0, sizeof(vreq)); vreq.vifi = vif_index; ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq); .Ed d -literal -offset indent /* IPv6 */ struct sioc_mif_req6 mreq; memset(&mreq, 0, sizeof(mreq)); mreq.mifi = vif_index; ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq); .Ed .Ss Advanced Multicast API Programming Guide Adding new features to the kernel makes it difficult to preserve backward compatibility (binary and API), and at the same time to allow user-level processes to take advantage of the new features (if the kernel supports them).
p
One of the mechanisms that allows preserving the backward
compatibility is a sort of negotiation
between the user-level process and the kernel:
l -enum t The user-level process tries to enable in the kernel the set of new
features (and the corresponding API) it would like to use.
t The kernel returns the (sub)set of features it knows about
and is willing to be enabled.
t The user-level process uses only that set of features
the kernel has agreed on.
.El
p
To support backward compatibility, if the user-level process does not
ask for any new features, the kernel defaults to the basic
multicast API (see the
.Sx "Programming Guide"
section).
XXX: edit as appropriate after the advanced multicast API is
supported under IPv6
Currently, the advanced multicast API exists only for IPv4;
in the future there will be IPv6 support as well.
p Below is a summary of the expandable API solution. Note that all new options and structures are defined in n netinet/ip_mroute.h and n netinet6/ip6_mroute.h , unless stated otherwise.
p The user-level process uses new .Fn getsockopt Ns / Ns Fn setsockopt options to perform the API features negotiation with the kernel. This negotiation must be performed right after the multicast routing socket is open. The set of desired/allowed features is stored in a bitset (currently, in .Vt uint32_t i.e., maximum of 32 new features). The new .Fn getsockopt Ns / Ns Fn setsockopt options are .Dv MRT_API_SUPPORT and .Dv MRT_API_CONFIG . An example: d -literal -offset 3n uint32_t v; getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, &v, sizeof(v)); .Ed
p This would set .Va v to the pre-defined bits that the kernel API supports. The eight least significant bits in .Vt uint32_t are the same as the eight possible flags .Dv MRT_MFC_FLAGS_* that can be used in .Va mfcc_flags as part of the new definition of .Vt "struct mfcctl" (see below about those flags), which leaves 24 flags for other new features. The value returned by .Fn getsockopt MRT_API_SUPPORT is read-only; in other words, .Fn setsockopt MRT_API_SUPPORT would fail.
p To modify the API, and to set some specific feature in the kernel, then: d -literal -offset 3n uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF; if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, &v, sizeof(v)) != 0) return (ERROR); if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF) return (OK); /* Success */ else return (ERROR); .Ed
p In other words, when .Fn setsockopt MRT_API_CONFIG is called, the argument to it specifies the desired set of features to be enabled in the API and the kernel. The return value in .Va v is the actual (sub)set of features that were enabled in the kernel. To obtain later the same set of features that were enabled, use: d -literal -offset indent getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, &v, sizeof(v)); .Ed
p The set of enabled features is global. In other words, .Fn setsockopt MRT_API_CONFIG should be called right after .Fn setsockopt MRT_INIT .
p
Currently, the following set of new features is defined:
d -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0)/*disable WRONGVIF signals*/
#define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
#define MRT_MFC_RP (1 << 8) /* enable RP address */
#define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */
.Ed
.Pp
In the future there might be:
.Bd -literal
#define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */
.Ed
.Pp
to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel.
For now this is left-out until it is clear whether
(*,G) MFC support is the preferred solution instead of something more generic
solution for example.
2. The newly defined struct mfcctl2.
p The advanced multicast API uses a newly defined .Vt "struct mfcctl2" instead of the traditional .Vt "struct mfcctl" . The original .Vt "struct mfcctl" is kept as is. The new .Vt "struct mfcctl2" is: d -literal /* * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays * and extends the old struct mfcctl. */ struct mfcctl2 { /* the mfcctl fields */ struct in_addr mfcc_origin; /* ip origin of mcasts */ struct in_addr mfcc_mcastgrp; /* multicast group associated*/ vifi_t mfcc_parent; /* incoming vif */ u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */ /* extension fields */ uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/ struct in_addr mfcc_rp; /* the RP address */ }; .Ed
p The new fields are .Va mfcc_flags[MAXVIFS] and .Va mfcc_rp . Note that for compatibility reasons they are added at the end.
p The .Va mfcc_flags[MAXVIFS] field is used to set various flags per interface per (S,G) entry. Currently, the defined flags are: d -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0)/*disable WRONGVIF signals*/ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ .Ed
p The .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is used to explicitly disable the .Dv IGMPMSG_WRONGVIF kernel signal at the (S,G) granularity if a multicast data packet arrives on the wrong interface. However, it should not be delivered for interfaces that are not set in the outgoing interface, and that are not expecting to become an incoming interface. Hence, if the .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is set for some of the interfaces, then a data packet that arrives on that interface for that MFC entry will NOT trigger a WRONGVIF signal. If that flag is not set, then a signal is triggered (the default action).
p Typically, a multicast routing user-level process would need to know the forwarding bandwidth for some data flow.
p The original solution for measuring the bandwidth of a dataflow was that a user-level process would periodically query the kernel about the number of forwarded packets/bytes per (S,G), and then based on those numbers it would estimate whether a source has been idle, or whether the source's transmission bandwidth is above a threshold. That solution is far from being scalable, hence the need for a new mechanism for bandwidth monitoring.
p Below is a description of the bandwidth monitoring mechanism. l -bullet t If the bandwidth of a data flow satisfies some pre-defined filter, the kernel delivers an upcall on the multicast routing socket to the multicast routing process that has installed that filter. t The bandwidth-upcall filters are installed per (S,G). There can be more than one filter per (S,G). t Instead of supporting all possible comparison operations (i.e., < <= == != > >= ), there is support only for the <= and >= operations, because this makes the kernel-level implementation simpler, and because practically we need only those two. Furthermore, the missing operations can be simulated by secondary user-level filtering of those <= and >= filters. For example, to simulate !=, then we need to install filter .Dq bw <= 0xffffffff , and after an upcall is received, we need to check whether .Dq measured_bw != expected_bw . t The bandwidth-upcall mechanism is enabled by .Fn setsockopt MRT_API_CONFIG for the .Dv MRT_MFC_BW_UPCALL flag. t The bandwidth-upcall filters are added/deleted by the new .Fn setsockopt MRT_ADD_BW_UPCALL and .Fn setsockopt MRT_DEL_BW_UPCALL respectively (with the appropriate .Vt "struct bw_upcall" argument of course). .El
p From an application point of view, a developer needs to know about the following: d -literal /* * Structure for installing or delivering an upcall if the * measured bandwidth is above or below a threshold. * * User programs (e.g. daemons) may have a need to know when the * bandwidth used by some data flow is above or below some threshold. * This interface allows the userland to specify the threshold (in * bytes and/or packets) and the measurement interval. Flows are * all packet with the same source and destination IP address. * At the moment the code is only used for multicast destinations * but there is nothing that prevents its use for unicast. * * The measurement interval cannot be shorter than some Tmin (3s). * The threshold is set in packets and/or bytes per_interval. * * Measurement works as follows: * * For >= measurements: * The first packet marks the start of a measurement interval. * During an interval we count packets and bytes, and when we * pass the threshold we deliver an upcall and we are done. * The first packet after the end of the interval resets the * count and restarts the measurement. * * For <= measurement: * We start a timer to fire at the end of the interval, and * then for each incoming packet we count packets and bytes. * When the timer fires, we compare the value with the threshold, * schedule an upcall if we are below, and restart the measurement * (reschedule timer and zero counters). */ struct bw_data { struct timeval b_time; uint64_t b_packets; uint64_t b_bytes; }; struct bw_upcall { struct in_addr bu_src; /* source address */ struct in_addr bu_dst; /* destination address */ uint32_t bu_flags; /* misc flags (see below) */ #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */ #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */ #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */ #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */ #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/ struct bw_data bu_threshold; /* the bw threshold */ struct bw_data bu_measured; /* the measured bw */ }; /* max. number of upcalls to deliver together */ #define BW_UPCALLS_MAX 128 /* min. threshold time interval for bandwidth measurement */ #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0 .Ed
p The .Vt bw_upcall structure is used as an argument to .Fn setsockopt MRT_ADD_BW_UPCALL and .Fn setsockopt MRT_DEL_BW_UPCALL . Each .Fn setsockopt MRT_ADD_BW_UPCALL installs a filter in the kernel for the source and destination address in the .Vt bw_upcall argument, and that filter will trigger an upcall according to the following pseudo-algorithm: d -literal if (bw_upcall_oper IS ">=") { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets >= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes >= threshold_bytes))) SEND_UPCALL("measured bandwidth is >= threshold"); } if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets <= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes <= threshold_bytes))) SEND_UPCALL("measured bandwidth is <= threshold"); } .Ed
p In the same .Vt bw_upcall , the unit can be specified in both BYTES and PACKETS. However, the GEQ and LEQ flags are mutually exclusive.
p Basically, an upcall is delivered if the measured bandwidth is >= or <= the threshold bandwidth (within the specified measurement interval). For practical reasons, the smallest value for the measurement interval is 3 seconds. If smaller values are allowed, then the bandwidth estimation may be less accurate, or the potentially very high frequency of the generated upcalls may introduce too much overhead. For the >= operation, the answer may be known before the end of .Va threshold_interval , therefore the upcall may be delivered earlier. For the <= operation however, we must wait until the threshold interval has expired to know the answer. .Sh EXAMPLES d -literal -offset indent struct bw_upcall bw_upcall; /* Assign all bw_upcall fields as appropriate */ memset(&bw_upcall, 0, sizeof(bw_upcall)); memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src)); memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst)); bw_upcall.bu_threshold.b_data = threshold_interval; bw_upcall.bu_threshold.b_packets = threshold_packets; bw_upcall.bu_threshold.b_bytes = threshold_bytes; if (is_threshold_in_packets) bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS; if (is_threshold_in_bytes) bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES; do { if (is_geq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_GEQ; break; } if (is_leq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_LEQ; break; } return (ERROR); } while (0); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL, &bw_upcall, sizeof(bw_upcall)); .Ed
p To delete a single filter, use .Dv MRT_DEL_BW_UPCALL , and the fields of bw_upcall must be set to exactly same as when .Dv MRT_ADD_BW_UPCALL was called.
p To delete all bandwidth filters for a given (S,G), then only the .Va bu_src and .Va bu_dst fields in .Vt "struct bw_upcall" need to be set, and then just set only the .Dv BW_UPCALL_DELETE_ALL flag inside field .Va bw_upcall.bu_flags .
p The bandwidth upcalls are received by aggregating them in the new upcall message: d -literal -offset indent #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */ .Ed
p This message is an array of .Vt "struct bw_upcall" elements (up to .Dv BW_UPCALLS_MAX = 128). The upcalls are delivered when there are 128 pending upcalls, or when 1 second has expired since the previous upcall (whichever comes first). In an .Vt "struct upcall" element, the .Va bu_measured field is filled in to indicate the particular measured values. However, because of the way the particular intervals are measured, the user should be careful how .Va bu_measured.b_time is used. For example, if the filter is installed to trigger an upcall if the number of packets is >= 1, then .Va bu_measured may have a value of zero in the upcalls after the first one, because the measured interval for >= filters is .Dq clocked by the forwarded packets. Hence, this upcall mechanism should not be used for measuring the exact value of the bandwidth of the forwarded data. To measure the exact bandwidth, the user would need to get the forwarded packets statistics with the .Fn ioctl SIOCGETSGCNT mechanism (see the .Sx Programming Guide section).
p
Note that the upcalls for a filter are delivered until the specific
filter is deleted, but no more frequently than once per
.Va bu_threshold.b_time .
For example, if the filter is specified to
deliver a signal if bw >= 1 packet, the first packet will trigger a
signal, but the next upcall will be triggered no earlier than
.Va bu_threshold.b_time
after the previous upcall.
.Sh SEE ALSO
.Xr getsockopt 2 ,
.Xr recvfrom 2 ,
.Xr recvmsg 2 ,
.Xr setsockopt 2 ,
.Xr socket 2 ,
.Xr icmp6 4 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr intro 4 ,
.Xr ip 4 ,
.Xr ip6 4 ,
.Xr mrouted 8 ,
.Xr sysctl 8
.Sh AUTHORS
.An -nosplit
The original multicast code was written by
.An David Waitzman
(BBN Labs),
and later modified by the following individuals:
.An Steve Deering
(Stanford),
.An Mark J. Steiglitz
(Stanford),
.An Van Jacobson
(LBL),
.An Ajit Thyagarajan
(PARC),
.An Bill Fenner
(PARC).
p The IPv6 multicast support was implemented by the KAME project
q Lk https://www.kame.net , and was based on the IPv4 multicast code. The advanced multicast API and the multicast bandwidth monitoring were implemented by .An Pavlin Radoslavov (ICSI) in collaboration with .An Chris Brown (NextHop).
p This manual page was written by .An Pavlin Radoslavov (ICSI).