Provided by: pimd_2.3.1-2_amd64 
NAME
pimd — PIM-SM/SSM v2 dynamic multicast routing daemon
SYNOPSIS
pimd [-fhlNqr] [-c FILE] [-d [LEVEL[,LEVEL,...]] [-s LEVEL]
DESCRIPTION
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 version 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.
OPTIONS
This program follows the usual UNIX command line syntax, with long options starting with two dashes (`-').
The options are as follows:
-h, --help
Print a help message and exit.
-c, --config=FILE
Specify an alternative configuration file, instead of the default /etc/pimd.conf.
-d, --debug[=LEVEL[,LEVEL...]
By default, pimd daemonizes itself by detaching from the invoking terminal and forking to the
background. However, if -d, --debug or -f, --foreground is specified, pimd runs in the foreground
of the starting terminal and responds to signals. If -d is given with no argument, the debug level
defaults to igmp, cache, interface, groups, prunes, routes and peers.
Regardless of the debug level, pimd always writes warning and error messages to the system log
daemon. Debug levels have the following effects:
packet Debug inbound/outbout packets
prunes Pruning operations, or pruned routes
routes Routing messages
rtdetail Detailed routing information
peers Neighbor gossip
cache Debug routing cache
timeout Debug timeouts
interface Show interface (VIF) debug messages
groups Debug group memberships
mtrace Multicast traceroute information
igmp Debug IGMP messages
icmp Debug ICMP messages
rsrr Debug RSRR messages
pim All PIM messages
pim_routes PIM routing messages
pim_bsr PIM bootstrap router messages
pim_detail Detailed PIM debug
pim_hello Debug hello messages to/from neighbors
-f, --foreground
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.
-l, --reload-config
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.
-N, --disable-vifs
This prevents pimd from 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.
-q, --quit-daemon
Tell a running pimd to quit. Similar to -l, --reload-config but this command sends SIGTERM.
Depending on the capabilities of your user, you may need to be root to do this.
-r, --show-routes
Show state of VIFs and multicast routing tables. This is command sends SIGUSR1 to a running pimd,
similar to -l --reload-config. Depending on the capabilities of your user, you may need to be root
to do this.
-v, --version
Show pimd version
-s, --loglevel=LEVEL
Set syslog level to one of the following:
ALERT Action must be taken immediately
CRIT Critical conditions
ERR Error conditions
WARNING Warning conditions
NOTICE Normal but significant condition (Default)
INFO Informational
DEBUG Debug-level messages
CONFIGURATION
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:
default-route-distance <1-255>
default-route-metric <1-1024>
igmp-query-interval <1-65535>
igmp-querier-timeout <8-65535>
hello-interval <30-18724>
phyint <address | ifname>
[disable | enable] [igmpv2 | igmpv3]
[dr-priority <1-4294967294>]
[ttl-threshold <1-255>] [distance <1-255>] [metric <1-1024>]
[altnet <network> [/<masklen> | masklen <masklen>]]
[scoped <network> [/<masklen> | masklen <masklen>]]
bsr-candidate [address | ifname] [priority <number>]
rp-candidate [address | ifname] [priority <0-255>] [time <10-16384>]
group-prefix <group>[/<masklen> | masklen <masklen>]
...
group-prefix ...
rp-address <address> [<group-addr>[/<masklen> | masklen <masklen]
spt-threshold [rate <KBPS> | packets <NUM> | infinity] [interval <SEC>]
By default, pimd will be activated on all multicast capable interfaces. The phyint setting and the -N,
--disable-vifs command line option control this behaviour. More on the phyint interface configuration
setting below.
The 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 pimd.
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-query-interval and 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 -- before 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.
The phyint option refers to a physical interface and must come after default-route-metric and
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 -N command 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 phyint in 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.
Add one phyint line per interface on this router. If you don't do this, pimd will either be completely
silent (if you provide the -N command line option), or simply assume that you want it to utilize all
interfaces using default settings.
The bsr-candidate setting is similar to rp-candidate. Only difference is the lack of an interval time
option.
The rp-candidate setting refers to Candidate Rendezvous Point (CRP). It specifies which interface on this
machine should be included in RP elections:
• address | ifname: Optional local IPv4 address, or interface name to acquire address from. If both
address and ifname is left out, pimd will default to the highest active IP address.
• priority <0-255>: How important this CRP is compared to others. The lower the value here, the more
important the CRP. Default is 0 for pimd and Cisco IOS, but the standard says 192.
• time <10-16383>: The number of seconds to wait between advertising this CRP. The default value is
60 seconds.
The group-prefix sub-setting to rp-candidate is 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-prefix may be given, but max number of records supported in pimd is 255.
The 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 224.0.0.0/16. Note: all static RP's are
announced with priority 1.
The spt-threshold setting replaces two older configuration settings, switch_data_threshold and
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.
SIGNALS
pimd responds to the following signals:
HUP Restarts pimd. The configuration file is reread every time this signal is evoked.
TERM Terminates execution gracefully (i.e. by sending good-bye messages to all neighboring routers).
INT The same as TERM.
USR1 Dumps the internal state of VIFs and multicast routing tables to /var/run/pimd/pimd.dump. See also
the -r, --show-routes option above.
For convenience in sending signals, pimd writes its process ID to /var/run/pimd.pid upon startup.
FILES
/etc/pimd.conf
/var/run/pimd/pimd.dump
/var/run/pimd.pid
SEE ALSO
mrouted(8), smcroute(8), /usr/share/doc/pimd/
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.
AUTHORS
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.