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