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.
37 .Cd "options MROUTING"
42 .In netinet/ip_mroute.h
43 .In netinet6/ip6_mroute.h
45 .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen"
47 .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen"
49 .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen"
51 .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen"
53 .Tn "Multicast routing"
54 is used to efficiently propagate data
55 packets to a set of multicast listeners in multipoint networks.
56 If unicast is used to replicate the data to all listeners,
57 then some of the network links may carry multiple copies of the same
59 With multicast routing, the overhead is reduced to one copy
60 (at most) per network link.
62 All multicast-capable routers must run a common multicast routing
64 The Distance Vector Multicast Routing Protocol (DVMRP)
65 was the first developed multicast routing protocol.
66 Later, other protocols such as Multicast Extensions to OSPF (MOSPF),
67 Core Based Trees (CBT),
68 Protocol Independent Multicast - Sparse Mode (PIM-SM),
69 and Protocol Independent Multicast - Dense Mode (PIM-DM)
70 were developed as well.
72 To start multicast routing,
73 the user must enable multicast forwarding in the kernel
76 about the kernel configuration options),
77 and must run a multicast routing capable user-level process.
78 From developer's point of view,
79 the programming guide described in the
80 .Sx "Programming Guide"
81 section should be used to control the multicast forwarding in the kernel.
84 This section provides information about the basic multicast routing API.
86 .Dq advanced multicast API
88 .Sx "Advanced Multicast API Programming Guide"
91 First, a multicast routing socket must be open.
92 That socket would be used
93 to control the multicast forwarding in the kernel.
94 Note that most operations below require certain privilege
95 (i.e., root privilege):
99 mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP);
103 mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6);
106 Note that if the router needs to open an IGMP or ICMPv6 socket
107 (in case of IPv4 and IPv6 respectively)
108 for sending or receiving of IGMP or MLD multicast group membership messages,
113 sockets should be used
114 for sending and receiving respectively IGMP or MLD messages.
117 -derived kernel, it may be possible to open separate sockets
118 for IGMP or MLD messages only.
119 However, some other kernels (e.g.,
121 require that the multicast
122 routing socket must be used for sending and receiving of IGMP or MLD
124 Therefore, for portability reason the multicast
125 routing socket should be reused for IGMP and MLD messages as well.
127 After the multicast routing socket is open, it can be used to enable
128 or disable multicast forwarding in the kernel:
131 int v = 1; /* 1 to enable, or 0 to disable */
132 setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v));
136 int v = 1; /* 1 to enable, or 0 to disable */
137 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v));
139 /* If necessary, filter all ICMPv6 messages */
140 struct icmp6_filter filter;
141 ICMP6_FILTER_SETBLOCKALL(&filter);
142 setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter,
146 After multicast forwarding is enabled, the multicast routing socket
147 can be used to enable PIM processing in the kernel if we are running PIM-SM or
152 For each network interface (e.g., physical or a virtual tunnel)
153 that would be used for multicast forwarding, a corresponding
154 multicast interface must be added to the kernel:
158 memset(&vc, 0, sizeof(vc));
159 /* Assign all vifctl fields as appropriate */
160 vc.vifc_vifi = vif_index;
161 vc.vifc_flags = vif_flags;
162 vc.vifc_threshold = min_ttl_threshold;
163 vc.vifc_rate_limit = max_rate_limit;
164 memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr));
165 if (vc.vifc_flags & VIFF_TUNNEL)
166 memcpy(&vc.vifc_rmt_addr, &vif_remote_address,
167 sizeof(vc.vifc_rmt_addr));
168 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc,
174 must be unique per vif.
180 .In netinet/ip_mroute.h .
182 .Va min_ttl_threshold
183 contains the minimum TTL a multicast data packet must have to be
184 forwarded on that vif.
185 Typically, it would have value of 1.
188 contains the maximum rate (in bits/s) of the multicast data packets forwarded
190 Value of 0 means no limit.
192 .Va vif_local_address
193 contains the local IP address of the corresponding local interface.
195 .Va vif_remote_address
196 contains the remote IP address in case of DVMRP multicast tunnels.
200 memset(&mc, 0, sizeof(mc));
201 /* Assign all mif6ctl fields as appropriate */
202 mc.mif6c_mifi = mif_index;
203 mc.mif6c_flags = mif_flags;
204 mc.mif6c_pifi = pif_index;
205 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc,
211 must be unique per vif.
217 .In netinet6/ip6_mroute.h .
220 is the physical interface index of the corresponding local interface.
222 A multicast interface is deleted by:
225 vifi_t vifi = vif_index;
226 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi,
231 mifi_t mifi = mif_index;
232 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi,
236 After the multicast forwarding is enabled, and the multicast virtual
238 added, the kernel may deliver upcall messages (also called signals
239 later in this text) on the multicast routing socket that was open
244 The IPv4 upcalls have
247 .In netinet/ip_mroute.h )
251 Note that this header follows the structure of
253 with the protocol field
256 The IPv6 upcalls have
259 .In netinet6/ip6_mroute.h )
263 Note that this header follows the structure of
265 with the next header field
269 The upcall header contains field
273 with the type of the upcall
277 for IPv4 and IPv6 respectively.
278 The values of the rest of the upcall header fields
279 and the body of the upcall message depend on the particular upcall type.
281 If the upcall message type is
284 .Dv MRT6MSG_NOCACHE ,
285 this is an indication that a multicast packet has reached the multicast
286 router, but the router has no forwarding state for that packet.
287 Typically, the upcall would be a signal for the multicast routing
288 user-level process to install the appropriate Multicast Forwarding
289 Cache (MFC) entry in the kernel.
291 An MFC entry is added by:
295 memset(&mc, 0, sizeof(mc));
296 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
297 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
298 mc.mfcc_parent = iif_index;
299 for (i = 0; i < maxvifs; i++)
300 mc.mfcc_ttls[i] = oifs_ttl[i];
301 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC,
302 (void *)&mc, sizeof(mc));
307 memset(&mc, 0, sizeof(mc));
308 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
309 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
310 mc.mf6cc_parent = iif_index;
311 for (i = 0; i < maxvifs; i++)
313 IF_SET(i, &mc.mf6cc_ifset);
314 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC,
315 (void *)&mc, sizeof(mc));
322 are the source and group address of the multicast packet (as set
323 in the upcall message).
326 is the virtual interface index of the multicast interface the multicast
327 packets for this specific source and group address should be received on.
330 array contains the minimum TTL (per interface) a multicast packet
331 should have to be forwarded on an outgoing interface.
332 If the TTL value is zero, the corresponding interface is not included
333 in the set of outgoing interfaces.
334 Note that in case of IPv6 only the set of outgoing interfaces can
337 An MFC entry is deleted by:
341 memset(&mc, 0, sizeof(mc));
342 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
343 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
344 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC,
345 (void *)&mc, sizeof(mc));
350 memset(&mc, 0, sizeof(mc));
351 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
352 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
353 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC,
354 (void *)&mc, sizeof(mc));
357 The following method can be used to get various statistics per
358 installed MFC entry in the kernel (e.g., the number of forwarded
359 packets per source and group address):
362 struct sioc_sg_req sgreq;
363 memset(&sgreq, 0, sizeof(sgreq));
364 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
365 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
366 ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq);
370 struct sioc_sg_req6 sgreq;
371 memset(&sgreq, 0, sizeof(sgreq));
372 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
373 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
374 ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq);
377 The following method can be used to get various statistics per
378 multicast virtual interface in the kernel (e.g., the number of forwarded
379 packets per interface):
382 struct sioc_vif_req vreq;
383 memset(&vreq, 0, sizeof(vreq));
384 vreq.vifi = vif_index;
385 ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq);
389 struct sioc_mif_req6 mreq;
390 memset(&mreq, 0, sizeof(mreq));
391 mreq.mifi = vif_index;
392 ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq);
394 .Ss Advanced Multicast API Programming Guide
395 If we want to add new features in the kernel, it becomes difficult
396 to preserve backward compatibility (binary and API),
397 and at the same time to allow user-level processes to take advantage of
398 the new features (if the kernel supports them).
400 One of the mechanisms that allows us to preserve the backward
401 compatibility is a sort of negotiation
402 between the user-level process and the kernel:
405 The user-level process tries to enable in the kernel the set of new
406 features (and the corresponding API) it would like to use.
408 The kernel returns the (sub)set of features it knows about
409 and is willing to be enabled.
411 The user-level process uses only that set of features
412 the kernel has agreed on.
416 To support backward compatibility, if the user-level process does not
417 ask for any new features, the kernel defaults to the basic
418 multicast API (see the
419 .Sx "Programming Guide"
421 .\" XXX: edit as appropriate after the advanced multicast API is
422 .\" supported under IPv6
423 Currently, the advanced multicast API exists only for IPv4;
424 in the future there will be IPv6 support as well.
426 Below is a summary of the expandable API solution.
427 Note that all new options and structures are defined
429 .In netinet/ip_mroute.h
431 .In netinet6/ip6_mroute.h ,
432 unless stated otherwise.
434 The user-level process uses new
435 .Fn getsockopt Ns / Ns Fn setsockopt
437 perform the API features negotiation with the kernel.
438 This negotiation must be performed right after the multicast routing
440 The set of desired/allowed features is stored in a bitset
443 i.e., maximum of 32 new features).
445 .Fn getsockopt Ns / Ns Fn setsockopt
453 getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v));
458 the pre-defined bits that the kernel API supports.
459 The eight least significant bits in
466 as part of the new definition of
468 (see below about those flags), which leaves 24 flags for other new features.
469 The value returned by
470 .Fn getsockopt MRT_API_SUPPORT
471 is read-only; in other words,
472 .Fn setsockopt MRT_API_SUPPORT
475 To modify the API, and to set some specific feature in the kernel, then:
477 uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF;
478 if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v))
482 if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF)
483 return (OK); /* Success */
489 .Fn setsockopt MRT_API_CONFIG
491 argument to it specifies the desired set of features to
492 be enabled in the API and the kernel.
495 is the actual (sub)set of features that were enabled in the kernel.
496 To obtain later the same set of features that were enabled, then:
498 getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v));
501 The set of enabled features is global.
503 .Fn setsockopt MRT_API_CONFIG
504 should be called right after
505 .Fn setsockopt MRT_INIT .
507 Currently, the following set of new features is defined:
509 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
510 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
511 #define MRT_MFC_RP (1 << 8) /* enable RP address */
512 #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */
515 .\" In the future there might be:
517 .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */
520 .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel.
521 .\" For now this is left-out until it is clear whether
522 .\" (*,G) MFC support is the preferred solution instead of something more generic
523 .\" solution for example.
525 .\" 2. The newly defined struct mfcctl2.
528 The advanced multicast API uses a newly defined
530 instead of the traditional
531 .Vt "struct mfcctl" .
540 * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays
541 * and extends the old struct mfcctl.
544 /* the mfcctl fields */
545 struct in_addr mfcc_origin; /* ip origin of mcasts */
546 struct in_addr mfcc_mcastgrp; /* multicast group associated*/
547 vifi_t mfcc_parent; /* incoming vif */
548 u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */
550 /* extension fields */
551 uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/
552 struct in_addr mfcc_rp; /* the RP address */
557 .Va mfcc_flags[MAXVIFS]
560 Note that for compatibility reasons they are added at the end.
563 .Va mfcc_flags[MAXVIFS]
564 field is used to set various flags per
565 interface per (S,G) entry.
566 Currently, the defined flags are:
568 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
569 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
573 .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF
574 flag is used to explicitly disable the
576 kernel signal at the (S,G) granularity if a multicast data packet
577 arrives on the wrong interface.
578 Usually, this signal is used to
579 complete the shortest-path switch in case of PIM-SM multicast routing,
580 or to trigger a PIM assert message.
581 However, it should not be delivered for interfaces that are not in
582 the outgoing interface set, and that are not expecting to
583 become an incoming interface.
585 .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF
586 flag is set for some of the
587 interfaces, then a data packet that arrives on that interface for
588 that MFC entry will NOT trigger a WRONGVIF signal.
589 If that flag is not set, then a signal is triggered (the default action).
592 .Dv MRT_MFC_FLAGS_BORDER_VIF
593 flag is used to specify whether the Border-bit in PIM
594 Register messages should be set (in case when the Register encapsulation
595 is performed inside the kernel).
596 If it is set for the special PIM Register kernel virtual interface
599 the Border-bit in the Register messages sent to the RP will be set.
601 The remaining six bits are reserved for future usage.
605 field is used to specify the RP address (in case of PIM-SM multicast routing)
607 group G if we want to perform kernel-level PIM Register encapsulation.
610 field is used only if the
612 advanced API flag/capability has been successfully set by
613 .Fn setsockopt MRT_API_CONFIG .
616 .\" 3. Kernel-level PIM Register encapsulation
620 flag was successfully set by
621 .Fn setsockopt MRT_API_CONFIG ,
622 then the kernel will attempt to perform
623 the PIM Register encapsulation itself instead of sending the
624 multicast data packets to user level (inside
626 upcalls) for user-level encapsulation.
627 The RP address would be taken from the
631 .Vt "struct mfcctl2" .
634 flag was successfully set, if the
639 kernel will still deliver an
642 multicast data packet to the user-level process.
644 In addition, if the multicast data packet is too large to fit within
645 a single IP packet after the PIM Register encapsulation (e.g., if
646 its size was on the order of 65500 bytes), the data packet will be
647 fragmented, and then each of the fragments will be encapsulated
649 Note that typically a multicast data packet can be that
650 large only if it was originated locally from the same hosts that
651 performs the encapsulation; otherwise the transmission of the
652 multicast data packet over Ethernet for example would have
653 fragmented it into much smaller pieces.
655 .\" Note that if this code is ported to IPv6, we may need the kernel to
656 .\" perform MTU discovery to the RP, and keep those discoveries inside
657 .\" the kernel so the encapsulating router may send back ICMP
658 .\" Fragmentation Required if the size of the multicast data packet is
659 .\" too large (see "Encapsulating data packets in the Register Tunnel"
660 .\" in Section 4.4.1 in the PIM-SM spec
661 .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}).
662 .\" For IPv4 we may be able to get away without it, but for IPv6 we need
665 .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls".
668 Typically, a multicast routing user-level process would need to know the
669 forwarding bandwidth for some data flow.
670 For example, the multicast routing process may want to timeout idle MFC
671 entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if
672 the bandwidth rate is above a threshold for example.
674 The original solution for measuring the bandwidth of a dataflow was
675 that a user-level process would periodically
676 query the kernel about the number of forwarded packets/bytes per
677 (S,G), and then based on those numbers it would estimate whether a source
678 has been idle, or whether the source's transmission bandwidth is above a
680 That solution is far from being scalable, hence the need for a new
681 mechanism for bandwidth monitoring.
683 Below is a description of the bandwidth monitoring mechanism.
686 If the bandwidth of a data flow satisfies some pre-defined filter,
687 the kernel delivers an upcall on the multicast routing socket
688 to the multicast routing process that has installed that filter.
690 The bandwidth-upcall filters are installed per (S,G).
692 more than one filter per (S,G).
694 Instead of supporting all possible comparison operations
695 (i.e., < <= == != > >= ), there is support only for the
696 <= and >= operations,
697 because this makes the kernel-level implementation simpler,
698 and because practically we need only those two.
699 Further, the missing operations can be simulated by secondary
700 user-level filtering of those <= and >= filters.
701 For example, to simulate !=, then we need to install filter
702 .Dq bw <= 0xffffffff ,
704 upcall is received, we need to check whether
705 .Dq measured_bw != expected_bw .
707 The bandwidth-upcall mechanism is enabled by
708 .Fn setsockopt MRT_API_CONFIG
710 .Dv MRT_MFC_BW_UPCALL
713 The bandwidth-upcall filters are added/deleted by the new
714 .Fn setsockopt MRT_ADD_BW_UPCALL
716 .Fn setsockopt MRT_DEL_BW_UPCALL
717 respectively (with the appropriate
718 .Vt "struct bw_upcall"
722 From application point of view, a developer needs to know about
726 * Structure for installing or delivering an upcall if the
727 * measured bandwidth is above or below a threshold.
729 * User programs (e.g. daemons) may have a need to know when the
730 * bandwidth used by some data flow is above or below some threshold.
731 * This interface allows the userland to specify the threshold (in
732 * bytes and/or packets) and the measurement interval. Flows are
733 * all packet with the same source and destination IP address.
734 * At the moment the code is only used for multicast destinations
735 * but there is nothing that prevents its use for unicast.
737 * The measurement interval cannot be shorter than some Tmin (currently, 3s).
738 * The threshold is set in packets and/or bytes per_interval.
740 * Measurement works as follows:
742 * For >= measurements:
743 * The first packet marks the start of a measurement interval.
744 * During an interval we count packets and bytes, and when we
745 * pass the threshold we deliver an upcall and we are done.
746 * The first packet after the end of the interval resets the
747 * count and restarts the measurement.
749 * For <= measurement:
750 * We start a timer to fire at the end of the interval, and
751 * then for each incoming packet we count packets and bytes.
752 * When the timer fires, we compare the value with the threshold,
753 * schedule an upcall if we are below, and restart the measurement
754 * (reschedule timer and zero counters).
758 struct timeval b_time;
764 struct in_addr bu_src; /* source address */
765 struct in_addr bu_dst; /* destination address */
766 uint32_t bu_flags; /* misc flags (see below) */
767 #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */
768 #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */
769 #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */
770 #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */
771 #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/
772 struct bw_data bu_threshold; /* the bw threshold */
773 struct bw_data bu_measured; /* the measured bw */
776 /* max. number of upcalls to deliver together */
777 #define BW_UPCALLS_MAX 128
778 /* min. threshold time interval for bandwidth measurement */
779 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3
780 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0
785 structure is used as an argument to
786 .Fn setsockopt MRT_ADD_BW_UPCALL
788 .Fn setsockopt MRT_DEL_BW_UPCALL .
790 .Fn setsockopt MRT_ADD_BW_UPCALL
791 installs a filter in the kernel
792 for the source and destination address in the
795 and that filter will trigger an upcall according to the following
798 if (bw_upcall_oper IS ">=") {
799 if (((bw_upcall_unit & PACKETS == PACKETS) &&
800 (measured_packets >= threshold_packets)) ||
801 ((bw_upcall_unit & BYTES == BYTES) &&
802 (measured_bytes >= threshold_bytes)))
803 SEND_UPCALL("measured bandwidth is >= threshold");
805 if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) {
806 if (((bw_upcall_unit & PACKETS == PACKETS) &&
807 (measured_packets <= threshold_packets)) ||
808 ((bw_upcall_unit & BYTES == BYTES) &&
809 (measured_bytes <= threshold_bytes)))
810 SEND_UPCALL("measured bandwidth is <= threshold");
816 the unit can be specified in both BYTES and PACKETS.
817 However, the GEQ and LEQ flags are mutually exclusive.
819 Basically, an upcall is delivered if the measured bandwidth is >= or
820 <= the threshold bandwidth (within the specified measurement
822 For practical reasons, the smallest value for the measurement
823 interval is 3 seconds.
824 If smaller values are allowed, then the bandwidth
825 estimation may be less accurate, or the potentially very high frequency
826 of the generated upcalls may introduce too much overhead.
827 For the >= operation, the answer may be known before the end of
828 .Va threshold_interval ,
829 therefore the upcall may be delivered earlier.
830 For the <= operation however, we must wait
831 until the threshold interval has expired to know the answer.
835 struct bw_upcall bw_upcall;
836 /* Assign all bw_upcall fields as appropriate */
837 memset(&bw_upcall, 0, sizeof(bw_upcall));
838 memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src));
839 memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst));
840 bw_upcall.bu_threshold.b_data = threshold_interval;
841 bw_upcall.bu_threshold.b_packets = threshold_packets;
842 bw_upcall.bu_threshold.b_bytes = threshold_bytes;
843 if (is_threshold_in_packets)
844 bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS;
845 if (is_threshold_in_bytes)
846 bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES;
849 bw_upcall.bu_flags |= BW_UPCALL_GEQ;
853 bw_upcall.bu_flags |= BW_UPCALL_LEQ;
858 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL,
859 (void *)&bw_upcall, sizeof(bw_upcall));
862 To delete a single filter, then use
863 .Dv MRT_DEL_BW_UPCALL ,
864 and the fields of bw_upcall must be set
866 .Dv MRT_ADD_BW_UPCALL
869 To delete all bandwidth filters for a given (S,G), then
875 .Vt "struct bw_upcall"
876 need to be set, and then just set only the
877 .Dv BW_UPCALL_DELETE_ALL
879 .Va bw_upcall.bu_flags .
881 The bandwidth upcalls are received by aggregating them in the new upcall
884 #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */
887 This message is an array of
888 .Vt "struct bw_upcall"
893 delivered when there are 128 pending upcalls, or when 1 second has
894 expired since the previous upcall (whichever comes first).
899 field is filled-in to
900 indicate the particular measured values.
901 However, because of the way
902 the particular intervals are measured, the user should be careful how
903 .Va bu_measured.b_time
906 filter is installed to trigger an upcall if the number of packets
909 may have a value of zero in the upcalls after the
910 first one, because the measured interval for >= filters is
912 by the forwarded packets.
913 Hence, this upcall mechanism should not be used for measuring
914 the exact value of the bandwidth of the forwarded data.
915 To measure the exact bandwidth, the user would need to
916 get the forwarded packets statistics with the
917 .Fn ioctl SIOCGETSGCNT
920 .Sx Programming Guide
923 Note that the upcalls for a filter are delivered until the specific
924 filter is deleted, but no more frequently than once per
925 .Va bu_threshold.b_time .
926 For example, if the filter is specified to
927 deliver a signal if bw >= 1 packet, the first packet will trigger a
928 signal, but the next upcall will be triggered no earlier than
929 .Va bu_threshold.b_time
930 after the previous upcall.
948 The original multicast code was written by
951 and later modified by the following individuals:
954 .An Mark J. Steiglitz
962 The IPv6 multicast support was implemented by the KAME project
963 .Pq Pa http://www.kame.net ,
964 and was based on the IPv4 multicast code.
965 The advanced multicast API and the multicast bandwidth
966 monitoring were implemented by
967 .An Pavlin Radoslavov
969 in collaboration with
973 This manual page was written by
974 .An Pavlin Radoslavov
projects / FreeBSD / FreeBSD.git / blob