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