Add multicast(4) and pim(4) manual pages and hook up to the build.

Submitted by:	Pavlin Radoslavov <pavlin@icir.org>
Reviewed by:	hsu, bmah
MFC after:	2 weeks

1 files changed, 192 insertions, 0 deletions

diff --git a/share/man/man4/pim.4 b/share/man/man4/pim.4
new file mode 100644
index 0000000..bf1e88d
--- /dev/null
+++ b/share/man/man4/pim.4
@@ -0,0 +1,192 @@
+.\" 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$
+.\"
+.Dd September 4, 2003
+.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 routing and PIM processing in the kernel
+(see
+.Sx SYNOPSIS
+about the kernel configuration options),
+and must run a PIM-SM or PIM-DM capable user-level process.
+From 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):
+.Pp
+.Bd -literal
+/* IPv4 */
+int v = 1;        /* 1 to enable, or 0 to disable */
+setsockopt(mrouter_s4, IPPROTO_IP, MRT_PIM, (void *)&v, sizeof(v));
+.Ed
+.Pp
+.Bd -literal
+/* 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 ) .
+In case of PIM-SM, the PIM-Register virtual interface must be added
+as well.
+This can be accomplished by using the following options:
+.Bd -literal
+/* 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
+/* 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
+opening first a
+.Dq raw socket
+(see
+.Xr socket 2 ) ,
+with protocol value of
+.Dq IPPROTO_PIM :
+.Bd -literal
+/* IPv4 */
+int pim_s4;
+pim_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_PIM);
+.Ed
+.Bd -literal
+/* 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 ,
+.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
+.\"
+.Sh STANDARDS
+.\" XXX the PIM-SM number must be updated after RFC 2362 is
+.\" replaced by a new RFC by the end of year 2003 or so.
+The PIM-SM protocol is specified in RFC 2362 (to be replaced by
+.Xr draft-ietf-pim-sm-v2-new-* ) .
+The PIM-DM protocol is specified in
+.Xr draft-ietf-pim-dm-new-v2-* ) .
+.\"
+.Sh AUTHORS
+The original IPv4 PIM kernel support for IRIX and SunOS-4.x was
+implemented by Ahmed Helmy (USC and SGI).
+Later the code was ported to various BSD flavors and modified by
+George Edmond Eddy (Rusty) (ISI),
+Hitoshi Asaeda (WIDE Project), and Pavlin Radoslavov (USC/ISI and ICSI).
+The IPv6 PIM kernel support was implemented by the KAME project
+(http://www.kame.net), and was based on the IPv4 PIM kernel support.
+.Pp
+This manual page was written by Pavlin Radoslavov (ICSI).