PIM(4)

📦
version 15.1 · 2 versions
, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💖 PIM(4) — Protocol Independent Multicast 💖

okay so this one's from the Kernel Interfaces Manual, and it's literally about PIM, which is the common name for two whole multicast routing protocols: Protocol Independent Multicast - Sparse Mode (PIM-SM) and Protocol Independent Multicast - Dense Mode (PIM-DM). bestie, there are two of them. two. i'm obsessed.

✨ NAME ✨

pim — Protocol Independent Multicast (yes, both flavors, we love a dual-icon moment)

🎀 SYNOPSIS 🎀

first you gotta have the kernel option:

options MROUTING

then include these icons:

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

and here are the function signatures, exactly as they are, no cap:

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 🌸

okay so PIM is the common name for two multicast routing protocols — PIM-SM and PIM-DM — and they are not the same vibe at all.

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. like, it's giving organized, it's giving structured, it's giving main character energy.

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. it's the "just flood it and let them prune" vibe, honestly kinda chaotic but it works 💅

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 “SYNOPSIS” about the kernel configuration options), and must 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 enabled in the kernel (see 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). bestie, don't forget the root privilege, that's literally the vibe check 👑

IPv4:

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

IPv6:

/* 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)). 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:

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

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

IPv4:

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

IPv6:

/* 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 packets: sendto(2), sendmsg(2), recvfrom(2), recvmsg(2). slay.

🔥 SEE ALSO 🔥

🌈 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 draft-ietf-pim-dm-new-v2-*). yes there's a stray closing paren in the original, we keep it, no cap.

👑 AUTHORS 👑

shoutout to the icons who made this happen:

  • 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 (https://www.kame.net), and was based on the IPv4 PIM kernel support.
  • this manual page was written by Pavlin Radoslavov (ICSI).
💜 okay bestie that's the whole page. all the flags, all the structs, all the syscalls, all the drafts with their weird little asterisks, preserved with love. periodt. 💜

this iconic page comes from Debian, dated February 12, 2007, under the Kernel Interfaces Manual — mwah, thanks Debian, you ate 🫶✨💖

📦 where this page comes from