1 .\" Copyright (c) 2001-2003 International Computer Science Institute
3 .\" Permission is hereby granted, free of charge, to any person obtaining a
4 .\" copy of this software and associated documentation files (the "Software"),
5 .\" to deal in the Software without restriction, including without limitation
6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
7 .\" and/or sell copies of the Software, and to permit persons to whom the
8 .\" Software is furnished to do so, subject to the following conditions:
10 .\" The above copyright notice and this permission notice shall be included in
11 .\" all copies or substantial portions of the Software.
13 .\" The names and trademarks of copyright holders may not be used in
14 .\" advertising or publicity pertaining to the software without specific
15 .\" prior permission. Title to copyright in this software and any associated
16 .\" documentation will at all times remain with the copyright holders.
18 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 .\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24 .\" DEALINGS IN THE SOFTWARE.
26 .\" $FreeBSD: /repoman/r/ncvs/src/share/man/man4/multicast.4,v 1.1 2003/10/17 15:12:01 bmah Exp $
27 .\" $DragonFly: src/share/man/man4/multicast.4,v 1.1 2003/10/18 21:40:41 hmp Exp $
38 .Cd "options MROUTING"
43 .In netinet/ip_mroute.h
44 .In netinet6/ip6_mroute.h
46 .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen"
48 .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen"
50 .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen"
52 .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen"
54 .Tn "Multicast routing"
55 is used to efficiently propagate data
56 packets to a set of multicast listeners in multipoint networks.
57 If unicast is used to replicate the data to all listeners,
58 then some of the network links may carry multiple copies of the same
60 With multicast routing, the overhead is reduced to one copy
61 (at most) per network link.
63 All multicast-capable routers must run a common multicast routing
65 The Distance Vector Multicast Routing Protocol (DVMRP)
66 was the first developed multicast routing protocol.
67 Later, other protocols such as Multicast Extensions to OSPF (MOSPF),
68 Core Based Trees (CBT),
69 Protocol Independent Multicast - Sparse Mode (PIM-SM),
70 and Protocol Independent Multicast - Dense Mode (PIM-DM)
71 were developed as well.
73 To start multicast routing,
74 the user must enable multicast forwarding in the kernel
77 about the kernel configuration options),
78 and must run a multicast routing capable user-level process.
79 From developer's point of view,
80 the programming guide described in the
81 .Sx "Programming Guide"
82 section should be used to control the multicast forwarding in the kernel.
85 This section provides information about the basic multicast routing API.
87 .Dq advanced multicast API
89 .Sx "Advanced Multicast API Programming Guide"
92 First, a multicast routing socket must be open.
93 That socket would be used
94 to control the multicast forwarding in the kernel.
95 Note that most operations below require certain privilege
96 (i.e., root privilege):
101 mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP);
106 mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6);
109 Note that if the router needs to open an IGMP or ICMPv6 socket
110 (in case of IPv4 and IPv6 respectively)
111 for sending or receiving of IGMP or MLD multicast group membership messages,
112 then the same mrouter_s4 or mrouter_s6 sockets should be used
113 for sending and receiving respectively IGMP or MLD messages.
114 In case of BSD-derived kernel, it may be possible to open separate sockets
115 for IGMP or MLD messages only.
116 However, some other kernels (e.g., Linux) require that the multicast
117 routing socket must be used for sending and receiving of IGMP or MLD
119 Therefore, for portability reason the multicast
120 routing socket should be reused for IGMP and MLD messages as well.
122 After the multicast routing socket is open, it can be used to enable
123 or disable multicast forwarding in the kernel:
126 int v = 1; /* 1 to enable, or 0 to disable */
127 setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v));
132 int v = 1; /* 1 to enable, or 0 to disable */
133 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v));
135 /* If necessary, filter all ICMPv6 messages */
136 struct icmp6_filter filter;
137 ICMP6_FILTER_SETBLOCKALL(&filter);
138 setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter,
142 After multicast forwarding is enabled, the multicast routing socket
143 can be used to enable PIM processing in the kernel if we are running PIM-SM or
148 For each network interface (e.g., physical or a virtual tunnel)
149 that would be used for multicast forwarding, a corresponding
150 multicast interface must be added to the kernel:
154 memset(&vc, 0, sizeof(vc));
155 /* Assign all vifctl fields as appropriate */
156 vc.vifc_vifi = vif_index;
157 vc.vifc_flags = vif_flags;
158 vc.vifc_threshold = min_ttl_threshold;
159 vc.vifc_rate_limit = max_rate_limit;
160 memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr));
161 if (vc.vifc_flags & VIFF_TUNNEL)
162 memcpy(&vc.vifc_rmt_addr, &vif_remote_address,
163 sizeof(vc.vifc_rmt_addr));
164 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc,
170 must be unique per vif.
175 flags as defined in <netinet/ip_mroute.h>.
177 .Dq min_ttl_threshold
178 contains the minimum TTL a multicast data packet must have to be
179 forwarded on that vif.
180 Typically, it would have value of 1.
183 contains the maximum rate (in bits/s) of the multicast data packets forwarded
185 Value of 0 means no limit.
187 .Dq vif_local_address
188 contains the local IP address of the corresponding local interface.
190 .Dq vif_remote_address
191 contains the remote IP address in case of DVMRP multicast tunnels.
196 memset(&mc, 0, sizeof(mc));
197 /* Assign all mif6ctl fields as appropriate */
198 mc.mif6c_mifi = mif_index;
199 mc.mif6c_flags = mif_flags;
200 mc.mif6c_pifi = pif_index;
201 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc,
207 must be unique per vif.
212 flags as defined in <netinet6/ip6_mroute.h>.
215 is the physical interface index of the corresponding local interface.
217 A multicast interface is deleted by:
220 vifi_t vifi = vif_index;
221 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi,
227 mifi_t mifi = mif_index;
228 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi,
232 After the multicast forwarding is enabled, and the multicast virtual
234 added, the kernel may deliver upcall messages (also called signals
235 later in this text) on the multicast routing socket that was open
240 The IPv4 upcalls have
242 header (see <netinet/ip_mroute.h>) with field
245 Note that this header follows the structure of
247 with the protocol field
250 The IPv6 upcalls have
252 header (see <netinet6/ip6_mroute.h>) with field
255 Note that this header follows the structure of
257 with the next header field
261 The upcall header contains field
265 with the type of the upcall
269 for IPv4 and IPv6 respectively.
270 The values of the rest of the upcall header fields
271 and the body of the upcall message depend on the particular upcall type.
273 If the upcall message type is
276 .Dq MRT6MSG_NOCACHE ,
277 this is an indication that a multicast packet has reached the multicast
278 router, but the router has no forwarding state for that packet.
279 Typically, the upcall would be a signal for the multicast routing
280 user-level process to install the appropriate Multicast Forwarding
281 Cache (MFC) entry in the kernel.
283 A MFC entry is added by:
287 memset(&mc, 0, sizeof(mc));
288 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
289 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
290 mc.mfcc_parent = iif_index;
291 for (i = 0; i < maxvifs; i++)
292 mc.mfcc_ttls[i] = oifs_ttl[i];
293 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC,
294 (void *)&mc, sizeof(mc));
300 memset(&mc, 0, sizeof(mc));
301 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
302 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
303 mc.mf6cc_parent = iif_index;
304 for (i = 0; i < maxvifs; i++)
306 IF_SET(i, &mc.mf6cc_ifset);
307 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC,
308 (void *)&mc, sizeof(mc));
315 are the source and group address of the multicast packet (as set
316 in the upcall message).
319 is the virtual interface index of the multicast interface the multicast
320 packets for this specific source and group address should be received on.
323 array contains the minimum TTL (per interface) a multicast packet
324 should have to be forwarded on an outgoing interface.
325 If the TTL value is zero, the corresponding interface is not included
326 in the set of outgoing interfaces.
327 Note that in case of IPv6 only the set of outgoing interfaces can
330 A MFC entry is deleted by:
334 memset(&mc, 0, sizeof(mc));
335 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
336 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
337 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC,
338 (void *)&mc, sizeof(mc));
344 memset(&mc, 0, sizeof(mc));
345 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
346 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
347 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC,
348 (void *)&mc, sizeof(mc));
351 The following method can be used to get various statistics per
352 installed MFC entry in the kernel (e.g., the number of forwarded
353 packets per source and group address):
356 struct sioc_sg_req sgreq;
357 memset(&sgreq, 0, sizeof(sgreq));
358 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
359 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
360 ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq);
365 struct sioc_sg_req6 sgreq;
366 memset(&sgreq, 0, sizeof(sgreq));
367 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
368 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
369 ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq);
372 The following method can be used to get various statistics per
373 multicast virtual interface in the kernel (e.g., the number of forwarded
374 packets per interface):
377 struct sioc_vif_req vreq;
378 memset(&vreq, 0, sizeof(vreq));
379 vreq.vifi = vif_index;
380 ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq);
385 struct sioc_mif_req6 mreq;
386 memset(&mreq, 0, sizeof(mreq));
387 mreq.mifi = vif_index;
388 ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq);
391 .Ss Advanced Multicast API Programming Guide
392 If we want to add new features in the kernel, it becomes difficult
393 to preserve backward compatibility (binary and API),
394 and at the same time to allow user-level processes to take advantage of
395 the new features (if the kernel supports them).
397 One of the mechanisms that allows us to preserve the backward
398 compatibility is a sort of negotiation
399 between the user-level process and the kernel:
402 The user-level process tries to enable in the kernel the set of new
403 features (and the corresponding API) it would like to use.
405 The kernel returns the (sub)set of features it knows about
406 and is willing to be enabled.
408 The user-level process uses only that set of features
409 the kernel has agreed on.
413 To support backward compatibility, if the user-level process doesn't
414 ask for any new features, the kernel defaults to the basic
415 multicast API (see the
416 .Sx "Programming Guide"
418 .\" XXX: edit as appropriate after the advanced multicast API is
419 .\" supported under IPv6
420 Currently, the advanced multicast API exists only for IPv4;
421 in the future there will be IPv6 support as well.
423 Below is a summary of the expandable API solution.
424 Note that all new options and structures are defined
425 in <netinet/ip_mroute.h> and <netinet6/ip6_mroute.h>,
426 unless stated otherwise.
428 The user-level process uses new get/setsockopt() options to
429 perform the API features negotiation with the kernel.
430 This negotiation must be performed right after the multicast routing
432 The set of desired/allowed features is stored in a bitset
433 (currently, in uint32_t; i.e., maximum of 32 new features).
434 The new get/setsockopt() options are
441 getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v));
446 the pre-defined bits that the kernel API supports.
447 The eight least significant bits in uint32_t are same as the
452 as part of the new definition of
454 (see below about those flags), which leaves 24 flags for other new features.
455 The value returned by getsockopt(MRT_API_SUPPORT) is read-only; in other
456 words, setsockopt(MRT_API_SUPPORT) would fail.
458 To modify the API, and to set some specific feature in the kernel, then:
460 uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF;
461 if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v))
465 if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF)
466 return (OK); /* Success */
471 In other words, when setsockopt(MRT_API_CONFIG) is called, the
472 argument to it specifies the desired set of features to
473 be enabled in the API and the kernel.
476 is the actual (sub)set of features that were enabled in the kernel.
477 To obtain later the same set of features that were enabled, then:
479 getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v));
482 The set of enabled features is global.
483 In other words, setsockopt(MRT_API_CONFIG)
484 should be called right after setsockopt(MRT_INIT).
486 Currently, the following set of new features is defined:
488 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
489 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
490 #define MRT_MFC_RP (1 << 8) /* enable RP address */
491 #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */
494 .\" In the future there might be:
496 .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */
499 .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel.
500 .\" For now this is left-out until it is clear whether
501 .\" (*,G) MFC support is the preferred solution instead of something more generic
502 .\" solution for example.
504 .\" 2. The newly defined struct mfcctl2.
507 The advanced multicast API uses a newly defined
509 instead of the traditional
519 * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays
520 * and extends the old struct mfcctl.
523 /* the mfcctl fields */
524 struct in_addr mfcc_origin; /* ip origin of mcasts */
525 struct in_addr mfcc_mcastgrp; /* multicast group associated*/
526 vifi_t mfcc_parent; /* incoming vif */
527 u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */
529 /* extension fields */
530 uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/
531 struct in_addr mfcc_rp; /* the RP address */
536 .Dq mfcc_flags[MAXVIFS]
539 Note that for compatibility reasons they are added at the end.
542 .Dq mfcc_flags[MAXVIFS]
543 field is used to set various flags per
544 interface per (S,G) entry.
545 Currently, the defined flags are:
547 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
548 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
552 .Dq MRT_MFC_FLAGS_DISABLE_WRONGVIF
553 flag is used to explicitly disable the
555 kernel signal at the (S,G) granularity if a multicast data packet
556 arrives on the wrong interface.
557 Usually, this signal is used to
558 complete the shortest-path switch in case of PIM-SM multicast routing,
559 or to trigger a PIM assert message.
560 However, it should not be delivered for interfaces that are not in
561 the outgoing interface set, and that are not expecting to
562 become an incoming interface.
564 .Dq MRT_MFC_FLAGS_DISABLE_WRONGVIF
565 flag is set for some of the
566 interfaces, then a data packet that arrives on that interface for
567 that MFC entry will NOT trigger a WRONGVIF signal.
568 If that flag is not set, then a signal is triggered (the default action).
571 .Dq MRT_MFC_FLAGS_BORDER_VIF
572 flag is used to specify whether the Border-bit in PIM
573 Register messages should be set (in case when the Register encapsulation
574 is performed inside the kernel).
575 If it is set for the special PIM Register kernel virtual interface
578 the Border-bit in the Register messages sent to the RP will be set.
580 The remaining six bits are reserved for future usage.
584 field is used to specify the RP address (in case of PIM-SM multicast routing)
586 group G if we want to perform kernel-level PIM Register encapsulation.
589 field is used only if the
591 advanced API flag/capability has been successfully set by
592 setsockopt(MRT_API_CONFIG).
595 .\" 3. Kernel-level PIM Register encapsulation
599 flag was successfully set by
600 setsockopt(MRT_API_CONFIG), then the kernel will attempt to perform
601 the PIM Register encapsulation itself instead of sending the
602 multicast data packets to user level (inside IGMPMSG_WHOLEPKT
603 upcalls) for user-level encapsulation.
604 The RP address would be taken from the
611 flag was successfully set, if the
616 kernel will still deliver an IGMPMSG_WHOLEPKT upcall with the
617 multicast data packet to the user-level process.
619 In addition, if the multicast data packet is too large to fit within
620 a single IP packet after the PIM Register encapsulation (e.g., if
621 its size was on the order of 65500 bytes), the data packet will be
622 fragmented, and then each of the fragments will be encapsulated
624 Note that typically a multicast data packet can be that
625 large only if it was originated locally from the same hosts that
626 performs the encapsulation; otherwise the transmission of the
627 multicast data packet over Ethernet for example would have
628 fragmented it into much smaller pieces.
630 .\" Note that if this code is ported to IPv6, we may need the kernel to
631 .\" perform MTU discovery to the RP, and keep those discoveries inside
632 .\" the kernel so the encapsulating router may send back ICMP
633 .\" Fragmentation Required if the size of the multicast data packet is
634 .\" too large (see "Encapsulating data packets in the Register Tunnel"
635 .\" in Section 4.4.1 in the PIM-SM spec
636 .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}).
637 .\" For IPv4 we may be able to get away without it, but for IPv6 we need
640 .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls".
643 Typically, a multicast routing user-level process would need to know the
644 forwarding bandwidth for some data flow.
645 For example, the multicast routing process may want to timeout idle MFC
646 entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if
647 the bandwidth rate is above a threshold for example.
649 The original solution for measuring the bandwidth of a dataflow was
650 that a user-level process would periodically
651 query the kernel about the number of forwarded packets/bytes per
652 (S,G), and then based on those numbers it would estimate whether a source
653 has been idle, or whether the source's transmission bandwidth is above a
655 That solution is far from being scalable, hence the need for a new
656 mechanism for bandwidth monitoring.
658 Below is a description of the bandwidth monitoring mechanism.
661 If the bandwidth of a data flow satisfies some pre-defined filter,
662 the kernel delivers an upcall on the multicast routing socket
663 to the multicast routing process that has installed that filter.
665 The bandwidth-upcall filters are installed per (S,G). There can be
666 more than one filter per (S,G).
668 Instead of supporting all possible comparison operations
669 (i.e., < <= == != > >= ), there is support only for the
670 <= and >= operations,
671 because this makes the kernel-level implementation simpler,
672 and because practically we need only those two.
673 Further, the missing operations can be simulated by secondary
674 user-level filtering of those <= and >= filters.
675 For example, to simulate !=, then we need to install filter
676 .Dq bw <= 0xffffffff ,
678 upcall is received, we need to check whether
679 .Dq measured_bw != expected_bw .
681 The bandwidth-upcall mechanism is enabled by
682 setsockopt(MRT_API_CONFIG) for the MRT_MFC_BW_UPCALL flag.
684 The bandwidth-upcall filters are added/deleted by the new
685 setsockopt(MRT_ADD_BW_UPCALL) and setsockopt(MRT_DEL_BW_UPCALL)
686 respectively (with the appropriate
691 From application point of view, a developer needs to know about
695 * Structure for installing or delivering an upcall if the
696 * measured bandwidth is above or below a threshold.
698 * User programs (e.g. daemons) may have a need to know when the
699 * bandwidth used by some data flow is above or below some threshold.
700 * This interface allows the userland to specify the threshold (in
701 * bytes and/or packets) and the measurement interval. Flows are
702 * all packet with the same source and destination IP address.
703 * At the moment the code is only used for multicast destinations
704 * but there is nothing that prevents its use for unicast.
706 * The measurement interval cannot be shorter than some Tmin (currently, 3s).
707 * The threshold is set in packets and/or bytes per_interval.
709 * Measurement works as follows:
711 * For >= measurements:
712 * The first packet marks the start of a measurement interval.
713 * During an interval we count packets and bytes, and when we
714 * pass the threshold we deliver an upcall and we are done.
715 * The first packet after the end of the interval resets the
716 * count and restarts the measurement.
718 * For <= measurement:
719 * We start a timer to fire at the end of the interval, and
720 * then for each incoming packet we count packets and bytes.
721 * When the timer fires, we compare the value with the threshold,
722 * schedule an upcall if we are below, and restart the measurement
723 * (reschedule timer and zero counters).
727 struct timeval b_time;
733 struct in_addr bu_src; /* source address */
734 struct in_addr bu_dst; /* destination address */
735 uint32_t bu_flags; /* misc flags (see below) */
736 #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */
737 #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */
738 #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */
739 #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */
740 #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/
741 struct bw_data bu_threshold; /* the bw threshold */
742 struct bw_data bu_measured; /* the measured bw */
745 /* max. number of upcalls to deliver together */
746 #define BW_UPCALLS_MAX 128
747 /* min. threshold time interval for bandwidth measurement */
748 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3
749 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0
754 structure is used as an argument to
755 setsockopt(MRT_ADD_BW_UPCALL) and setsockopt(MRT_DEL_BW_UPCALL).
756 Each setsockopt(MRT_ADD_BW_UPCALL) installs a filter in the kernel
757 for the source and destination address in the
760 and that filter will trigger an upcall according to the following
763 if (bw_upcall_oper IS ">=") {
764 if (((bw_upcall_unit & PACKETS == PACKETS) &&
765 (measured_packets >= threshold_packets)) ||
766 ((bw_upcall_unit & BYTES == BYTES) &&
767 (measured_bytes >= threshold_bytes)))
768 SEND_UPCALL("measured bandwidth is >= threshold");
770 if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) {
771 if (((bw_upcall_unit & PACKETS == PACKETS) &&
772 (measured_packets <= threshold_packets)) ||
773 ((bw_upcall_unit & BYTES == BYTES) &&
774 (measured_bytes <= threshold_bytes)))
775 SEND_UPCALL("measured bandwidth is <= threshold");
781 the unit can be specified in both BYTES and PACKETS.
782 However, the GEQ and LEQ flags are mutually exclusive.
784 Basically, an upcall is delivered if the measured bandwidth is >= or
785 <= the threshold bandwidth (within the specified measurement
787 For practical reasons, the smallest value for the measurement
788 interval is 3 seconds.
789 If smaller values are allowed, then the bandwidth
790 estimation may be less accurate, or the potentially very high frequency
791 of the generated upcalls may introduce too much overhead.
792 For the >= operation, the answer may be known before the end of
793 .Dq threshold_interval ,
794 therefore the upcall may be delivered earlier.
795 For the <= operation however, we must wait
796 until the threshold interval has expired to know the answer.
800 struct bw_upcall bw_upcall;
801 /* Assign all bw_upcall fields as appropriate */
802 memset(&bw_upcall, 0, sizeof(bw_upcall));
803 memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src));
804 memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst));
805 bw_upcall.bu_threshold.b_data = threshold_interval;
806 bw_upcall.bu_threshold.b_packets = threshold_packets;
807 bw_upcall.bu_threshold.b_bytes = threshold_bytes;
808 if (is_threshold_in_packets)
809 bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS;
810 if (is_threshold_in_bytes)
811 bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES;
814 bw_upcall.bu_flags |= BW_UPCALL_GEQ;
818 bw_upcall.bu_flags |= BW_UPCALL_LEQ;
823 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL,
824 (void *)&bw_upcall, sizeof(bw_upcall));
827 To delete a single filter, then use MRT_DEL_BW_UPCALL,
828 and the fields of bw_upcall must be set
829 exactly same as when MRT_ADD_BW_UPCALL was called.
831 To delete all bandwidth filters for a given (S,G), then
838 need to be set, and then just set only the
839 .Dq BW_UPCALL_DELETE_ALL
841 .Dq bw_upcall.bu_flags .
843 The bandwidth upcalls are received by aggregating them in the new upcall
846 #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */
849 This message is an array of
851 elements (up to BW_UPCALLS_MAX = 128).
853 delivered when there are 128 pending upcalls, or when 1 second has
854 expired since the previous upcall (whichever comes first).
859 field is filled-in to
860 indicate the particular measured values.
861 However, because of the way
862 the particular intervals are measured, the user should be careful how
863 bu_measured.b_time is used.
865 filter is installed to trigger an upcall if the number of packets
868 may have a value of zero in the upcalls after the
869 first one, because the measured interval for >= filters is
871 by the forwarded packets.
872 Hence, this upcall mechanism should not be used for measuring
873 the exact value of the bandwidth of the forwarded data.
874 To measure the exact bandwidth, the user would need to
875 get the forwarded packets statistics with the ioctl(SIOCGETSGCNT)
878 .Sx Programming Guide
881 Note that the upcalls for a filter are delivered until the specific
882 filter is deleted, but no more frequently than once per
883 .Dq bu_threshold.b_time .
884 For example, if the filter is specified to
885 deliver a signal if bw >= 1 packet, the first packet will trigger a
886 signal, but the next upcall will be triggered no earlier than
887 .Dq bu_threshold.b_time
888 after the previous upcall.
907 The original multicast code was written by David Waitzman (BBN Labs),
908 and later modified by the following individuals:
909 Steve Deering (Stanford), Mark J. Steiglitz (Stanford),
910 Van Jacobson (LBL), Ajit Thyagarajan (PARC),
912 The IPv6 multicast support was implemented by the KAME project
913 (http://www.kame.net), and was based on the IPv4 multicast code.
914 The advanced multicast API and the multicast bandwidth
915 monitoring were implemented by Pavlin Radoslavov (ICSI)
916 in collaboration with Chris Brown (NextHop).
918 This manual page was written by Pavlin Radoslavov (ICSI).
projects / dragonfly.git / blob