path: root/share/man/man4/pim.4

.\" Copyright (c) 2001-2003 International Computer Science Institute
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
.\" to deal in the Software without restriction, including without limitation
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
.\" and/or sell copies of the Software, and to permit persons to whom the
.\" Software is furnished to do so, subject to the following conditions:
.\"
.\" The above copyright notice and this permission notice shall be included in
.\" all copies or substantial portions of the Software.
.\"
.\" The names and trademarks of copyright holders may not be used in
.\" advertising or publicity pertaining to the software without specific
.\" prior permission. Title to copyright in this software and any associated
.\" documentation will at all times remain with the copyright holders.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
.\" DEALINGS IN THE SOFTWARE.
.\"
.\" $FreeBSD: src/share/man/man4/pim.4,v 1.2 2004/07/09 09:22:36 ru Exp $
.\" $OpenBSD: pim.4,v 1.6 2007/05/31 19:19:51 jmc Exp $
.\" $NetBSD: pim.4,v 1.2 2004/09/12 13:06:14 wiz Exp $
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt PIM 4
.Os
.\"
.Sh NAME
.Nm pim
.Nd Protocol Independent Multicast
.\"
.Sh SYNOPSIS
.Cd "options MROUTING"
.Cd "options PIM"
.Pp
.In sys/types.h
.In sys/socket.h
.In netinet/in.h
.In netinet/ip_mroute.h
.In netinet/pim.h
.Ft int
.Fn getsockopt "int s" IPPROTO_IP MRT_PIM "void *optval" "socklen_t *optlen"
.Ft int
.Fn setsockopt "int s" IPPROTO_IP MRT_PIM "const void *optval" "socklen_t optlen"
.Ft int
.Fn getsockopt "int s" IPPROTO_IPV6 MRT6_PIM "void *optval" "socklen_t *optlen"
.Ft int
.Fn setsockopt "int s" IPPROTO_IPV6 MRT6_PIM "const void *optval" "socklen_t optlen"
.Sh DESCRIPTION
.Tn PIM
is the common name for two multicast routing protocols:
Protocol Independent Multicast \- Sparse Mode (PIM-SM) and
Protocol Independent Multicast \- Dense Mode (PIM-DM).
.Pp
PIM-SM is a multicast routing protocol that can use the underlying
unicast routing information base or a separate multicast-capable
routing information base.
It builds unidirectional shared trees rooted at a Rendezvous
Point (RP) per group,
and optionally creates shortest-path trees per source.
.Pp
PIM-DM is a multicast routing protocol that uses the underlying
unicast routing information base to flood multicast datagrams
to all multicast routers.
Prune messages are used to prevent future datagrams from propagating
to routers with no group membership information.
.Pp
Both PIM-SM and PIM-DM are fairly complex protocols,
though PIM-SM is much more complex.
To enable PIM-SM or PIM-DM multicast routing in a router,
the user must enable multicast forwarding via the
.Va net.inet.ip.mforwarding
.Xr sysctl 8
and PIM processing in the kernel
(see
.Sx SYNOPSIS
for the correct kernel configuration option).
The user must also run a PIM-SM or PIM-DM capable user-level process.
From a developer's point of view,
the programming guide described in the
.Sx "Programming Guide"
section should be used to control the PIM processing in the kernel.
.\"
.Ss Programming Guide
After a multicast routing socket is open and multicast forwarding
is enabled in the kernel
(see
.Xr multicast 4 ) ,
one of the following socket options should be used to enable or disable
PIM processing in the kernel.
Note that those options require certain privilege
(i.e., root privilege):
.Bd -literal -offset 4n
/* IPv4 */
int v = 1;        /* 1 to enable, or 0 to disable */
setsockopt(mrouter_s4, IPPROTO_IP, MRT_PIM, (void *)&v, sizeof(v));
.Ed
.Bd -literal -offset 4n
/* IPv6 */
int v = 1;        /* 1 to enable, or 0 to disable */
setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_PIM, (void *)&v, sizeof(v));
.Ed
.Pp
After PIM processing is enabled, the multicast-capable interfaces
should be added
(see
.Xr multicast 4 ) .
For PIM-SM, the PIM-Register virtual interface must be added
as well.
This can be accomplished by using the following options:
.Bd -literal -offset indent
/* IPv4 */
struct vifctl vc;
memset(&vc, 0, sizeof(vc));
/* Assign all vifctl fields as appropriate */
\&...
if (is_pim_register_vif)
    vc.vifc_flags |= VIFF_REGISTER;
setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc,
           sizeof(vc));
.Ed
.Bd -literal -offset indent
/* IPv6 */
struct mif6ctl mc;
memset(&mc, 0, sizeof(mc));
/* Assign all mif6ctl fields as appropriate */
\&...
if (is_pim_register_vif)
    mc.mif6c_flags |= MIFF_REGISTER;
setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc,
           sizeof(mc));
.Ed
.Pp
Sending or receiving of PIM packets can be accomplished by
first opening a
.Dq raw socket
(see
.Xr socket 2 ) ,
with protocol value of
.Dv IPPROTO_PIM :
.Bd -literal -offset indent
/* IPv4 */
int pim_s4;
pim_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_PIM);
.Ed
.Bd -literal -offset indent
/* IPv6 */
int pim_s6;
pim_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_PIM);
.Ed
.Pp
Then the following system calls can be used to send or receive PIM
packets:
.Xr sendto 2 ,
.Xr sendmsg 2 ,
.Xr recvfrom 2 ,
and
.Xr recvmsg 2 .
.\"
.Sh SEE ALSO
.Xr getsockopt 2 ,
.Xr recvfrom 2 ,
.Xr recvmsg 2 ,
.Xr sendmsg 2 ,
.Xr sendto 2 ,
.Xr setsockopt 2 ,
.Xr socket 2 ,
.Xr inet 4 ,
.Xr intro 4 ,
.Xr ip 4 ,
.Xr multicast 4 ,
.Xr sysctl 8
.\"
.Sh STANDARDS
The PIM-SM protocol is specified in RFC 2362 (to be replaced by
.Pa draft-ietf-pim-sm-v2-new-* ) .
The PIM-DM protocol is specified in RFC 3973.
.\"
.Sh AUTHORS
.An -nosplit
The original IPv4 PIM kernel support for IRIX and SunOS-4.x was
implemented by
.An Ahmed Helmy
(USC and SGI).
Later the code was ported to various
.Bx
flavors and modified by
.An George Edmond Eddy
(Rusty) (ISI),
.An Hitoshi Asaeda
(WIDE Project), and
.An Pavlin Radoslavov
(USC/ISI and ICSI).
.Pp
The IPv6 PIM kernel support was implemented by the KAME project
.Pq Pa http://www.kame.net ,
and was based on the IPv4 PIM kernel support.
.Pp
This manual page was written by
.An Pavlin Radoslavov
(ICSI).