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