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