PIM-SM/SSM multicast routing for UNIX
pimd is a lightweight, stand-alone PIM-SM/SSM multicast routing daemon available under the free 3-clause BSD license. This is the restored original version from University of Southern California, by Ahmed Helmy, Rusty Eddy and Pavlin Ivanov Radoslavov.
Today pimd is maintained at GitHub. This is the preferred way to download releases, access the GIT sources, report bugs, and send patches or pull requests. Official release tarballs at the homepage and at the GitHub project's release directory.
pimd is primarily developed on Linux and should work as-is out of the box on all major distributions. Other UNIX variants (OpenBSD, NetBSD, FreeBSD, and Illumos) may also work, but are not officially supported.
pimd ships with a useful
pimctltool, compatible with all PIM daemons from the same family: pimd, pimd-dense, pim6sd. It can be a very helpful little tool when debugging and learning PIM setups. The pimctl API is documented in the file
src/ipc.c, in case you want to use
socatto talk to pimd over its UNIX domain socket:
echo "help" |socat - UNIX-CONNECT:/var/run/pimd.sock
For a summary of changes for each release, see the ChangeLog.
The configuration is kept in the file
/etc/pimd.conf, the order of the statements are in some cases important.
PIM-SM is a designed to be a protocol independent multicast routing protocol. As such it relies on unicast protocols like, e.g, OSPF, RIP, or static routing entries to figure out the reverse path to multicast sources. This information is necessary in setups with more than one route between a multicast sender and a receiver to figure out which PIM router should be the active forwarder.
However, pimd currently cannot retrieve the unicast routing distance (preference) and metric of routes from the system, not from the kernel nor a route manager like zebra. Hence, pimd currently needs to be setup statically on each router using the desired distance and metric for each active interface. If either the distance and/or the metric is missing in an interface configuration, the following two defaults will be used:
default-route-distance <1-255> default: 101 default-route-metric <1-1024> default: 1024
By default pimd starts up on all interfaces it can find, using the above defaults. To configure individual interfaces use:
You can reference the interface via either its local IPv4 address or its name, e.g., eth0. Some common interface settings are:
disable: Disable pimd on this interface, i.e., do not send or listen for PIM-SM traffic
dr-priority <1-4294967294>: The DR Priority option, sent in all all PIM Hello messages. Used instead of the IP address in all DR elections, if all PIM routers in LAN advertise it. The higher, the better, default 1.
distance <1-255>: The interface's admin distance value (also confusingly referred to as metric preference in the RFC) in PIM Assert messages. Used with
metricto elect the active multicast forwarding router. Defaults to
metric <1-1024>: The cost for traversing this router. Used with the
preferencevalue above. Defaults to
More interface settings are available, see the pimd(8) manual page for the full details.
The most notable feature of PIM-SM is that multicast is distributed from so called Rendezvous Points (RP). Each RP handles distribution of one or more multicast groups, pimd can be configured to advertise itself as a candidate RP
rp-candidate, and request to be static RP
rp-addressfor one or more multicast groups.
rp-address [[/ | masklen
Therp-addresssetting is the same as the Ciscoip pim rp-addresssetting to configure static Rendezvous Points. The first argument can be an IPv4 address or a multicast group address. The default group and prefix length is 184.108.40.206/16. Static RP's always have priority 1.rp-candidate [address | ifname] [interval <10-16383>] [priority <0-255>]
The Rendezvous Point candidate, or CRP, setting is the same as the Ciscoip pim rp-candidatesetting. Use it to control which interface that should be used in RP elections.
address | ifname: Optional local IPv4 address, or interface name to acquire address from. The default is to use the highest active IP address.
interval <10-16383>: The CRP advertisement interval, in seconds. Default: 60 seconds
priority <0-255>: How important this CRP is compared to others. The lower the value here, the more important the CRP. Like Cisco, pimd defaults to priority 0 when this is left out
In the CRP messages sent out by pimd, one or more multicast groups can be advertised using the following syntax.
group-prefix [| masklen ]
group-prefixsetting defines one multicast group and an optional mask length, which defaults to 16 if left out. A maximum of 255 multicast group prefix records is possible for the CRP.
To keep track of all Rendezvous Points in a PIM-SM domain there exists a feature called Bootstrap Router. The elected BSR in a PIM-SM domain periodically announces the RP set in Bootstrap messages. For details on PIM BSR operation, see RFC 5059.
bsr-candidate [address | ifname] [priority <0-255>] [interval <10-26214>]
The configuration of a Candidate BootStrap Router (CBSR) is very similar to that of CRP. If either the address or the interface name is left out
pimduses the highest active IP address. If the priority is left out,
pimd(like Cisco) defaults to priority 0. If the interval is left out, it defaults to the RFC value of 60 seconds.
To disable CRP and CBSR completely in
pimd, simply comment the two lines out from your
pimd.conf, and make sure
pimdcan find the file. Because if
pimdcannot find the file it will default to them enabled, with defaults listed in the
pimd.confincluded in the distribution.
In a PIM-SM domain there can be two, or more, paths from a designated router (DR) for a multicast sender to reach a receiver. When receivers begin joining multicast groups all data is received via the shared tree (RPT) from each Rendezvous Point (RP). This is often not an optimal route, so when the volume starts exceeding a configurable threshold, on either the last-hop router or the RP itself, the router will attempt to switch to the shortest path tree (SPT) from the multicast source to the receiver.
In versions of pimd prior to 2.2.0 this threshold was confusingly split in two different settings, one for the DR and one for the RP. These settings are still supported, for compatibility reasons and documented in the man-page, but it is strongly recommended to change to the new syntax instead:
spt-threshold [rate | packets | infinity] [interval <5-60>]
Only slightly different from the Cisco
ip pim spt-thresholdsetting, pimd can trigger a switch to SPT on a rate or number of packets and you can also tweak the poll interval. It's recommended to keep the interval in the tens of seconds, the default is 100 sec. The default threshold is set to zero packets, which will cause a switch over to the SPT after the first multicast packet is received.
# Interface eth0 is disabled, i.e., pimd will not run there. phyint eth0 disable
On this LAN we have a lower numeric IP than other PIM routers
but we want to take care of forwarding all PIM messages.
phyint eth1 dr-priority 10
Partake in BSR elections on eth1
Offer to be an RP for all of 220.127.116.11/4
rp-candidate eth1 group-prefix 18.104.22.168 masklen 4
This is the built-in defaults, switch to SPT on first packet
spt-threshold packets 0 interval 100
Having set up the configuration file, you are ready to run
pimd. As usual, it is recommended that you start it manually first, to make sure everything works as expected, before adding it to your system's startup scripts, with any startup flags it might need.
pimd [-hnrsv] [-f file] [-d subsys1[,...,subsysN]] [-l level]
-n: Run in foreground, with logs to stdout (for systemd and finit)
-s: Use syslog, default unless
-c file: Utilize the specified configuration file rather than the default,
-d [subsys1,...,subsysN]: Subsystems to enable debug for when running the daemon. Optional argument, if left out, all subsystems are enabled. Type
pimd -hfor a full list of subsystems
-l level: Log level, one of
debug. Default is
pimd -f /cfg/pimd.conf
When running multiple instances of pimd, make sure to use the
-I identargument, otherwise the PID and IPC socket files will be overwritten and the syslog will also be hard to follow. Note,
-Ichanges the default
.conffilename pimd looks for as well, a complete identity change.
Remember to set the correct log level when enabling debug messages, usually you need
-l debug, and
-sto force messages to syslog when running in the foreground (
pimd -d igmp_proto,pim_jp,kernel,pim_register -l debug -n -s
Check the TTL of incoming multicast
Remember, the TTL of the multicast stream must be >1 to be routed.
Check the Linux
Check the underlying unicast routing table
PIM is protocol independent so you must have a unicast route in both directions for
pimdto work. Use
pingto verify connectivitiy between multicast sender and receiver.
To see the virtual interface table, including neighboring PIM routers, and the multicast routing table:
pimctl show interfaces pimctl show neighbor pimctl show mrt ...
The default command is
pimctl show pim. To watch it continually (notice the
-cflag to watch(1) to tell it to interpret the ANSI escape sequences):
watch -cd pimctl
pimctl helpusage text for more commands (available only when a running PIM daemon is available), or the pimctl(8) man page.
Also worth mentioning,
pimdlogs important events to the system log, in particular at startup when it parses the
pimd is limited to the number of
MAXVIFSinterfaces listed in the kernel headers. In Linux see
To overcome this limitation, adjust the kernel
#defineto, e.g., 1280, and configure pimd
--with-max-vifs=1280. Please note, this has only been tested with Linux and will likely not work with other kernels!
With this many interfaces the kernel may run out of memory to let pimd to enable IGMP on all interfaces. In Linux, use sysctl to tweak the following settings:
sysctl -w net.core.optmem_max=327680 sysctl -w net.ipv4.igmp_max_memberships=5120
The configure script and Makefile supports de facto standard settings and environment variables such as
DESTDIR=for the install process. E.g., to install pimd to
/usrinstead of the default
/usr/local, but redirect install to a package directory in
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var make make DESTDIR=/tmp/pimd-2.3.2-1 install-strip
If you want to contribute, or simply just try out the latest but unreleased features, then you need to know a few things about the GNU build system:
configure.acand a per-directory
Makefile.amare key files
Makefile.inare generated from
Makefileis generated by
To build from GIT you first need to clone the repository and run the
autogen.shscript. This requires
autoconfto be installed on your system.
git clone https://github.com/troglobit/pimd.git cd pimd/ ./autogen.sh ./configure && make
GIT sources are a moving target and are not recommended for production systems, unless you know what you are doing!
git clone https://github.com/troglobit/pimd cd pimd
See the file CONTRIBUTING.md for further details.
Part of this program has been derived from mrouted. The mrouted program is covered by the 3-clause BSD license in the accompanying file named LICENSE.mrouted.
The mrouted program is COPYRIGHT 2002 by The Board of Trustees of Leland Stanford Junior University.