NAME¶
pimd
—
PIM-SM/SSM v2 dynamic multicast routing daemon
SYNOPSIS¶
pimd |
[ -fhlNqr ]
[-c
FILE ]
[-d
[SYS[,SYS,...] ]
[-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 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.
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, default
/etc/pimd.conf. If
pimd
cannot find its configuration file
it will start up with fallback defaults, which include enabling both
bsr-candidate
and
rp-candidate
.
-d,
--debug[=SYS[,SYS...]
- 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. If -d
is given
without any argument pimd
defaults to
debug all subystems.
Available subsystems are:
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 log level to one of the following, default
notice
:
none
- Disable all logging
error
- 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:
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.
Both the
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:
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 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
pimd
and 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.
- 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.