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
Independent Multicast - Sparse Mode (PIM-SM) and Protocol

Independent
Multicast - Dense Mode (PIM-DM).

PIM-SM is a multicast routing protocol that can use the un

derlying unicast routing information base or a separate multicast-capa

ble routing
information base. It builds unidirectional shared trees

rooted at a Rendezvous Point (RP) per group, and optionally creates short

est-path trees
per source.

PIM-DM is a multicast routing protocol that uses the under

lying unicast
routing information base to flood multicast datagrams to all

multicast
routers. Prune messages are used to prevent future data

grams from propagating 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 routing and PIM pro

cessing in the
kernel (see SYNOPSIS about the kernel configuration op

tions), and must
run a PIM-SM or PIM-DM capable user-level process. From de

veloper'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 for

warding is
enabled in the kernel (see multicast(4)), one of the follow

ing 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):

/* 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 in

terfaces should
be added (see 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:

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

opening first
a ``raw socket'' (see socket(2)), with protocol value of IP

PROTO_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 re

ceive PIM packets: sendto(2), sendmsg(2), recvfrom(2), recvmsg(2).

SEE ALSO

getsockopt(2), recvfrom(2), recvmsg(2), sendmsg(2), send

to(2),
setsockopt(2), socket(2), inet(4), intro(4), ip(4), multi

cast(4)

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 speci

fied in
draft-ietf-pim-dm-new-v2-*).

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.

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

BSD September 4, 2003

BSD