| blob | 3c53db351117828a26608aa05680a8ef7c5ee0dc |
1 .\" Copyright (c) 2001-2003 International Computer Science Institute
2 .\"
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:
9 .\"
10 .\" The above copyright notice and this permission notice shall be included in
11 .\" all copies or substantial portions of the Software.
12 .\"
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.
17 .\"
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.
25 .\"
26 .\" $FreeBSD$
27 .\"
28 .Dd March 18, 2007
29 .Dt MULTICAST 4
30 .Os
31 .\"
32 .Sh NAME
33 .Nm multicast
34 .Nd Multicast Routing
35 .\"
36 .Sh SYNOPSIS
37 .Cd "options MROUTING"
38 .Pp
39 .In sys/types.h
40 .In sys/socket.h
41 .In netinet/in.h
42 .In netinet/ip_mroute.h
43 .In netinet6/ip6_mroute.h
44 .Ft int
45 .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen"
46 .Ft int
47 .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen"
48 .Ft int
49 .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen"
50 .Ft int
51 .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen"
52 .Sh DESCRIPTION
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
58 data packets.
59 With multicast routing, the overhead is reduced to one copy
60 (at most) per network link.
61 .Pp
62 All multicast-capable routers must run a common multicast routing
63 protocol.
64 It is recommended that either
65 Protocol Independent Multicast - Sparse Mode (PIM-SM),
66 or Protocol Independent Multicast - Dense Mode (PIM-DM)
67 are used, as these are now the generally accepted protocols
68 in the Internet community.
69 The
70 .Sx HISTORY
71 section discusses previous multicast routing protocols.
72 .Pp
73 To start multicast routing,
74 the user must enable multicast forwarding in the kernel
75 (see
76 .Sx SYNOPSIS
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.
83 .\"
84 .Ss Programming Guide
85 This section provides information about the basic multicast routing API.
86 The so-called
87 .Dq advanced multicast API
88 is described in the
89 .Sx "Advanced Multicast API Programming Guide"
90 section.
91 .Pp
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):
97 .Bd -literal
98 /* IPv4 */
99 int mrouter_s4;
100 mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP);
101 .Ed
102 .Bd -literal
103 int mrouter_s6;
104 mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6);
105 .Ed
106 .Pp
107 Note that if the router needs to open an IGMP or ICMPv6 socket
108 (in case of IPv4 and IPv6 respectively)
109 for sending or receiving of IGMP or MLD multicast group membership messages,
110 then the same
111 .Va mrouter_s4
112 or
113 .Va mrouter_s6
114 sockets should be used
115 for sending and receiving respectively IGMP or MLD messages.
116 In case of
117 .Bx Ns
118 -derived kernel, it may be possible to open separate sockets
119 for IGMP or MLD messages only.
120 However, some other kernels (e.g.,
121 .Tn Linux )
122 require that the multicast
123 routing socket must be used for sending and receiving of IGMP or MLD
124 messages.
125 Therefore, for portability reason the multicast
126 routing socket should be reused for IGMP and MLD messages as well.
127 .Pp
128 After the multicast routing socket is open, it can be used to enable
129 or disable multicast forwarding in the kernel:
130 .Bd -literal
131 /* IPv4 */
132 int v = 1; /* 1 to enable, or 0 to disable */
133 setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v));
134 .Ed
135 .Bd -literal
136 /* IPv6 */
137 int v = 1; /* 1 to enable, or 0 to disable */
138 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v));
139 \&...
140 /* If necessary, filter all ICMPv6 messages */
141 struct icmp6_filter filter;
142 ICMP6_FILTER_SETBLOCKALL(&filter);
143 setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter,
144 sizeof(filter));
145 .Ed
146 .Pp
147 After multicast forwarding is enabled, the multicast routing socket
148 can be used to enable PIM processing in the kernel if we are running PIM-SM or
149 PIM-DM
150 (see
151 .Xr pim 4 ) .
152 .Pp
153 For each network interface (e.g., physical or a virtual tunnel)
154 that would be used for multicast forwarding, a corresponding
155 multicast interface must be added to the kernel:
156 .Bd -literal
157 /* IPv4 */
158 struct vifctl vc;
159 memset(&vc, 0, sizeof(vc));
160 /* Assign all vifctl fields as appropriate */
161 vc.vifc_vifi = vif_index;
162 vc.vifc_flags = vif_flags;
163 vc.vifc_threshold = min_ttl_threshold;
164 vc.vifc_rate_limit = 0;
165 memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr));
166 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc,
167 sizeof(vc));
168 .Ed
169 .Pp
170 The
171 .Va vif_index
172 must be unique per vif.
173 The
174 .Va vif_flags
175 contains the
176 .Dv VIFF_*
177 flags as defined in
178 .In netinet/ip_mroute.h .
179 The
180 .Dv VIFF_TUNNEL
181 flag is no longer supported by
182 .Fx .
183 Users who wish to forward multicast datagrams over a tunnel should consider
184 configuring a
185 .Xr gif 4
186 or
187 .Xr gre 4
188 tunnel and using it as a physical interface.
189 .Pp
190 The
191 .Va min_ttl_threshold
192 contains the minimum TTL a multicast data packet must have to be
193 forwarded on that vif.
194 Typically, it would have value of 1.
195 .Pp
196 The
197 .Va max_rate_limit
198 argument is no longer supported in
199 .Fx
200 and should be set to 0.
201 Users who wish to rate-limit multicast datagrams should consider the use of
202 .Xr dummynet 4
203 or
204 .Xr altq 4 .
205 .Pp
206 The
207 .Va vif_local_address
208 contains the local IP address of the corresponding local interface.
209 The
210 .Va vif_remote_address
211 contains the remote IP address in case of DVMRP multicast tunnels.
212 .Bd -literal
213 /* IPv6 */
214 struct mif6ctl mc;
215 memset(&mc, 0, sizeof(mc));
216 /* Assign all mif6ctl fields as appropriate */
217 mc.mif6c_mifi = mif_index;
218 mc.mif6c_flags = mif_flags;
219 mc.mif6c_pifi = pif_index;
220 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc,
221 sizeof(mc));
222 .Ed
223 .Pp
224 The
225 .Va mif_index
226 must be unique per vif.
227 The
228 .Va mif_flags
229 contains the
230 .Dv MIFF_*
231 flags as defined in
232 .In netinet6/ip6_mroute.h .
233 The
234 .Va pif_index
235 is the physical interface index of the corresponding local interface.
236 .Pp
237 A multicast interface is deleted by:
238 .Bd -literal
239 /* IPv4 */
240 vifi_t vifi = vif_index;
241 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi,
242 sizeof(vifi));
243 .Ed
244 .Bd -literal
245 /* IPv6 */
246 mifi_t mifi = mif_index;
247 setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi,
248 sizeof(mifi));
249 .Ed
250 .Pp
251 After the multicast forwarding is enabled, and the multicast virtual
252 interfaces are
253 added, the kernel may deliver upcall messages (also called signals
254 later in this text) on the multicast routing socket that was open
255 earlier with
256 .Dv MRT_INIT
257 or
258 .Dv MRT6_INIT .
259 The IPv4 upcalls have
260 .Vt "struct igmpmsg"
261 header (see
262 .In netinet/ip_mroute.h )
263 with field
264 .Va im_mbz
265 set to zero.
266 Note that this header follows the structure of
267 .Vt "struct ip"
268 with the protocol field
269 .Va ip_p
270 set to zero.
271 The IPv6 upcalls have
272 .Vt "struct mrt6msg"
273 header (see
274 .In netinet6/ip6_mroute.h )
275 with field
276 .Va im6_mbz
277 set to zero.
278 Note that this header follows the structure of
279 .Vt "struct ip6_hdr"
280 with the next header field
281 .Va ip6_nxt
282 set to zero.
283 .Pp
284 The upcall header contains field
285 .Va im_msgtype
286 and
287 .Va im6_msgtype
288 with the type of the upcall
289 .Dv IGMPMSG_*
290 and
291 .Dv MRT6MSG_*
292 for IPv4 and IPv6 respectively.
293 The values of the rest of the upcall header fields
294 and the body of the upcall message depend on the particular upcall type.
295 .Pp
296 If the upcall message type is
297 .Dv IGMPMSG_NOCACHE
298 or
299 .Dv MRT6MSG_NOCACHE ,
300 this is an indication that a multicast packet has reached the multicast
301 router, but the router has no forwarding state for that packet.
302 Typically, the upcall would be a signal for the multicast routing
303 user-level process to install the appropriate Multicast Forwarding
304 Cache (MFC) entry in the kernel.
305 .Pp
306 An MFC entry is added by:
307 .Bd -literal
308 /* IPv4 */
309 struct mfcctl mc;
310 memset(&mc, 0, sizeof(mc));
311 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
312 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
313 mc.mfcc_parent = iif_index;
314 for (i = 0; i < maxvifs; i++)
315 mc.mfcc_ttls[i] = oifs_ttl[i];
316 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC,
317 (void *)&mc, sizeof(mc));
318 .Ed
319 .Bd -literal
320 /* IPv6 */
321 struct mf6cctl mc;
322 memset(&mc, 0, sizeof(mc));
323 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
324 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
325 mc.mf6cc_parent = iif_index;
326 for (i = 0; i < maxvifs; i++)
327 if (oifs_ttl[i] > 0)
328 IF_SET(i, &mc.mf6cc_ifset);
329 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC,
330 (void *)&mc, sizeof(mc));
331 .Ed
332 .Pp
333 The
334 .Va source_addr
335 and
336 .Va group_addr
337 are the source and group address of the multicast packet (as set
338 in the upcall message).
339 The
340 .Va iif_index
341 is the virtual interface index of the multicast interface the multicast
342 packets for this specific source and group address should be received on.
343 The
344 .Va oifs_ttl[]
345 array contains the minimum TTL (per interface) a multicast packet
346 should have to be forwarded on an outgoing interface.
347 If the TTL value is zero, the corresponding interface is not included
348 in the set of outgoing interfaces.
349 Note that in case of IPv6 only the set of outgoing interfaces can
350 be specified.
351 .Pp
352 An MFC entry is deleted by:
353 .Bd -literal
354 /* IPv4 */
355 struct mfcctl mc;
356 memset(&mc, 0, sizeof(mc));
357 memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin));
358 memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp));
359 setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC,
360 (void *)&mc, sizeof(mc));
361 .Ed
362 .Bd -literal
363 /* IPv6 */
364 struct mf6cctl mc;
365 memset(&mc, 0, sizeof(mc));
366 memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin));
367 memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp));
368 setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC,
369 (void *)&mc, sizeof(mc));
370 .Ed
371 .Pp
372 The following method can be used to get various statistics per
373 installed MFC entry in the kernel (e.g., the number of forwarded
374 packets per source and group address):
375 .Bd -literal
376 /* IPv4 */
377 struct sioc_sg_req sgreq;
378 memset(&sgreq, 0, sizeof(sgreq));
379 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
380 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
381 ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq);
382 .Ed
383 .Bd -literal
384 /* IPv6 */
385 struct sioc_sg_req6 sgreq;
386 memset(&sgreq, 0, sizeof(sgreq));
387 memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src));
388 memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp));
389 ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq);
390 .Ed
391 .Pp
392 The following method can be used to get various statistics per
393 multicast virtual interface in the kernel (e.g., the number of forwarded
394 packets per interface):
395 .Bd -literal
396 /* IPv4 */
397 struct sioc_vif_req vreq;
398 memset(&vreq, 0, sizeof(vreq));
399 vreq.vifi = vif_index;
400 ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq);
401 .Ed
402 .Bd -literal
403 /* IPv6 */
404 struct sioc_mif_req6 mreq;
405 memset(&mreq, 0, sizeof(mreq));
406 mreq.mifi = vif_index;
407 ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq);
408 .Ed
409 .Ss Advanced Multicast API Programming Guide
410 If we want to add new features in the kernel, it becomes difficult
411 to preserve backward compatibility (binary and API),
412 and at the same time to allow user-level processes to take advantage of
413 the new features (if the kernel supports them).
414 .Pp
415 One of the mechanisms that allows us to preserve the backward
416 compatibility is a sort of negotiation
417 between the user-level process and the kernel:
418 .Bl -enum
419 .It
420 The user-level process tries to enable in the kernel the set of new
421 features (and the corresponding API) it would like to use.
422 .It
423 The kernel returns the (sub)set of features it knows about
424 and is willing to be enabled.
425 .It
426 The user-level process uses only that set of features
427 the kernel has agreed on.
428 .El
429 .\"
430 .Pp
431 To support backward compatibility, if the user-level process does not
432 ask for any new features, the kernel defaults to the basic
433 multicast API (see the
434 .Sx "Programming Guide"
435 section).
436 .\" XXX: edit as appropriate after the advanced multicast API is
437 .\" supported under IPv6
438 Currently, the advanced multicast API exists only for IPv4;
439 in the future there will be IPv6 support as well.
440 .Pp
441 Below is a summary of the expandable API solution.
442 Note that all new options and structures are defined
443 in
444 .In netinet/ip_mroute.h
445 and
446 .In netinet6/ip6_mroute.h ,
447 unless stated otherwise.
448 .Pp
449 The user-level process uses new
450 .Fn getsockopt Ns / Ns Fn setsockopt
451 options to
452 perform the API features negotiation with the kernel.
453 This negotiation must be performed right after the multicast routing
454 socket is open.
455 The set of desired/allowed features is stored in a bitset
456 (currently, in
457 .Vt uint32_t ;
458 i.e., maximum of 32 new features).
459 The new
460 .Fn getsockopt Ns / Ns Fn setsockopt
461 options are
462 .Dv MRT_API_SUPPORT
463 and
464 .Dv MRT_API_CONFIG .
465 Example:
466 .Bd -literal
467 uint32_t v;
468 getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v));
469 .Ed
470 .Pp
471 would set in
472 .Va v
473 the pre-defined bits that the kernel API supports.
474 The eight least significant bits in
475 .Vt uint32_t
476 are same as the
477 eight possible flags
478 .Dv MRT_MFC_FLAGS_*
479 that can be used in
480 .Va mfcc_flags
481 as part of the new definition of
482 .Vt "struct mfcctl"
483 (see below about those flags), which leaves 24 flags for other new features.
484 The value returned by
485 .Fn getsockopt MRT_API_SUPPORT
486 is read-only; in other words,
487 .Fn setsockopt MRT_API_SUPPORT
488 would fail.
489 .Pp
490 To modify the API, and to set some specific feature in the kernel, then:
491 .Bd -literal
492 uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF;
493 if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v))
494 != 0) {
495 return (ERROR);
496 }
497 if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF)
498 return (OK); /* Success */
499 else
500 return (ERROR);
501 .Ed
502 .Pp
503 In other words, when
504 .Fn setsockopt MRT_API_CONFIG
505 is called, the
506 argument to it specifies the desired set of features to
507 be enabled in the API and the kernel.
508 The return value in
509 .Va v
510 is the actual (sub)set of features that were enabled in the kernel.
511 To obtain later the same set of features that were enabled, then:
512 .Bd -literal
513 getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v));
514 .Ed
515 .Pp
516 The set of enabled features is global.
517 In other words,
518 .Fn setsockopt MRT_API_CONFIG
519 should be called right after
520 .Fn setsockopt MRT_INIT .
521 .Pp
522 Currently, the following set of new features is defined:
523 .Bd -literal
524 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
525 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
526 #define MRT_MFC_RP (1 << 8) /* enable RP address */
527 #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */
528 .Ed
529 .\" .Pp
530 .\" In the future there might be:
531 .\" .Bd -literal
532 .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */
533 .\" .Ed
534 .\" .Pp
535 .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel.
536 .\" For now this is left-out until it is clear whether
537 .\" (*,G) MFC support is the preferred solution instead of something more generic
538 .\" solution for example.
539 .\"
540 .\" 2. The newly defined struct mfcctl2.
541 .\"
542 .Pp
543 The advanced multicast API uses a newly defined
544 .Vt "struct mfcctl2"
545 instead of the traditional
546 .Vt "struct mfcctl" .
547 The original
548 .Vt "struct mfcctl"
549 is kept as is.
550 The new
551 .Vt "struct mfcctl2"
552 is:
553 .Bd -literal
554 /*
555 * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays
556 * and extends the old struct mfcctl.
557 */
558 struct mfcctl2 {
559 /* the mfcctl fields */
560 struct in_addr mfcc_origin; /* ip origin of mcasts */
561 struct in_addr mfcc_mcastgrp; /* multicast group associated*/
562 vifi_t mfcc_parent; /* incoming vif */
563 u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */
565 /* extension fields */
566 uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/
567 struct in_addr mfcc_rp; /* the RP address */
568 };
569 .Ed
570 .Pp
571 The new fields are
572 .Va mfcc_flags[MAXVIFS]
573 and
574 .Va mfcc_rp .
575 Note that for compatibility reasons they are added at the end.
576 .Pp
577 The
578 .Va mfcc_flags[MAXVIFS]
579 field is used to set various flags per
580 interface per (S,G) entry.
581 Currently, the defined flags are:
582 .Bd -literal
583 #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */
584 #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */
585 .Ed
586 .Pp
587 The
588 .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF
589 flag is used to explicitly disable the
590 .Dv IGMPMSG_WRONGVIF
591 kernel signal at the (S,G) granularity if a multicast data packet
592 arrives on the wrong interface.
593 Usually, this signal is used to
594 complete the shortest-path switch in case of PIM-SM multicast routing,
595 or to trigger a PIM assert message.
596 However, it should not be delivered for interfaces that are not in
597 the outgoing interface set, and that are not expecting to
598 become an incoming interface.
599 Hence, if the
600 .Dv MRT_MFC_FLAGS_DISABLE_WRONGVIF
601 flag is set for some of the
602 interfaces, then a data packet that arrives on that interface for
603 that MFC entry will NOT trigger a WRONGVIF signal.
604 If that flag is not set, then a signal is triggered (the default action).
605 .Pp
606 The
607 .Dv MRT_MFC_FLAGS_BORDER_VIF
608 flag is used to specify whether the Border-bit in PIM
609 Register messages should be set (in case when the Register encapsulation
610 is performed inside the kernel).
611 If it is set for the special PIM Register kernel virtual interface
612 (see
613 .Xr pim 4 ) ,
614 the Border-bit in the Register messages sent to the RP will be set.
615 .Pp
616 The remaining six bits are reserved for future usage.
617 .Pp
618 The
619 .Va mfcc_rp
620 field is used to specify the RP address (in case of PIM-SM multicast routing)
621 for a multicast
622 group G if we want to perform kernel-level PIM Register encapsulation.
623 The
624 .Va mfcc_rp
625 field is used only if the
626 .Dv MRT_MFC_RP
627 advanced API flag/capability has been successfully set by
628 .Fn setsockopt MRT_API_CONFIG .
629 .Pp
630 .\"
631 .\" 3. Kernel-level PIM Register encapsulation
632 .\"
633 If the
634 .Dv MRT_MFC_RP
635 flag was successfully set by
636 .Fn setsockopt MRT_API_CONFIG ,
637 then the kernel will attempt to perform
638 the PIM Register encapsulation itself instead of sending the
639 multicast data packets to user level (inside
640 .Dv IGMPMSG_WHOLEPKT
641 upcalls) for user-level encapsulation.
642 The RP address would be taken from the
643 .Va mfcc_rp
644 field
645 inside the new
646 .Vt "struct mfcctl2" .
647 However, even if the
648 .Dv MRT_MFC_RP
649 flag was successfully set, if the
650 .Va mfcc_rp
651 field was set to
652 .Dv INADDR_ANY ,
653 then the
654 kernel will still deliver an
655 .Dv IGMPMSG_WHOLEPKT
656 upcall with the
657 multicast data packet to the user-level process.
658 .Pp
659 In addition, if the multicast data packet is too large to fit within
660 a single IP packet after the PIM Register encapsulation (e.g., if
661 its size was on the order of 65500 bytes), the data packet will be
662 fragmented, and then each of the fragments will be encapsulated
663 separately.
664 Note that typically a multicast data packet can be that
665 large only if it was originated locally from the same hosts that
666 performs the encapsulation; otherwise the transmission of the
667 multicast data packet over Ethernet for example would have
668 fragmented it into much smaller pieces.
669 .\"
670 .\" Note that if this code is ported to IPv6, we may need the kernel to
671 .\" perform MTU discovery to the RP, and keep those discoveries inside
672 .\" the kernel so the encapsulating router may send back ICMP
673 .\" Fragmentation Required if the size of the multicast data packet is
674 .\" too large (see "Encapsulating data packets in the Register Tunnel"
675 .\" in Section 4.4.1 in the PIM-SM spec
676 .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}).
677 .\" For IPv4 we may be able to get away without it, but for IPv6 we need
678 .\" that.
679 .\"
680 .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls".
681 .\"
682 .Pp
683 Typically, a multicast routing user-level process would need to know the
684 forwarding bandwidth for some data flow.
685 For example, the multicast routing process may want to timeout idle MFC
686 entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if
687 the bandwidth rate is above a threshold for example.
688 .Pp
689 The original solution for measuring the bandwidth of a dataflow was
690 that a user-level process would periodically
691 query the kernel about the number of forwarded packets/bytes per
692 (S,G), and then based on those numbers it would estimate whether a source
693 has been idle, or whether the source's transmission bandwidth is above a
694 threshold.
695 That solution is far from being scalable, hence the need for a new
696 mechanism for bandwidth monitoring.
697 .Pp
698 Below is a description of the bandwidth monitoring mechanism.
699 .Bl -bullet
700 .It
701 If the bandwidth of a data flow satisfies some pre-defined filter,
702 the kernel delivers an upcall on the multicast routing socket
703 to the multicast routing process that has installed that filter.
704 .It
705 The bandwidth-upcall filters are installed per (S,G).
706 There can be
707 more than one filter per (S,G).
708 .It
709 Instead of supporting all possible comparison operations
710 (i.e., < <= == != > >= ), there is support only for the
711 <= and >= operations,
712 because this makes the kernel-level implementation simpler,
713 and because practically we need only those two.
714 Further, the missing operations can be simulated by secondary
715 user-level filtering of those <= and >= filters.
716 For example, to simulate !=, then we need to install filter
717 .Dq bw <= 0xffffffff ,
718 and after an
719 upcall is received, we need to check whether
720 .Dq measured_bw != expected_bw .
721 .It
722 The bandwidth-upcall mechanism is enabled by
723 .Fn setsockopt MRT_API_CONFIG
724 for the
725 .Dv MRT_MFC_BW_UPCALL
726 flag.
727 .It
728 The bandwidth-upcall filters are added/deleted by the new
729 .Fn setsockopt MRT_ADD_BW_UPCALL
730 and
731 .Fn setsockopt MRT_DEL_BW_UPCALL
732 respectively (with the appropriate
733 .Vt "struct bw_upcall"
734 argument of course).
735 .El
736 .Pp
737 From application point of view, a developer needs to know about
738 the following:
739 .Bd -literal
740 /*
741 * Structure for installing or delivering an upcall if the
742 * measured bandwidth is above or below a threshold.
743 *
744 * User programs (e.g. daemons) may have a need to know when the
745 * bandwidth used by some data flow is above or below some threshold.
746 * This interface allows the userland to specify the threshold (in
747 * bytes and/or packets) and the measurement interval. Flows are
748 * all packet with the same source and destination IP address.
749 * At the moment the code is only used for multicast destinations
750 * but there is nothing that prevents its use for unicast.
751 *
752 * The measurement interval cannot be shorter than some Tmin (currently, 3s).
753 * The threshold is set in packets and/or bytes per_interval.
754 *
755 * Measurement works as follows:
756 *
757 * For >= measurements:
758 * The first packet marks the start of a measurement interval.
759 * During an interval we count packets and bytes, and when we
760 * pass the threshold we deliver an upcall and we are done.
761 * The first packet after the end of the interval resets the
762 * count and restarts the measurement.
763 *
764 * For <= measurement:
765 * We start a timer to fire at the end of the interval, and
766 * then for each incoming packet we count packets and bytes.
767 * When the timer fires, we compare the value with the threshold,
768 * schedule an upcall if we are below, and restart the measurement
769 * (reschedule timer and zero counters).
770 */
772 struct bw_data {
773 struct timeval b_time;
774 uint64_t b_packets;
775 uint64_t b_bytes;
776 };
778 struct bw_upcall {
779 struct in_addr bu_src; /* source address */
780 struct in_addr bu_dst; /* destination address */
781 uint32_t bu_flags; /* misc flags (see below) */
782 #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */
783 #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */
784 #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */
785 #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */
786 #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/
787 struct bw_data bu_threshold; /* the bw threshold */
788 struct bw_data bu_measured; /* the measured bw */
789 };
791 /* max. number of upcalls to deliver together */
792 #define BW_UPCALLS_MAX 128
793 /* min. threshold time interval for bandwidth measurement */
794 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3
795 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0
796 .Ed
797 .Pp
798 The
799 .Vt bw_upcall
800 structure is used as an argument to
801 .Fn setsockopt MRT_ADD_BW_UPCALL
802 and
803 .Fn setsockopt MRT_DEL_BW_UPCALL .
804 Each
805 .Fn setsockopt MRT_ADD_BW_UPCALL
806 installs a filter in the kernel
807 for the source and destination address in the
808 .Vt bw_upcall
809 argument,
810 and that filter will trigger an upcall according to the following
811 pseudo-algorithm:
812 .Bd -literal
813 if (bw_upcall_oper IS ">=") {
814 if (((bw_upcall_unit & PACKETS == PACKETS) &&
815 (measured_packets >= threshold_packets)) ||
816 ((bw_upcall_unit & BYTES == BYTES) &&
817 (measured_bytes >= threshold_bytes)))
818 SEND_UPCALL("measured bandwidth is >= threshold");
819 }
820 if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) {
821 if (((bw_upcall_unit & PACKETS == PACKETS) &&
822 (measured_packets <= threshold_packets)) ||
823 ((bw_upcall_unit & BYTES == BYTES) &&
824 (measured_bytes <= threshold_bytes)))
825 SEND_UPCALL("measured bandwidth is <= threshold");
826 }
827 .Ed
828 .Pp
829 In the same
830 .Vt bw_upcall
831 the unit can be specified in both BYTES and PACKETS.
832 However, the GEQ and LEQ flags are mutually exclusive.
833 .Pp
834 Basically, an upcall is delivered if the measured bandwidth is >= or
835 <= the threshold bandwidth (within the specified measurement
836 interval).
837 For practical reasons, the smallest value for the measurement
838 interval is 3 seconds.
839 If smaller values are allowed, then the bandwidth
840 estimation may be less accurate, or the potentially very high frequency
841 of the generated upcalls may introduce too much overhead.
842 For the >= operation, the answer may be known before the end of
843 .Va threshold_interval ,
844 therefore the upcall may be delivered earlier.
845 For the <= operation however, we must wait
846 until the threshold interval has expired to know the answer.
847 .Pp
848 Example of usage:
849 .Bd -literal
850 struct bw_upcall bw_upcall;
851 /* Assign all bw_upcall fields as appropriate */
852 memset(&bw_upcall, 0, sizeof(bw_upcall));
853 memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src));
854 memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst));
855 bw_upcall.bu_threshold.b_data = threshold_interval;
856 bw_upcall.bu_threshold.b_packets = threshold_packets;
857 bw_upcall.bu_threshold.b_bytes = threshold_bytes;
858 if (is_threshold_in_packets)
859 bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS;
860 if (is_threshold_in_bytes)
861 bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES;
862 do {
863 if (is_geq_upcall) {
864 bw_upcall.bu_flags |= BW_UPCALL_GEQ;
865 break;
866 }
867 if (is_leq_upcall) {
868 bw_upcall.bu_flags |= BW_UPCALL_LEQ;
869 break;
870 }
871 return (ERROR);
872 } while (0);
873 setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL,
874 (void *)&bw_upcall, sizeof(bw_upcall));
875 .Ed
876 .Pp
877 To delete a single filter, then use
878 .Dv MRT_DEL_BW_UPCALL ,
879 and the fields of bw_upcall must be set
880 exactly same as when
881 .Dv MRT_ADD_BW_UPCALL
882 was called.
883 .Pp
884 To delete all bandwidth filters for a given (S,G), then
885 only the
886 .Va bu_src
887 and
888 .Va bu_dst
889 fields in
890 .Vt "struct bw_upcall"
891 need to be set, and then just set only the
892 .Dv BW_UPCALL_DELETE_ALL
893 flag inside field
894 .Va bw_upcall.bu_flags .
895 .Pp
896 The bandwidth upcalls are received by aggregating them in the new upcall
897 message:
898 .Bd -literal
899 #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */
900 .Ed
901 .Pp
902 This message is an array of
903 .Vt "struct bw_upcall"
904 elements (up to
905 .Dv BW_UPCALLS_MAX
906 = 128).
907 The upcalls are
908 delivered when there are 128 pending upcalls, or when 1 second has
909 expired since the previous upcall (whichever comes first).
910 In an
911 .Vt "struct upcall"
912 element, the
913 .Va bu_measured
914 field is filled-in to
915 indicate the particular measured values.
916 However, because of the way
917 the particular intervals are measured, the user should be careful how
918 .Va bu_measured.b_time
919 is used.
920 For example, if the
921 filter is installed to trigger an upcall if the number of packets
922 is >= 1, then
923 .Va bu_measured
924 may have a value of zero in the upcalls after the
925 first one, because the measured interval for >= filters is
926 .Dq clocked
927 by the forwarded packets.
928 Hence, this upcall mechanism should not be used for measuring
929 the exact value of the bandwidth of the forwarded data.
930 To measure the exact bandwidth, the user would need to
931 get the forwarded packets statistics with the
932 .Fn ioctl SIOCGETSGCNT
933 mechanism
934 (see the
935 .Sx Programming Guide
936 section) .
937 .Pp
938 Note that the upcalls for a filter are delivered until the specific
939 filter is deleted, but no more frequently than once per
940 .Va bu_threshold.b_time .
941 For example, if the filter is specified to
942 deliver a signal if bw >= 1 packet, the first packet will trigger a
943 signal, but the next upcall will be triggered no earlier than
944 .Va bu_threshold.b_time
945 after the previous upcall.
946 .\"
947 .Sh SEE ALSO
948 .Xr altq 4 ,
949 .Xr dummynet 4 ,
950 .Xr getsockopt 2 ,
951 .Xr gif 4 ,
952 .Xr gre 4 ,
953 .Xr recvfrom 2 ,
954 .Xr recvmsg 2 ,
955 .Xr setsockopt 2 ,
956 .Xr socket 2 ,
957 .Xr icmp6 4 ,
958 .Xr inet 4 ,
959 .Xr inet6 4 ,
960 .Xr intro 4 ,
961 .Xr ip 4 ,
962 .Xr ip6 4 ,
963 .Xr pim 4
964 .\"
965 .Sh HISTORY
966 The Distance Vector Multicast Routing Protocol (DVMRP)
967 was the first developed multicast routing protocol.
968 Later, other protocols such as Multicast Extensions to OSPF (MOSPF)
969 and Core Based Trees (CBT), were developed as well.
970 Routers at autonomous system boundaries may now exchange multicast
971 routes with peers via the Border Gateway Protocol (BGP).
972 Many other routing protocols are able to redistribute multicast routes
973 for use with
974 .Dv PIM-SM
975 and
976 .Dv PIM-DM .
977 .Sh AUTHORS
978 .An -nosplit
979 The original multicast code was written by
980 .An David Waitzman
981 (BBN Labs),
982 and later modified by the following individuals:
983 .An Steve Deering
984 (Stanford),
985 .An Mark J. Steiglitz
986 (Stanford),
987 .An Van Jacobson
988 (LBL),
989 .An Ajit Thyagarajan
990 (PARC),
991 .An Bill Fenner
992 (PARC).
993 The IPv6 multicast support was implemented by the KAME project
994 .Pq Pa http://www.kame.net ,
995 and was based on the IPv4 multicast code.
996 The advanced multicast API and the multicast bandwidth
997 monitoring were implemented by
998 .An Pavlin Radoslavov
999 (ICSI)
1000 in collaboration with
1001 .An Chris Brown
1002 (NextHop).
1003 .Pp
1004 This manual page was written by
1005 .An Pavlin Radoslavov
1006 (ICSI).