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 = 0;
164 memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr));
165 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc,
171 must be unique per vif.
177 .In netinet/ip_mroute.h .
180 flag is no longer supported by
182 Users who wish to forward multicast datagrams over a tunnel should consider
187 tunnel and using it as a physical interface.
190 .Va min_ttl_threshold
191 contains the minimum TTL a multicast data packet must have to be
192 forwarded on that vif.
193 Typically, it would have value of 1.
197 argument is no longer supported in
199 and should be set to 0.
200 Users who wish to rate-limit multicast datagrams should consider the use of
206 .Va vif_local_address
207 contains the local IP address of the corresponding local interface.
209 .Va vif_remote_address
210 contains the remote IP address in case of DVMRP multicast tunnels.
214 memset(&mc, 0, sizeof(mc));
215 /* Assign all mif6ctl fields as appropriate */
216 mc.mif6c_mifi = mif_index;
217 mc.mif6c_flags = mif_flags;
218 mc.mif6c_pifi = pif_index;
219 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc,
225 must be unique per vif.
231 .In netinet6/ip6_mroute.h .
234 is the physical interface index of the corresponding local interface.
236 A multicast interface is deleted by:
239 vifi_t vifi = vif_index;
240 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi,
245 mifi_t mifi = mif_index;
246 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi,
250 After the multicast forwarding is enabled, and the multicast virtual
252 added, the kernel may deliver upcall messages (also called signals
253 later in this text) on the multicast routing socket that was open
258 The IPv4 upcalls have
261 .In netinet/ip_mroute.h )
265 Note that this header follows the structure of
267 with the protocol field
270 The IPv6 upcalls have
273 .In netinet6/ip6_mroute.h )
277 Note that this header follows the structure of
279 with the next header field
283 The upcall header contains field
287 with the type of the upcall
291 for IPv4 and IPv6 respectively.
292 The values of the rest of the upcall header fields
293 and the body of the upcall message depend on the particular upcall type.
295 If the upcall message type is
298 .Dv MRT6MSG_NOCACHE ,
299 this is an indication that a multicast packet has reached the multicast
300 router, but the router has no forwarding state for that packet.
301 Typically, the upcall would be a signal for the multicast routing
302 user-level process to install the appropriate Multicast Forwarding
303 Cache (MFC) entry in the kernel.
305 An MFC entry is added by:
309 memset(&mc, 0, sizeof(mc));
310 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
311 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
312 mc.mfcc_parent = iif_index;
313 for (i = 0; i < maxvifs; i++)
314 mc.mfcc_ttls[i] = oifs_ttl[i];
315 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC,
316 (void *)&mc, sizeof(mc));
321 memset(&mc, 0, sizeof(mc));
322 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
323 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
324 mc.mf6cc_parent = iif_index;
325 for (i = 0; i < maxvifs; i++)
327 IF_SET(i, &mc.mf6cc_ifset);
328 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC,
329 (void *)&mc, sizeof(mc));
336 are the source and group address of the multicast packet (as set
337 in the upcall message).
340 is the virtual interface index of the multicast interface the multicast
341 packets for this specific source and group address should be received on.
344 array contains the minimum TTL (per interface) a multicast packet
345 should have to be forwarded on an outgoing interface.
346 If the TTL value is zero, the corresponding interface is not included
347 in the set of outgoing interfaces.
348 Note that in case of IPv6 only the set of outgoing interfaces can
351 An MFC entry is deleted by:
355 memset(&mc, 0, sizeof(mc));
356 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
357 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
358 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC,
359 (void *)&mc, sizeof(mc));
364 memset(&mc, 0, sizeof(mc));
365 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
366 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
367 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC,
368 (void *)&mc, sizeof(mc));
371 The following method can be used to get various statistics per
372 installed MFC entry in the kernel (e.g., the number of forwarded
373 packets per source and group address):
376 struct sioc_sg_req sgreq;
377 memset(&sgreq, 0, sizeof(sgreq));
378 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
379 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
380 ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq);
384 struct sioc_sg_req6 sgreq;
385 memset(&sgreq, 0, sizeof(sgreq));
386 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
387 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
388 ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq);
391 The following method can be used to get various statistics per
392 multicast virtual interface in the kernel (e.g., the number of forwarded
393 packets per interface):
396 struct sioc_vif_req vreq;
397 memset(&vreq, 0, sizeof(vreq));
398 vreq.vifi = vif_index;
399 ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq);
403 struct sioc_mif_req6 mreq;
404 memset(&mreq, 0, sizeof(mreq));
405 mreq.mifi = vif_index;
406 ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq);
408 .Ss Advanced Multicast API Programming Guide
409 If we want to add new features in the kernel, it becomes difficult
410 to preserve backward compatibility (binary and API),
411 and at the same time to allow user-level processes to take advantage of
412 the new features (if the kernel supports them).
414 One of the mechanisms that allows us to preserve the backward
415 compatibility is a sort of negotiation
416 between the user-level process and the kernel:
419 The user-level process tries to enable in the kernel the set of new
420 features (and the corresponding API) it would like to use.
422 The kernel returns the (sub)set of features it knows about
423 and is willing to be enabled.
425 The user-level process uses only that set of features
426 the kernel has agreed on.
430 To support backward compatibility, if the user-level process does not
431 ask for any new features, the kernel defaults to the basic
432 multicast API (see the
433 .Sx "Programming Guide"
435 .\" XXX: edit as appropriate after the advanced multicast API is
436 .\" supported under IPv6
437 Currently, the advanced multicast API exists only for IPv4;
438 in the future there will be IPv6 support as well.
440 Below is a summary of the expandable API solution.
441 Note that all new options and structures are defined
443 .In netinet/ip_mroute.h
445 .In netinet6/ip6_mroute.h ,
446 unless stated otherwise.
448 The user-level process uses new
449 .Fn getsockopt Ns / Ns Fn setsockopt
451 perform the API features negotiation with the kernel.
452 This negotiation must be performed right after the multicast routing
454 The set of desired/allowed features is stored in a bitset
457 i.e., maximum of 32 new features).
459 .Fn getsockopt Ns / Ns Fn setsockopt
467 getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v));
472 the pre-defined bits that the kernel API supports.
473 The eight least significant bits in
480 as part of the new definition of
482 (see below about those flags), which leaves 24 flags for other new features.
483 The value returned by
484 .Fn getsockopt MRT_API_SUPPORT
485 is read-only; in other words,
486 .Fn setsockopt MRT_API_SUPPORT
489 To modify the API, and to set some specific feature in the kernel, then:
491 uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF;
492 if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v))
496 if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF)
497 return (OK); /* Success */
503 .Fn setsockopt MRT_API_CONFIG
505 argument to it specifies the desired set of features to
506 be enabled in the API and the kernel.
509 is the actual (sub)set of features that were enabled in the kernel.
510 To obtain later the same set of features that were enabled, then:
512 getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v));
515 The set of enabled features is global.
517 .Fn setsockopt MRT_API_CONFIG
518 should be called right after
519 .Fn setsockopt MRT_INIT .
521 Currently, the following set of new features is defined:
523 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
524 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
525 #define MRT_MFC_RP (1 << 8) /* enable RP address */
526 #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */
529 .\" In the future there might be:
531 .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */
534 .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel.
535 .\" For now this is left-out until it is clear whether
536 .\" (*,G) MFC support is the preferred solution instead of something more generic
537 .\" solution for example.
539 .\" 2. The newly defined struct mfcctl2.
542 The advanced multicast API uses a newly defined
544 instead of the traditional
545 .Vt "struct mfcctl" .
554 * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays
555 * and extends the old struct mfcctl.
558 /* the mfcctl fields */
559 struct in_addr mfcc_origin; /* ip origin of mcasts */
560 struct in_addr mfcc_mcastgrp; /* multicast group associated*/
561 vifi_t mfcc_parent; /* incoming vif */
562 u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */
564 /* extension fields */
565 uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/
566 struct in_addr mfcc_rp; /* the RP address */
571 .Va mfcc_flags[MAXVIFS]
574 Note that for compatibility reasons they are added at the end.
577 .Va mfcc_flags[MAXVIFS]
578 field is used to set various flags per
579 interface per (S,G) entry.
580 Currently, the defined flags are:
582 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
583 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
587 .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF
588 flag is used to explicitly disable the
590 kernel signal at the (S,G) granularity if a multicast data packet
591 arrives on the wrong interface.
592 Usually, this signal is used to
593 complete the shortest-path switch in case of PIM-SM multicast routing,
594 or to trigger a PIM assert message.
595 However, it should not be delivered for interfaces that are not in
596 the outgoing interface set, and that are not expecting to
597 become an incoming interface.
599 .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF
600 flag is set for some of the
601 interfaces, then a data packet that arrives on that interface for
602 that MFC entry will NOT trigger a WRONGVIF signal.
603 If that flag is not set, then a signal is triggered (the default action).
606 .Dv MRT_MFC_FLAGS_BORDER_VIF
607 flag is used to specify whether the Border-bit in PIM
608 Register messages should be set (in case when the Register encapsulation
609 is performed inside the kernel).
610 If it is set for the special PIM Register kernel virtual interface
613 the Border-bit in the Register messages sent to the RP will be set.
615 The remaining six bits are reserved for future usage.
619 field is used to specify the RP address (in case of PIM-SM multicast routing)
621 group G if we want to perform kernel-level PIM Register encapsulation.
624 field is used only if the
626 advanced API flag/capability has been successfully set by
627 .Fn setsockopt MRT_API_CONFIG .
630 .\" 3. Kernel-level PIM Register encapsulation
634 flag was successfully set by
635 .Fn setsockopt MRT_API_CONFIG ,
636 then the kernel will attempt to perform
637 the PIM Register encapsulation itself instead of sending the
638 multicast data packets to user level (inside
640 upcalls) for user-level encapsulation.
641 The RP address would be taken from the
645 .Vt "struct mfcctl2" .
648 flag was successfully set, if the
653 kernel will still deliver an
656 multicast data packet to the user-level process.
658 In addition, if the multicast data packet is too large to fit within
659 a single IP packet after the PIM Register encapsulation (e.g., if
660 its size was on the order of 65500 bytes), the data packet will be
661 fragmented, and then each of the fragments will be encapsulated
663 Note that typically a multicast data packet can be that
664 large only if it was originated locally from the same hosts that
665 performs the encapsulation; otherwise the transmission of the
666 multicast data packet over Ethernet for example would have
667 fragmented it into much smaller pieces.
669 .\" Note that if this code is ported to IPv6, we may need the kernel to
670 .\" perform MTU discovery to the RP, and keep those discoveries inside
671 .\" the kernel so the encapsulating router may send back ICMP
672 .\" Fragmentation Required if the size of the multicast data packet is
673 .\" too large (see "Encapsulating data packets in the Register Tunnel"
674 .\" in Section 4.4.1 in the PIM-SM spec
675 .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}).
676 .\" For IPv4 we may be able to get away without it, but for IPv6 we need
679 .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls".
682 Typically, a multicast routing user-level process would need to know the
683 forwarding bandwidth for some data flow.
684 For example, the multicast routing process may want to timeout idle MFC
685 entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if
686 the bandwidth rate is above a threshold for example.
688 The original solution for measuring the bandwidth of a dataflow was
689 that a user-level process would periodically
690 query the kernel about the number of forwarded packets/bytes per
691 (S,G), and then based on those numbers it would estimate whether a source
692 has been idle, or whether the source's transmission bandwidth is above a
694 That solution is far from being scalable, hence the need for a new
695 mechanism for bandwidth monitoring.
697 Below is a description of the bandwidth monitoring mechanism.
700 If the bandwidth of a data flow satisfies some pre-defined filter,
701 the kernel delivers an upcall on the multicast routing socket
702 to the multicast routing process that has installed that filter.
704 The bandwidth-upcall filters are installed per (S,G).
706 more than one filter per (S,G).
708 Instead of supporting all possible comparison operations
709 (i.e., < <= == != > >= ), there is support only for the
710 <= and >= operations,
711 because this makes the kernel-level implementation simpler,
712 and because practically we need only those two.
713 Further, the missing operations can be simulated by secondary
714 user-level filtering of those <= and >= filters.
715 For example, to simulate !=, then we need to install filter
716 .Dq bw <= 0xffffffff ,
718 upcall is received, we need to check whether
719 .Dq measured_bw != expected_bw .
721 The bandwidth-upcall mechanism is enabled by
722 .Fn setsockopt MRT_API_CONFIG
724 .Dv MRT_MFC_BW_UPCALL
727 The bandwidth-upcall filters are added/deleted by the new
728 .Fn setsockopt MRT_ADD_BW_UPCALL
730 .Fn setsockopt MRT_DEL_BW_UPCALL
731 respectively (with the appropriate
732 .Vt "struct bw_upcall"
736 From application point of view, a developer needs to know about
740 * Structure for installing or delivering an upcall if the
741 * measured bandwidth is above or below a threshold.
743 * User programs (e.g. daemons) may have a need to know when the
744 * bandwidth used by some data flow is above or below some threshold.
745 * This interface allows the userland to specify the threshold (in
746 * bytes and/or packets) and the measurement interval. Flows are
747 * all packet with the same source and destination IP address.
748 * At the moment the code is only used for multicast destinations
749 * but there is nothing that prevents its use for unicast.
751 * The measurement interval cannot be shorter than some Tmin (currently, 3s).
752 * The threshold is set in packets and/or bytes per_interval.
754 * Measurement works as follows:
756 * For >= measurements:
757 * The first packet marks the start of a measurement interval.
758 * During an interval we count packets and bytes, and when we
759 * pass the threshold we deliver an upcall and we are done.
760 * The first packet after the end of the interval resets the
761 * count and restarts the measurement.
763 * For <= measurement:
764 * We start a timer to fire at the end of the interval, and
765 * then for each incoming packet we count packets and bytes.
766 * When the timer fires, we compare the value with the threshold,
767 * schedule an upcall if we are below, and restart the measurement
768 * (reschedule timer and zero counters).
772 struct timeval b_time;
778 struct in_addr bu_src; /* source address */
779 struct in_addr bu_dst; /* destination address */
780 uint32_t bu_flags; /* misc flags (see below) */
781 #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */
782 #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */
783 #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */
784 #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */
785 #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/
786 struct bw_data bu_threshold; /* the bw threshold */
787 struct bw_data bu_measured; /* the measured bw */
790 /* max. number of upcalls to deliver together */
791 #define BW_UPCALLS_MAX 128
792 /* min. threshold time interval for bandwidth measurement */
793 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3
794 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0
799 structure is used as an argument to
800 .Fn setsockopt MRT_ADD_BW_UPCALL
802 .Fn setsockopt MRT_DEL_BW_UPCALL .
804 .Fn setsockopt MRT_ADD_BW_UPCALL
805 installs a filter in the kernel
806 for the source and destination address in the
809 and that filter will trigger an upcall according to the following
812 if (bw_upcall_oper IS ">=") {
813 if (((bw_upcall_unit & PACKETS == PACKETS) &&
814 (measured_packets >= threshold_packets)) ||
815 ((bw_upcall_unit & BYTES == BYTES) &&
816 (measured_bytes >= threshold_bytes)))
817 SEND_UPCALL("measured bandwidth is >= threshold");
819 if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) {
820 if (((bw_upcall_unit & PACKETS == PACKETS) &&
821 (measured_packets <= threshold_packets)) ||
822 ((bw_upcall_unit & BYTES == BYTES) &&
823 (measured_bytes <= threshold_bytes)))
824 SEND_UPCALL("measured bandwidth is <= threshold");
830 the unit can be specified in both BYTES and PACKETS.
831 However, the GEQ and LEQ flags are mutually exclusive.
833 Basically, an upcall is delivered if the measured bandwidth is >= or
834 <= the threshold bandwidth (within the specified measurement
836 For practical reasons, the smallest value for the measurement
837 interval is 3 seconds.
838 If smaller values are allowed, then the bandwidth
839 estimation may be less accurate, or the potentially very high frequency
840 of the generated upcalls may introduce too much overhead.
841 For the >= operation, the answer may be known before the end of
842 .Va threshold_interval ,
843 therefore the upcall may be delivered earlier.
844 For the <= operation however, we must wait
845 until the threshold interval has expired to know the answer.
849 struct bw_upcall bw_upcall;
850 /* Assign all bw_upcall fields as appropriate */
851 memset(&bw_upcall, 0, sizeof(bw_upcall));
852 memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src));
853 memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst));
854 bw_upcall.bu_threshold.b_data = threshold_interval;
855 bw_upcall.bu_threshold.b_packets = threshold_packets;
856 bw_upcall.bu_threshold.b_bytes = threshold_bytes;
857 if (is_threshold_in_packets)
858 bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS;
859 if (is_threshold_in_bytes)
860 bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES;
863 bw_upcall.bu_flags |= BW_UPCALL_GEQ;
867 bw_upcall.bu_flags |= BW_UPCALL_LEQ;
872 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL,
873 (void *)&bw_upcall, sizeof(bw_upcall));
876 To delete a single filter, then use
877 .Dv MRT_DEL_BW_UPCALL ,
878 and the fields of bw_upcall must be set
880 .Dv MRT_ADD_BW_UPCALL
883 To delete all bandwidth filters for a given (S,G), then
889 .Vt "struct bw_upcall"
890 need to be set, and then just set only the
891 .Dv BW_UPCALL_DELETE_ALL
893 .Va bw_upcall.bu_flags .
895 The bandwidth upcalls are received by aggregating them in the new upcall
898 #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */
901 This message is an array of
902 .Vt "struct bw_upcall"
907 delivered when there are 128 pending upcalls, or when 1 second has
908 expired since the previous upcall (whichever comes first).
913 field is filled-in to
914 indicate the particular measured values.
915 However, because of the way
916 the particular intervals are measured, the user should be careful how
917 .Va bu_measured.b_time
920 filter is installed to trigger an upcall if the number of packets
923 may have a value of zero in the upcalls after the
924 first one, because the measured interval for >= filters is
926 by the forwarded packets.
927 Hence, this upcall mechanism should not be used for measuring
928 the exact value of the bandwidth of the forwarded data.
929 To measure the exact bandwidth, the user would need to
930 get the forwarded packets statistics with the
931 .Fn ioctl SIOCGETSGCNT
934 .Sx Programming Guide
937 Note that the upcalls for a filter are delivered until the specific
938 filter is deleted, but no more frequently than once per
939 .Va bu_threshold.b_time .
940 For example, if the filter is specified to
941 deliver a signal if bw >= 1 packet, the first packet will trigger a
942 signal, but the next upcall will be triggered no earlier than
943 .Va bu_threshold.b_time
944 after the previous upcall.
966 The original multicast code was written by
969 and later modified by the following individuals:
972 .An Mark J. Steiglitz
980 The IPv6 multicast support was implemented by the KAME project
981 .Pq Pa http://www.kame.net ,
982 and was based on the IPv4 multicast code.
983 The advanced multicast API and the multicast bandwidth
984 monitoring were implemented by
985 .An Pavlin Radoslavov
987 in collaboration with
991 This manual page was written by
992 .An Pavlin Radoslavov
projects / FreeBSD / FreeBSD.git / blob