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 September 4, 2003 29.Dt PIM 4 30.Os 31.\" 32.Sh NAME 33.Nm pim 34.Nd Protocol Independent Multicast 35.\" 36.Sh SYNOPSIS 37.Cd "options MROUTING" 38.Cd "options PIM" 39.Pp 40.In sys/types.h 41.In sys/socket.h 42.In netinet/in.h 43.In netinet/ip_mroute.h 44.In netinet/pim.h 45.Ft int 46.Fn getsockopt "int s" IPPROTO_IP MRT_PIM "void *optval" "socklen_t *optlen" 47.Ft int 48.Fn setsockopt "int s" IPPROTO_IP MRT_PIM "const void *optval" "socklen_t optlen" 49.Ft int 50.Fn getsockopt "int s" IPPROTO_IPV6 MRT6_PIM "void *optval" "socklen_t *optlen" 51.Ft int 52.Fn setsockopt "int s" IPPROTO_IPV6 MRT6_PIM "const void *optval" "socklen_t optlen" 53.Sh DESCRIPTION 54.Tn PIM 55is the common name for two multicast routing protocols: 56Protocol Independent Multicast - Sparse Mode (PIM-SM) and 57Protocol Independent Multicast - Dense Mode (PIM-DM). 58.Pp 59PIM-SM is a multicast routing protocol that can use the underlying 60unicast routing information base or a separate multicast-capable 61routing information base. 62It builds unidirectional shared trees rooted at a Rendezvous 63Point (RP) per group, 64and optionally creates shortest-path trees per source. 65.Pp 66PIM-DM is a multicast routing protocol that uses the underlying 67unicast routing information base to flood multicast datagrams 68to all multicast routers. 69Prune messages are used to prevent future datagrams from propagating 70to routers with no group membership information. 71.Pp 72Both PIM-SM and PIM-DM are fairly complex protocols, 73though PIM-SM is much more complex. 74To enable PIM-SM or PIM-DM multicast routing in a router, 75the user must enable multicast routing and PIM processing in the kernel 76(see 77.Sx SYNOPSIS 78about the kernel configuration options), 79and must run a PIM-SM or PIM-DM capable user-level process. 80From developer's point of view, 81the programming guide described in the 82.Sx "Programming Guide" 83section should be used to control the PIM processing in the kernel. 84.\" 85.Ss Programming Guide 86After a multicast routing socket is open and multicast forwarding 87is enabled in the kernel 88(see 89.Xr multicast 4 ) , 90one of the following socket options should be used to enable or disable 91PIM processing in the kernel. 92Note that those options require certain privilege 93(i.e., root privilege): 94.Bd -literal 95/* IPv4 */ 96int v = 1; /* 1 to enable, or 0 to disable */ 97setsockopt(mrouter_s4, IPPROTO_IP, MRT_PIM, (void *)&v, sizeof(v)); 98.Ed 99.Bd -literal 100/* IPv6 */ 101int v = 1; /* 1 to enable, or 0 to disable */ 102setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_PIM, (void *)&v, sizeof(v)); 103.Ed 104.Pp 105After PIM processing is enabled, the multicast-capable interfaces 106should be added 107(see 108.Xr multicast 4 ) . 109In case of PIM-SM, the PIM-Register virtual interface must be added 110as well. 111This can be accomplished by using the following options: 112.Bd -literal 113/* IPv4 */ 114struct vifctl vc; 115memset(&vc, 0, sizeof(vc)); 116/* Assign all vifctl fields as appropriate */ 117\&... 118if (is_pim_register_vif) 119 vc.vifc_flags |= VIFF_REGISTER; 120setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc, 121 sizeof(vc)); 122.Ed 123.Bd -literal 124/* IPv6 */ 125struct mif6ctl mc; 126memset(&mc, 0, sizeof(mc)); 127/* Assign all mif6ctl fields as appropriate */ 128\&... 129if (is_pim_register_vif) 130 mc.mif6c_flags |= MIFF_REGISTER; 131setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc, 132 sizeof(mc)); 133.Ed 134.Pp 135Sending or receiving of PIM packets can be accomplished by 136opening first a 137.Dq raw socket 138(see 139.Xr socket 2 ) , 140with protocol value of 141.Dv IPPROTO_PIM : 142.Bd -literal 143/* IPv4 */ 144int pim_s4; 145pim_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_PIM); 146.Ed 147.Bd -literal 148/* IPv6 */ 149int pim_s6; 150pim_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_PIM); 151.Ed 152.Pp 153Then, the following system calls can be used to send or receive PIM 154packets: 155.Xr sendto 2 , 156.Xr sendmsg 2 , 157.Xr recvfrom 2 , 158.Xr recvmsg 2 . 159.\" 160.Sh SEE ALSO 161.Xr getsockopt 2 , 162.Xr recvfrom 2 , 163.Xr recvmsg 2 , 164.Xr sendmsg 2 , 165.Xr sendto 2 , 166.Xr setsockopt 2 , 167.Xr socket 2 , 168.Xr inet 4 , 169.Xr intro 4 , 170.Xr ip 4 , 171.Xr multicast 4 172.\" 173.Sh STANDARDS 174.\" XXX the PIM-SM number must be updated after RFC 2362 is 175.\" replaced by a new RFC by the end of year 2003 or so. 176The PIM-SM protocol is specified in RFC 2362 (to be replaced by 177.%T draft-ietf-pim-sm-v2-new-* ) . 178The PIM-DM protocol is specified in 179.%T draft-ietf-pim-dm-new-v2-* ) . 180.\" 181.Sh AUTHORS 182.An -nosplit 183The original IPv4 PIM kernel support for IRIX and SunOS-4.x was 184implemented by 185.An Ahmed Helmy 186(USC and SGI). 187Later the code was ported to various 188.Bx 189flavors and modified by 190.An George Edmond Eddy 191(Rusty) (ISI), 192.An Hitoshi Asaeda 193(WIDE Project), and 194.An Pavlin Radoslavov 195(USC/ISI and ICSI). 196The IPv6 PIM kernel support was implemented by the KAME project 197.Pq Pa http://www.kame.net , 198and was based on the IPv4 PIM kernel support. 199.Pp 200This manual page was written by 201.An Pavlin Radoslavov 202(ICSI). 203