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