|PIMD(8)||System Manager's Manual (smm)||PIMD(8)|
pimd — PIM-SM/SSM
v2 dynamic multicast routing daemon
pimd is a lightweight, stand-alone
PIM-SM/SSM v2 multicast routing daemon available under the free 3-clause BSD
license. This is the restored original from University of Southern
California, by Ahmed Helmy, Rusty Eddy and Pavlin Ivanov Radoslavov.
Protocol Independent Multicast - Sparse Mode (PIM-SM):
- maintains the traditional IP multicast service model of receiver-initiated membership;
- uses explicit joins that propagate hop-by-hop from members' directly connected routers toward the distribution tree.
- builds a shared multicast distribution tree centered at a Rendezvous Point (RP), and then builds source-specific trees for those sources whose data traffic warrants it.
- is not dependent on a specific unicast routing protocol; and
- uses soft-state mechanisms to adapt to underlying network conditions and group dynamics.
The robustness, flexibility, and scaling properties of this architecture make it well suited to large heterogeneous internetworks.
pimd originally only implemented RFC2362,
but since v2.3.0 is supporting more and more of RFC4601.
This program follows the usual UNIX command line syntax, with long options starting with two dashes (`-'). The options are as follows:
- Print a help message and exit.
- Specify an alternative configuration file, default
pimdcannot find its configuration file it will start up with fallback defaults, which include enabling both
- By default,
pimddaemonizes itself by detaching from the invoking terminal and forking to the background. However, if
pimdruns in the foreground of the starting terminal. If
-dis given without any argument
pimddefaults to debug all subystems.
Available subsystems are:
- Debug inbound/outbout packets
- Pruning operations, or pruned routes
- Routing messages
- Detailed routing information
- Neighbor gossip
- Debug routing cache
- Debug timeouts
- Show interface (VIF) debug messages
- Debug group memberships
- Multicast traceroute information
- Debug IGMP messages
- Debug ICMP messages
- Debug RSRR messages
- All PIM messages
- PIM routing messages
- PIM bootstrap router messages
- Detailed PIM debug
- Debug hello messages to/from neighbors
- Run in the foreground, do not detach from calling terminal and do not fork to background. Useful not only when debugging (above) but also when running under a process monitor like daemontools, runit, finit, or systemd.
- Tell a running pimd to reload its configuration. This is done by sending a SIGHUP to the PID listed in /var/run/pimd.pid. Depending on the capabilities of your user, you may need to be root to do this.
- This prevents
pimdfrom being activated on all interfaces by default. When this command line option is given, use `phyint IFNAME enable` to selectively activate PIM services on an interface.
- Tell a running
pimdto quit. Similar to
--reload-configbut this command sends SIGTERM. Depending on the capabilities of your user, you may need to be root to do this.
- Show state of VIFs and multicast routing tables. This is command sends
SIGUSR1 to a running
pimd, similar to
--reload-config.Depending on the capabilities of your user, you may need to be root to do this.
- Set log level to one of the following, default
The configuration is kept in the file /etc/pimd.conf. The file format is relatively free-form: whitespace (including newlines) is not significant. However, the order of some statements are important, see more below.
All <masklen> arguments to an IPv4 address, group or network can also be given in the alternative /CIDR format. E.g., <group>/<masklen>.
Here are the different configuration settings:
bsr-candidate[address | ifname] [
rp-candidate[address | ifname] [
rp-address<address> [<group-addr>[/<masklen> | masklen <masklen]
pimd will be activated on all
multicast capable interfaces. The
phyint setting and
command line option control this behaviour. More on the
phyint interface configuration setting below.
default-route-distance option has
nothing to do with the system default route, it is rather the default value
for the unicast routing protocol's administrative distance. It is used in
PIM Assert elections to determine upstream routers. Currently
pimd cannot obtain the admin distance and metric
from the unicast routing protocols, so a default routing protocol distance
(the RFC confusingly refers to this as metric
prefererence) may be configured. In a PIM Assert election, the router
advertising the lowest assert preference will be selected as the forwarder
and upstream router for the LAN. Setting 101 should be sufficiently high so
that asserts from Cisco or GateD routers are preferred over poor-little
It is reccommended that distances be set such that metrics are
never consulted. However, default routing metrics may also be set using the
default-route-metric option. (Again, this has
nothing to do with the system default route.) This item sets the cost for
sending data through this router. You want only PIM-SM data to go to this
daemon; so once again, a high value is recommended to prevent accidental
usage. The preferred default value is 1024. Both defaults can be overridden
per phyint, so learned routes, or PIM Asserts use the phyint's values.
Please also note that PIM Assert elections are not the same as the DR election. The PIM Assert election determines the active multicast forwarder, whereas the DR election determines the active PIM router.
Two settings for IGMP behavior are available:
igmp-querier-timeout which are similar, but very
different. The former controls the interval between IGMP querys when elected
as querier, the latter controls the timeout for the elected querier --
pimd decides to take over. In IGMP the lowest
numerical address in a LAN becomes the elected querier. Obviously these
settings must be handled with care. The RFC recommends that the querier
timeout is set to a robustness value times the query interval, plus have the
query response time. The pimd robustness value for IGMP is 3 and the default
query response time is 10 sec. Since pimd v2.3.0 the default query interval
is 12 sec, which makes the querier timeut default to 41 sec, but this is
rounded off to 42 to honor the late Douglas Adams.
The PIM Hello message interval can be tuned by changing the
hello-interval setting. Changing this value also
affects the hold-time value included in Hello messages. The hold-time value
is 3.5 times hello-interval. The default value for the Hello interval is 30
sec. Anything less than 30 sec is considered an "aggressive"
setting and is unsupported.
phyint option refers to a physical
interface and must come after
default-route-distance. Select the interface
either by its IP address or interface name
ifname (e.g. eth0). If you just want to activate this
interface with default values, you don't need to put anything else on the
line. However, there are some additional settings:
disable: Do not send PIM-SM traffic through this interface nor listen for PIM-SM traffic from this interface. Default: enable.
enable: Selectively enable which interfaces to send PIM-SM traffic through. Useful with the
-Ncommand line option.
igmpv2: Force interface to use IGMPv2, or
igmpv3: Use IGMPv3, this is the default since v2.3.0.
dr-priority<1-4294967294>: When there are multiple PIM routers on the same LAN the DR is usually elected based on the highest numerical IP address. This setting can be used to control the DR Priority option in PIM Hellow messages, which by default otherwise is 1. When the DR Priority option is advertised by all PIM routers on the same LAN the highest priority router wins the DR election, regardless of its IP. If any router does not advertise the DR Priority option, or the same priority is advertised by more than one router, the protocol falls back to using the IP address.
ttl-threshold<1-255>: The TTL threshold for multicast frames to be forwarded from this interface. Default: 1
distance<1-255>: Use this to override the
default-route-distance(101) on this
phyintin PIM Assert elections.
metric<1-1024>: The cost of sending data through this interface. Defaults to
default-route-metric(1024) if not assigned.
altnet<network/len>: Alternative host(s)/network(s) to accept as locally attached multicast sources on a given interface. If a phyint is attached to multiple IP subnets, describe each additional subnet with the altnet keyword.
scoped<network/len>: Optional scoping of multicast groups. This allows interfaces to be configured as an administrative boundary for the specified group(s). Multicast streams belonging to the scoped groups will not be forwarded.
phyint line per interface on this
router. If you don't do this,
pimd will either be
completely silent (if you provide the
line option), or simply assume that you want it to utilize all interfaces
using default settings.
bsr-candidate (CBSR) and
rp-candidate (CRP) settings are enabled in the
default configuration. Disabling them, by commenting them out in the config
file, for all PIM capable routers is a bad idea. When troubleshooting,
ensure at least one bootstrap router (BSR) and at least one rendez-vous
point (RP) in PIM-SM, is available. Both settings share the following
options, with priority being interpreted differently:
ifname: Optional local IPv4 address, or interface name to acquire address from. If both address and ifname is left out,
pimdwill default to the highest active IP address.
priority<0-255>: How important this router is compared to others. For CRP, the lower the value the more important the router is considered. For BSR it is of course the exact opposite: a higher value is preferred. If the priority is left out
pimdand Cisco IOS defaults to 0 for both, but the standard says 192 for RP.
time<10-16383>: The number of seconds to wait between advertising this CRP. The default value is 30 seconds. Use a lower value for faster convergence.
rp-candidateis the set of multicast groups that the CRP will advertise to other routers, if it wins an election:
group: A specific multicast group or network range this router will handle.
masklen: Optional number of groups, in prefix length format. Remember that a multicast address is a Class D and has a netmask of 240.0.0.0, which means its length is 4.
Multiple lines of
group-prefixmay be given, but max number of records supported in pimd is 255.
rp-address setting is for static
rendezvous point (RP) configurations. It defines the RP for a given group,
or range or groups. The argument can be either a unicast address or a
multicast group, with an optional group address and netmask. Default group
and netmask is 188.8.131.52/16.
Note: all static RP's
are announced with priority 1.
spt-threshold setting replaces two
older configuration settings,
switch_register_threshold. It controls the
switch-over from the shared tree to the shortest-path source tree. The
default is to do the switch-over after the first packet, but only after 100
seconds. If infinity is specified the shortest path
switch-over is disabled.
pimd responds to the following
pimd. The configuration file is reread every time this signal is evoked.
- Terminates execution gracefully (i.e. by sending good-bye messages to all neighboring routers).
- The same as TERM.
- Dumps the internal state of VIFs and multicast routing tables to
/var/run/pimd/pimd.dump. See also the
For convenience in sending signals,
writes its process ID to /var/run/pimd.pid upon
PIM-SM is described in, the now obsolete RFC2362, and the current RFC4601, with additions in RFC5059 and RFC5796.
The pages at USC, http://netweb.usc.edu/pim/, are unfortunately no longer available. The wiki pages at http://github.com/troglobit/pimd/, the new GitHub project, are an attempt to gather as much info as possible.
pimd was written by Ahmed Helmy, George
Edmond "Rusty" Eddy, and Pavlin Ivanov Radoslavov. PIM-SSM,
including full IGMPv3 support, added by Markus Veranen. With contributions
by many others.
This manual page was initially written by Antonín Král for the Debian GNU/Linux system, and then updated by Joachim Nilsson for the GitHub pimd project.
|March 3, 2016||Debian|