PIM(4)                    OpenBSD Programmer's Manual                   PIM(4)

NAME
     pim - Protocol Independent Multicast

SYNOPSIS
     options MROUTING
     options PIM

     #include <sys/types.h>
     #include <sys/socket.h>
     #include <netinet/in.h>
     #include <netinet/ip_mroute.h>
     #include <netinet/pim.h>

     int
     getsockopt(int s, IPPROTO_IP, MRT_PIM, void *optval, socklen_t *optlen);

     int
     setsockopt(int s, IPPROTO_IP, MRT_PIM, const void *optval,
           socklen_t optlen);

     int
     getsockopt(int s, IPPROTO_IPV6, MRT6_PIM, void *optval,
           socklen_t *optlen);

     int
     setsockopt(int s, IPPROTO_IPV6, MRT6_PIM, const void *optval,
           socklen_t optlen);

DESCRIPTION
     PIM is the common name for two multicast routing protocols: Protocol In-
     dependent Multicast - Sparse Mode (PIM-SM) and Protocol Independent Mul-
     ticast - Dense Mode (PIM-DM).

     PIM-SM is a multicast routing protocol that can use the underlying uni-
     cast routing information base or a separate multicast-capable routing in-
     formation base.  It builds unidirectional shared trees rooted at a Ren-
     dezvous Point (RP) per group, and optionally creates shortest-path trees
     per source.

     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 propa-
     gating to routers with no group membership information.

     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
     net.inet.ip.mforwarding sysctl(8) and PIM processing in the kernel (see
     SYNOPSIS for the correct kernel configuration option).  The user must al-
     so run a PIM-SM or PIM-DM capable user-level process.  From a developer's
     point of view, the programming guide described in the Programming Guide
     section should be used to control the PIM processing in the kernel.

   Programming Guide
     After a multicast routing socket is open and multicast forwarding is en-
     abled in the kernel (see multicast(4)), one of the following socket op-
     tions should be used to enable or disable PIM processing in the kernel.
     Note that those options require certain privilege (i.e., root privilege):

         /* IPv4 */
         int v = 1;        /* 1 to enable, or 0 to disable */
         setsockopt(mrouter_s4, IPPROTO_IP, MRT_PIM, (void *)&v, sizeof(v));

         /* IPv6 */
         int v = 1;        /* 1 to enable, or 0 to disable */
         setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_PIM, (void *)&v, sizeof(v));

     After PIM processing is enabled, the multicast-capable interfaces should
     be added (see multicast(4)).  For PIM-SM, the PIM-Register virtual inter-
     face must be added as well.  This can be accomplished by using the fol-
     lowing options:

           /* 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));

           /* 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));

     Sending or receiving of PIM packets can be accomplished by first opening
     a ``raw socket'' (see socket(2)), with protocol value of IPPROTO_PIM:

           /* IPv4 */
           int pim_s4;
           pim_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_PIM);

           /* IPv6 */
           int pim_s6;
           pim_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_PIM);

     Then the following system calls can be used to send or receive PIM pack-
     ets: sendto(2), sendmsg(2), recvfrom(2), and recvmsg(2).

SEE ALSO
     getsockopt(2), recvfrom(2), recvmsg(2), sendmsg(2), sendto(2),
     setsockopt(2), socket(2), inet(4), intro(4), ip(4), multicast(4),
     sysctl(8)

STANDARDS
     The PIM-SM protocol is specified in RFC 2362 (to be replaced by draft-
     ietf-pim-sm-v2-new-*).  The PIM-DM protocol is specified in RFC 3973.

AUTHORS
     The original IPv4 PIM kernel support for IRIX and SunOS-4.x was imple-
     mented by Ahmed Helmy (USC and SGI).  Later the code was ported to vari-
     ous 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.

     This manual page was written by Pavlin Radoslavov (ICSI).

OpenBSD 4.7                      May 31, 2007                                2
